---
last_review: "2026-05-07"
last_reviewer: "s.kaviani"
documented_code: [ ]
---

```{tags} developer, how-to
```

% Issue: https://gitlab.indiscale.com/caosdb/src/linkahead-docs/-/work_items/103

# PyLinkAhead Development Guide

This guide covers setting up a development environment, running tests, checking code quality, and
building the documentation for [PyLinkAhead](https://gitlab.com/linkahead/linkahead-pylib).

## 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:

```sh
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:

```sh
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:

```sh
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:

```sh
make doc
```

### References

- [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
- [Google Style Python Docstrings 2nd reference](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings)
- [References to other documentation](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#role-external)

## Troubleshooting

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

```sh
pip install -e .
```