SAMPIClyser ¶

Python library to help decoding and analysing data from a SAMPIC system

Free software: Zlib license

Running the software ¶

We will use a venv to isolate the SAMPIClyser python installation and dependencies from that of the system and other venvs. Create the venv with: python -m venv venv. Venv creation only needs to be done once and occasionally when you upgrade the python version installed on the system.

Before running any commands related to the SAMPIClyser, activate the venv with: source venv/bin/activate

Once you are finished, you may deactivate the venv with: deactivate

Dependencies & Installation ¶

There are two options, you can run the SAMPIClyser from source or from PyPI (Recommended).

From PyPI¶

Make sure you activate the venv first, then simply run the command: python -m pip install SAMPIClyser

From Source¶

Fetch the source from github, you may for instance clone the git repository to a local directory. Make sure the venv is activated, then install this application with all its dependencies by running this command from the source directory: python -m pip install .

Developer Dependencies ¶

If you are working on developing the code for SAMPIClyser you will need to follow the “Running the Software” instructions for setup and then for installing use the “From Source” instructions but instead of the install command in the “Dependencies” instructions, use the following command: python -m pip install -e .. Then install a few other dependencies which are only used in development:

python -m pip install --upgrade pytest
python -m pip install --upgrade pytest-cov
python -m pip install --upgrade pytest-mock
python -m pip install --upgrade pre-commit
python -m pip install --upgrade bump2version
python -m pip install --upgrade black
python -m pip install --upgrade flake8-pyproject
python -m pip install --upgrade isort
python -m pip install --upgrade build
python -m pip install --upgrade twine

Then install the pre-commit hooks so that things are ran automatically before any commit is done: pre-commit install.

Developer Info ¶

Tools ¶

pytest¶

We are using pytest to run unit tests on the software. See here for ideas on how to get started. Use the command pytest to run all the tests.

We use the pytest-cov plugin to get coverage reports from pytest. Use the command pytest --cov --cov-report term-missing to run all the tests and get a coverage report. Use the command pytest --cov --cov-report term-missing --cov-report html to get an html report with detailed information.

We use the pytest-mock plugin in order to use the mock class in our tests.

pre-commit¶

pre-commit may need to be installed in the global python environment for things to work correctly. This tool allows to setup hooks into the git workflow, in particular for the Pre-Commit Hook, allowing to run automated tests before committing code. This functionality is used to automatically run black, flake8 and isort before any commit is made, thus guaranteeing a consistent style and formatting for all committed code (according to these tools). If you want to run all the checks individually as if a commit were about to be made, you can use pre-commit run --all-files. You can find more information on pre-commit here.

bump2version¶

We are using bump2version to manage the version string of the software. bump2version will automatically create a commit and a tag with the version when you use it:

To increase the major version, use: bump2version major; for example 0.1.3 to 1.0.0
To increase the minor version, use: bump2version minor; for example 0.1.3 to 0.2.0
To increase the patch version, use: bump2version patch; for example 0.1.3 to 0.1.4

black¶

We are using black to automatically format the python code. To run black standalone use: black . in the root directory. You may also use black --check -v . to get a list of which changes would be made, without actually making them. More information on black can be found here.

flake8¶

We are using flake8 to check the code for style and syntax errors (i.e. a linter tool). The flake8-pyproject enables flake8 to read configuration from the pyproject.toml file, and pulls flake8 as a dependency. This is why flake8 is not explicitly installed. To run flake8 standalone, use: flake8 in the root directory. More information on flake8 can be found here. A list of all options and configuration for the toml file can be found here.

isort¶

We are using isort to automatically sort the include statements at the top of the python files. To run isort standalone use: isort . in the root directory. More information on isort can be found here.

build¶

The build tool is used to package the code for publishing on PyPI. Build the release with: python -m build

twine¶

The twine tool is used to upload the package to PyPI. Once the distribution files are generated with the build tool, then upload them with: python -m twine upload --repository testpypi dist/*

Github Workflows ¶

Currently there is a single github workflow which builds and publishes a properly tagged version of the repo onto PyPI. We plan to use other github workflows as our CI tools, to be added.

publish-to-test-pypi¶

This workflow publishes to PyPI a properly tagged commit of the repository. Some initial setup in needed on PyPI so that things run smoothly, but once running it should continue to function without intervention needed.

There are entry points as explained in: https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#declaring-project-metadata There is an entry point to run the binary conversion tool, for example: sampic-convert tool, use the help to see the options.