Getting Started Developing

This document is a brief overview of the various parts of the project and the development process. For specific commands and related information see the development workflow.

Software Development Practices

The overall structure of the project is

Main directory: general project items
docs: location of the development documentation
examples: example usage and other instructional items
src: code for the apps, tools, library, and associate modules
sphinx: files used to generate the documentation
tests: tests for code
venvs: directory where virtual environments should be placed so that they are not committed to the repository

Test Driven Development

The main development practice used is a test driven development practice. New features are developed with the development of unit tests that the new code needs to pass. These tests are located within the tests directory and may reside is a sub-directory depending on the code organization.

As the feature evolves, the code (and corresponding tests) are refactored to better achieve the goal of the new feature. This is results in updated tests along with new tests. These tests are the used for regression testing as new features are developed. The following command can be used to run all tests from project root directory:

uv run pytest

It is expected that all tests will pass before a feature is completed or a release is made. Configuration for this tool is in pyproject.toml located in the project root directory.

Static Code Analysis and Formatting

In order to improve and maintain the code, static code analysis is used. The aim is to address all of the issues identified without using an ignore statement.

Another factor associated with the code improvement and maintenance is the format or readability of the code. By having a consistent format for the code, it makes reviewing and understanding the intention of the code easier.

On rare occasions it might be necessary to ignore a message associated with a line. When this is needed include comments in the code to explain the reason for ignoring the message. Ignoring entire files should be avoided.

Ruff

The tool that is used in this project for static code analysis and formatting is ruff. The following command can be used to analysis the code in the project

uv run ruff check .

Adding the --fix flag will automatically fix the errors that it is able to fix

uv run ruff check . --fix

To check the fomat of the code the following command can be used

uv run ruff format . --check

Removing the --check flag will automatically fix the errors that it can

uv run ruff format .

The configuration for this tool is in pyproject.toml located in the project root directory.

Code Coverage

The aim of the testing is to have tests covering 100% of the library code, but that is sometimes difficult to achieve. Especially when there are errors that are hard to replicate but should be handled. To collect the default code coverage data for the project use the following command:

uv run coverage run

Since each individual test can be executed on its own using pytest, the following command can be used to collect code coverage data from a particular test:

uv run coverage run -m pytest {pytest-file-with-path}

To get a text based report of the code coverage use the following command:

uv run coverage report -m

This produces a text based coverage report in the console.

To get an HTML version of the coverage report use the following command:

uv run coverage html

This generates a report in HTML format that can be found in htmlcov/index.html. The configuration for code coverage is in pyproject.toml located in the project root directory.

Type Checking

The aim for this project is to have type-hinting throughout the code to help developers know what types of data are expected and to limit the the introduction of bugs caused by passing invalid data types. Typing errors identified should be corrected before committing code. However, some libraries, such as numpy and scipy, may create spurious errors. Whenever an error message is ignored, comments need to be included explaining the reason for ignoring the message.

Mypy

One static typing tool used to check this project is mypy. To perform type checking for the entire project use the following command:

uv run mypy

If only a specific directory or file is to be checked that the path (and filename, if desired) can be passed as an argument, such as

uv run mypy ./examples

The configuration for code coverage is in pyproject.toml located in the project root directory.

BasedPyright

Support for BasedPyright, a fork of pyright, is also provided. This is to improve the integration of type checking in VSCodium with the BasedPyright extension, however the command line version of BasedPyright can also be used with the following command:

uv run basedpyright

The configuration for code coverage is in pyproject.toml located in the project root directory.

Continuous-Integration Testing

Several tests/checks are run on commits to the project repository, via workflows, to alert the developers of any problems that might be introduced by the commit. To check that these checks are going pass, use the following command to make sure everything is passing:

./scripts/run_checks.sh

This will run the entire pytest suite for the version of python uv is using. It will also go through the code analysis, code coverage, and type checking steps mentioned above.

Documentation

The documentation for this project is generated using sphinx along with MyST for markdown parsing. The Autodoc sphinx extension is used to get the docstrings from the code and convert them into API documentation.

The actual documentation files reside in the docs directory. The documentation is first built in the sphinx directory. To build the documentation use the following commands:

./scripts/build_docs.sh

Note that the HTML documentation is built in the sphinx/build/html/ directory. These are the pages that will be posted on the project’s documentation page. The configuration for this is in conf.py located in sphinx/source/ directory.