Developer Guide¶

Git Workflow¶

You should use a forking workflow to develop pwfdf-api. In brief, you should make a fork of the official repository, and then create merge requests from the fork to the main branch of the official repository. These requests will then be reviewed before merging.

Installation¶

Prerequisites

The pwfdf-api requires Python 3.10+, and these instructions also require git.

We recommend using poetry to install pwfdf-api. This will provide various command line scripts useful for developing the project.

You can install poetry using:

pip install poetry

and read also the poetry documentation for alternative installation instructions.

Next, clone your fork of the project and navigate to the cloned repository. Then, use:

poetry install --with dev

which will install pwfdf-api and various development libraries.

Formatting¶

This project uses isort and black to format the code. You can apply these formatters using:

poe format

This should format the code within the pwfdf-api and tests directories. We also note that many IDEs include tools to automatically apply these formats.

You can also use:

poe lint

to verify that all code is formatted correctly. The Gitlab Pipeline requires that this check passes before code can be merged.

Testing¶

This project uses the pytest framework to implement tests. Before adding new code, the Gitlab Pipeline requires:

All tests passing, and
100% test coverage

So as a rule, all new code should include accompanying tests. The tests should follow a parallel structure to the pwfdf-api package, and the tests for a given module should be named test_<module>.py or test_<folder>_<module>.py in the case of duplicate module names.

Within a test module, multiple tests for the same function should be grouped into a class. Test class names should use capitalized camel-case. Underscores are discouraged, except when needed to distinguish between public and private routines with the same name. Individual tests should be named using standard Python snakecase (lowercase separated by underscores).

Note that you can check the status of the tests using:

poe tests

Documentation¶

The documentation is built using sphinx with the furo theme. The content is written in reStructuredText Markup (reST). You can find a nice introduction to reST in the sphinx documentation, and the full documentation is here: reST Specification.

The docs use the sphinx_design extension to enable dropdowns and tabbed panels within the content. The final website is deployed using Gitlab Pages via a manual job in the Gitlab Pipeline. You must trigger this job manually to deploy new docs.

You can build the docs locally using:

poe docs

This will create the documentation HTML pages within the public folder of the repository. You can open these docs in a browser using:

poe open-docs

Gitlab Pipeline¶

The Gitlab pipeline requires that:

Code dependencies pass a security check,
All code is formatted correctly, and
The tests pass with 100% coverage

You can mimic the pipeline using:

poe audit
poe lint
poe tests

The docs are deployed via a manual pipeline job. Also, tagging a commit will trigger a pipeline job that will build a distribution package and upload the distribution to the project package registry.

Scripts¶

Development scripts are available via the poethepoet interface, and are defined in pyproject.toml.

The following table provides a complete list of available scripts:

Script Name	Description
`audit`	Checks dependencies for security vulnerabilities
`update`	Deletes `poetry.lock` and reinstalls the project
`format`	Applies formatters to `pwfdf-api` and `tests`
`lint`	Checks that `pwfdf-api` and `tests` are formatted correctly
`tests`	Runs tests and requires 100% coverage
`webtests`	Runs tests that make live web requests
`coverage`	Prints the coverage report from the tests
`htmlcov`	Builds an HTML coverage report and opens in a browser
`docs`	Rebuilds the docs locally
`open-docs`	Opens locally built docs in a web browser