Developer Manual
Shareloc is an open source software : don’t hesitate to hack it and contribute !
Please go to the GitHub repository for source code.
Read also Shareloc Contribution guide with LICENCE
You need also to complete, sign and email to cars [at] cnes [dot] fr the Individual Contributor Licence Agrement or Corporate Contributor Licence Agrement.
Contact: cars AT cnes.fr
Developer Install
Install from source procedure is followed.
The detailed development install method is described in the Makefile
Particularly, it uses the following pip editable install:
pip install -e .[dev]
With this pip install mode, source code modifications directly impacts Shareloc code.
Coding guide
Here are some rules to apply when developing a new functionality:
Comments: Include a comments ratio high enough and use explicit variables names. A comment by code block of several lines is necessary to explain a new functionality.
Test: Each new functionality shall have a corresponding test in its module’s test file. This test shall, if possible, check the function’s outputs and the corresponding degraded cases.
Documentation: All functions shall be documented (object, parameters, return values).
Use type hints: Use the type hints provided by the typing python module.
Use doctype: Follow sphinx default doctype for automatic API
Quality code: Correct project quality code errors with pre-commit automatic workflow (see below)
Factorization: Factorize the code as much as possible. The command line tools shall only include the main workflow and rely on the shareloc python modules.
Be careful with user interface upgrade: If major modifications of the user interface or of the tool’s behaviour are done, update the user documentation (and the notebooks if necessary).
Logging and no print: The usage of the print() function is forbidden: use the logging python standard module instead.
Limit classes: If possible, limit the use of classes as much as possible and opt for a functional approach. The classes are reserved for data modelling if it is impossible to do so using xarray and for the good level of modularity.
Limit new dependencies: Do not add new dependencies unless it is absolutely necessary, and only if it has a permissive license.
Pre-commit validation
A pre-commit validation is installed with code quality tools (see below). It is installed automatically by make install-dev command.
Here is the way to install it manually:
$ pre-commit install
This installs the pre-commit hook in .git/hooks/pre-commit from .pre-commit-config.yaml file configuration.
It is possible to test pre-commit before commiting:
$ pre-commit run --all-files # Run all hooks on all files
$ pre-commit run --files shareloc/__init__.py # Run all hooks on one file
$ pre-commit run pylint # Run only pylint hook
Code quality
Shareloc uses Black, and Pylint quality code checking.
Use the following command in shareloc virtualenv to check the code with these tools:
$ make lint
Use the following command to format the code with black:
$ make format
Black
Black is a quick and deterministic code formatter to help focus on the content.
Shareloc black
configuration is done in pyproject.toml
If necessary, Black doesn’t reformat blocks that start with “# fmt: off” and end with # fmt: on, or lines that ends with “# fmt: skip”. “# fmt: on/off” have to be on the same level of indentation.
Black manual usage examples:
$ cd SHARELOC_HOME
$ black --check shareloc tests # Check code with black with no modifications
$ black --diff shareloc tests # Show black diff modifications
$ black shareloc tests # Apply modifications
Pylint
Pylint is a global linting tool which helps to have many information on source code.
shareloc pylint
configuration is done in dedicated .pylintrc file.
Pylint messages can be avoided (in particular cases !) adding “# pylint: disable=error-message-name” in the file or line. Look at examples in source code.
Pylint manual usage examples:
$ cd SHARELOC_HOME
$ pylint tests shareloc # Run all pylint tests
$ pylint --list-msgs # Get pylint detailed errors informations
Tests
Shareloc includes a set of tests executed with pytest tool.
To launch tests:
make test
Advanced testing
To execute the tests manually, use pytest
at the Shareloc projects’s root (after initializing the environment):
$ python -m pytest
To run only the unit tests:
$ cd shareloc/
$ pytest -m unit_tests
It is possible to obtain the code coverage level of the tests by installing the pytest-cov
module and use the --cov
option.
$ cd shareloc/
$ python -m pytest --cov=shareloc
It is also possible to execute only a specific part of the test, either by indicating the test file to run:
$ cd shareloc/
$ python -m pytest tests/test_triangulation.py
Or by using the -k
option which will execute the tests which names contain the option’s value:
$ cd shareloc/
$ python -m pytest -k triangulation
By default, pytest
does not display the traces generated by the tests but only the tests’ status (passed or failed). To get all traces, the following options have to be added to the command line (which can be combined with the previous options):
$ cd shareloc/
$ python -m pytest -s -o log_cli=true -o log_cli_level=INFO