Development

Thank you for your interest in the development of pxwebpy!
This page explains how you can contribute. All improvements to code, documentation, and tests are welcome.

Setting up `uv` and the virtual environment

This project is set up to use uv to manage Python and dependencies. First, be sure you have uv installed.

# Install dependencies and set up the virtual environment
uv sync

For more details on how to use uv, head over to the uv docs.

Formatting

Code

ruff is used for linting and formatting, automatically executed in a pre-commit hook.

# Install the pre-commit hooks
uv run pre-commit install

To run ruff manually from the command line or editor, see the ruff documentation.

Docstrings

Follow the NumPy style guide when writing docstrings. This is important for being able to build the documentation.

Running tests

For fast iteration on specific tests, use uv run pytest:

uv run pytest -s tests/test_client.py # one test file
uv run pytest -s tests/test_client.py::test_call_raises_http_error # one specific test

To run the complete test suite across all supported Python versions, use nox:

uv run nox # for the entire suite
uv run nox -s tests # same thing, just being explicit about the session

To check test coverage:

uv run pytest --cov=pxweb # for terminal output
uv run pytest --cov=pxweb --cov-report=html # to get a report

Some tests utilize syrupy for snapshot testing to ensure consistency. If snapshots need to be updated:

uv run pytest --snapshot-update

Building the documentation

Documentation is built using quartodoc, thus you also need quarto installed on your machine if you wish to build the documentation locally. This is usually a good idea to check that the output looks as expected. The documentation is automatically built and published upon each release.

With quarto installed the documentation can be rendered:

cd docs
uv run quartodoc build
uv run quarto render

The rendered output is found in the folder called _site.

Submitting changes

When you’re ready to contribute:

Clone the repository and create a new branch for your changes.
Ensure tests pass and code is properly formatted.
Open a pull request to the main branch.

Setting up uv and the virtual environment