Quick Start

1-Click-Demo

Requirements: Conda (or equivalent), bash

$ bash 1-click-demo.sh

This serves as a setup script that also runs the main functionality of LapsPython in a virtual environment. It executes the following steps:

  1. Create and activate a Conda environment lapspython running on Python 3.7

  2. Install all LAPS requirements and used dev packages in a local Pipenv environment

  3. Run CI scripts (see Section Continuous Integration for detailed information)

    • Linting

    • Static Typechecking

    • Unit Tests

  4. Run a demo program launching the LapsPython pipeline for LAPS checkpoints in the re2 domain in Python mode and in R mode

Section Manual Installation describes this process as well as design decisions in more detail. Delete the Pipenv environment (~1.8 GB) by removing the contents of LapsPython/.venv/. Delete the Conda environment (~218 MB) by running

$ conda env remove --name lapspython

Manual Installation

If you do not want to use the recommended demo script, you can install the requirements manually in a Python 3.7 environment of your choice (here: lapspython):

(lapspython) $ git submodule init
(lapspython) $ git submodule update
(lapspython) $ conda install swig pipenv
(lapspython) $ pipenv sync

The pipenv sync command installs all Python modules required by LAPS locally in LapsPython/.venv/, as well as uniplot and the dev packages used in Section Continuous Integration.

The demo program can then be run through Pipenv:

(lapspython) $ pipenv run demo.py

Using Pipenv is recommended and the only verified way to get LapsPython running, since the portable Pipfile.lock allows to reproduce the exact virtual environment used on my Ubuntu 20.04 machine. If you do not want to use Pipenv, requirements.txt and requirements-dev.txt are provided and can be installed by running

(lapspython) $ pip install -r requirements.txt
(lapspython) $ pip install -r requirements-dev.txt

If you do not want to use Conda, swig needs to be installed through a package manger such as apt-get, which might require superuser rights.

Continuous Integration

You can run the following Pipenv scripts to execute the CI workflows also used by Github upon pushs and pull requests.

(lapspython) $ pipenv run tests

This script runs unit tests implemented with pytest. In addition, it uses pytest-cov to generate a coverage report which will then be printed to the terminal and stored as HTML here as part of the documentation.

(lapspython) $ pipenv run typechecks

This script runs static typechecks using Mypy.

(lapspython) $ pipenv run linting

This script runs the PEP-8 compliant linter Flake8 with a large selection of extensions enforcing stricter conventions in compliance with modern Python standards, simplifying complex code, as well as preventing bugs and security issues.

(lapspython) $ pipenv run sphinx

This script rebuilds the documentation using Sphinx. The built documentation can be deployed to GitHub Pages using the bash script git-deploy-docs.sh. These two manual steps reproduce an automatic workflow which is deactivated due to missing permissions of the github-actions bot but can be found in the Sphinx documentation.