Contributing

Contributions to the project are greatly appreciated.

Bugs and suggestions

You may submit an issue to the Gitea repository to warn of any bugs, ask for new features, or ask any questions that are not answered in this documentation.

When reporting a bug, do not forget to put in your version of Python and your version of pylspci. This will greatly help when troubleshooting, as most errors often come from version incompatibilities.

Development

Setup

You will need a virtual envionment to work properly. virtualenvwrapper is recommended:

git clone https://tildegit.org/lucidiot/pylspci.git
cd pylspci
mkvirtualenv -a . pylspci
pip install -e .[dev]

This will clone the repository, create a virtual environment named pylspci, then tell pip to let the package be editable (-e). The [dev] suffix adds the extra requirements useful for development.

Unit tests

Unit tests use the standard unittest package; you may run them using the standard setup.py command:

./setup.py test

Tests coverage

I aim for 100% coverage on all of my Python packages whenever I add unit tests to them; this package is no exception. CI checks use the coverage Python package to get coverage statistics. To get test coverage data locally, run:

coverage run setup.py test

You may then get a short coverage summary in your terminal:

coverage report

Or generate an HTML report in a htmlcov folder, which can be browsed offline using your favorite web browser and shows line by line coverage:

coverage html

If you are having issues reaching 100% coverage, try to still add some tests, and mention your issues when creating a pull request to the Gitea repository.

Linting

The source code follows the PEP 8 code style and performs CI checks using the flake8 tool. To perform the same checks locally, run flake8 on the root directory of this repository.

Type checking

The source code uses PEP 484 type hints and type checking is performed in CI using mypy. To run those checks locally, run mypy . on the root directory of this repository.

Documentation

The documentation you are reading is generated by the Sphinx tool. The text files that hold the documentation’s contents are written in reStructuredText and are available under the /docs folder of the Gitea repository. They are also subject to linting using the doc8 tool.