Python Guidelines and Coding style

Template code and examples for python project respecting the PEP8 coding style.

Quick start

List of steps to follow to adapt the template to your project.

1. Make your repo with "Use this template" button
2. Clone the new repo
3. [Recommended] Make a virtual environment
4. [Optional] Set up git lfs and .gitattributes
5. Activate pre-commit hook

./scripts/setup_git_hooks.sh

6. Configure visual studio

./scripts/setup_vscode_extensions.sh
./scripts/setup_vscode_config.sh

7. Install dev tools

pip install -e .[dev]

8. Adapt workflow and bagdes links to this repo

Configuration

Installation

Dependencies are detailed in the setup.cfg file. To install this package locally, run:

pip install -e .[dev]

Include [dev] for optional development tools.

The dependencies are listed in the setup.cfg file and will be installed if you install this package locally with:

pip install -e .[dev]

use [dev] for optional development tools.

Once this is done, you should be able to import the Python package anywhere on your system with:

import example

An exemple executable is also installed

example_entry_point

git

A .gitignore file ensures that the Python temporary files are not committed. It is adapted from here.

git LFS can be configured to manage all non-script files (3D models, deep learning models, images, etc.). The list of files is defined in gitattributes_example. If you wish to utilize LFS, rename this file to .gitattributes and then run git lfs install. It's also a good practice to maintain another repository as a submodule containing all the data.

A git hook can be set up to automatically check for PEP8 compliance before committing. Refer to scripts/git_hooks. Installing this is recommended as the GitHub workflows will perform the same checks. The script ./scripts/setup_git_hooks.sh will do this for you.

IDE - Linting

TL;DR Use ./scripts/setup_vscode_extensions.sh and ./scripts/setup_vscode_config.sh

Visual Studio Code is the recommended IDE. Ensure you have the Python extension installed and configure VS Code to auto-format your code using black.

isort verifies the order of Python imports. Set up VS Code to handle this automatically.

Flake8 will conduct additional checks. Choose flake8 as the linter for VS Code. Errors will be directly highlighted within the code.

Lastly, mypy will perform static type checking. In this guide, it's set to run in strict mode. Feel free to adjust the constraints if they don't align with your project's needs.

These tools are configured in the setup.cfg and pyproject.toml files. Their versions are predefined to prevent discrepancies between local and remote checks. It's advisable to keep them updated.

A code not compliant with PEP8 guidelines will not be merged.

Workflow

Branches

The git workflow is based on gitflow:

The default branch is develop, which serves as the working branch. main is reserved solely for stable code (releases). Both of these branches are protected, meaning direct pushes are disallowed. All new development MUST commence in a feature branch, derived from develop, and then be merged back into develop via a pull request. Once the code is deemed stable, the develop branch can also be merged into main through another pull request.

Issues

The issue system is a great tool to track problem, bugs, new features, etc. Commits and branches can be linked to a feature. Thus, before any development, a new issue MUST be created.

Procedure

1. Create an issue with the New Issue button. Document the problem as much as possible (images, url, ...)
2. Create a new branch. The easiest way is to do it directly from the issue. Thus, all branch names will be consistent, and the PR will directly close the issue.
3. Checkout your branch locally:

git fetch origin
git checkout <branch-name>

4. Work in the local branch and commit often. Each commit must be formatted as

<tag> #<issue number> : <message>

With tag being fix, bug or any label from the issue system, issue number the number of the issue, and message the mandatory message associated to the commit. Issue number is important so github can link the commit to the issue.

5. Create unit test to validate the new code (see below).

6. When the work is implemented, create a pull request. Easiest way is to do it from the branch page of the repo.

7. At the PR creation, unit tests will be computed and result reported. The branch will not be merged until they pass. Besides, the project is configured so a developer cannot merge his/her own code. An external review is mandatory.

8. Merge is completed, go to step 1.

Unit tests and test coverage

Unit tests must be written to ensure code robustness. Pytest is the recommended tool. Examples are provided in the tests folder.

It is recommended to have at least 90% of the code tested. The coverage package provide this metric.

The developer must run the test locally before committing any new code. Make sure that pytest and coverage are installed and run at the root level:

coverage run -m pytest

Then, if all tests are sucessful:

coverage report

These tests are automatically performed by a github action when a pull request is created.

Note that when creating a new repo from this template, you will need to first configure the Make badge action in the pytest.yml file. Follow those instructions if you don't have a gist secret and id yet.

Coding style

The main guidelines for the coding style is defined by PEP8. You can directly refer to the examples in the code.

Specific choices are detailed in dedicated document:

• for the mathematical notation please refer to Coding convention for Maths