Tags: developer, how-to

PyLinkAhead Development Guide#

This guide covers setting up a development environment, running tests, checking code quality, and building the documentation for PyLinkAhead.

Prerequisites#

  • Python 3.10 or later

  • The PyLinkAhead source code checked out locally

  • tox installed: pip install tox

All commands below are run from the root of the PyLinkAhead repository.

Setup#

Create a virtual environment and install the package in editable mode with all development dependencies:

python3 -m venv venv
source venv/bin/activate  # on Windows: venv\Scripts\activate
pip install -e ".[all]"

The all extra installs test, mypy, and keyring dependencies. To install only what is needed for running tests:

pip install -e ".[test]"

Run Unit Tests#

  • Run all tests: tox or make unittest

  • Run a specific test file: e.g. tox -- unittests/test_schema.py

  • Run a specific test function: e.g. tox -- unittests/test_schema.py::test_config_files

  • Run directly with pytest: pytest .

Code Quality#

Run all code quality checks at once:

make check

This runs:

  • make style: pycodestyle style checks

  • make lint: pylint static analysis

  • make mypy: mypy type checking

Run these before submitting a merge request.

Documentation#

We use Sphinx to build the documentation. Docstrings in the code should follow the Google style guide (see links below).

Build the documentation into build/ with:

make doc

References#

Troubleshooting#

If the client is to be executed directly from the src/ folder, install it in editable mode first:

pip install -e .