Contributing#

Contributors and contributions are welcome. Please read these guidelines first.

Git #

The project homepage is on GitHub.

Contributors can open pull requests from a fork targeting the parent main branch. But it may be a good first step to create an issue or open a discussion topic.

Repo #

Setting up the project should be straightforward once you have cloned the repository. A minimum of Python 3.11 is required (see requires-python in pyproject.toml).

To run examples or tests you will need an API key from the Companies House developer portal.

Dependencies #

Runtime dependencies are defined in the [project] section of pyproject.toml. At the time of writing these are:

  • httpx for asynchronous HTTP communication.

  • pydantic for data validation and typed models.

Development and tooling dependencies are specified under [tool.pdm.dev-dependencies] in the project TOML.

Tests #

Tests are located in the tests folder and can be run directly with pytest or via helper scripts in the bin/ directory:

  • bin/test.sh - run the full test suite with coverage reporting (automatically injects API key from 1Password).

  • bin/autoformat.sh - apply Ruff formatting and autofix lint issues where possible.

  • bin/run.sh <command> - run any command with API key automatically injected from 1Password.

Documentation #

The documentation is written in reStructuredText and built with Sphinx.

HTML documentation is built locally with:

pdm run sphinx-build -b html docs dist/docs/html

which builds the documentation and outputs HTML into dist/docs/html.

The Sphinx theme in use is pydata-sphinx-theme.

CI #

The CI workflows are defined here and there is also a separate CodeQL workflow.