Additional Development Info

This repository is Python-based and uses:

uv for dependency/environment workflows
pytest for tests
mypy and basedpyright for type checking
ruff for linting, static code analysis, and formatting
coverage.py for coverage reporting
Codeberg for git hosting and CI services
sphinx + MyST + Autodoc for documentation generation

We follow the Style Guide for Python Code, PEP 8. Code should should produce no warning when analyzed by any of the above tools to help ensure the quality of the code. These should be checked before committing code.

Code of Conduct Reminder

This project is governed by the Contributor Covenant Code of Conduct (v3.0). By participating, you agree to uphold it. Please see the code of conduct for details and reporting instructions.

Configuration is consolidated into pyproject.toml.

Versioning

For this project, the SemVer versioning system is used. Each version should be tagged in the repository as a release.

Prerequisites

uv installed
Git

Various Development Tasks

Below are some useful development tasks that might be of value.

Clone

git clone https://codeberg.org/BuffaloHerd/BuffaloExample.git
cd BuffaloExample

Running the standard checks

There is a script that will run the various tests and checks on the default python version:

scripts/run_checks.sh

There is a script that will run the tests on all supported versions of python:

scripts/run_test_matrix.sh

Make sure both scripts produce no errors or warnings.

Running tests (pytest)

Basic run:

uv run pytest

Run with a specific version of python (X.Y):

uv run --python X.Y -m pytest

Quiet:

uv run pytest -q

Run a subset:

uv run pytest -k "keyword"

Notes:

pytest is configured in pyproject.toml under [tool.pytest.ini_options].
pythonpath = "src" is set there to support the src/ layout.

Coverage

Along with running the tests, the project uses code coverage to track how much of the code base is being tested.

To get a code coverage report:

uv run coverage run -m pytest
uv run coverage report -m

Notes on type checking

This repo uses strict settings.

Currently both mypy and basedpyright are used for type checking.
Their settings are in pyproject.toml under [tool.mypy] and [tool.basedpyright], respectively.
Make sure all new code src/examples/tests/etc. are passing these checkers.

Style and lint

Ruff settings are in pyproject.toml under [tool.ruff.*]
max-line-length = 80 is enforced
Docstrings need to be present for modules, classes, methods, functions, etc.

Building the documentation

There is a script that builds the sphinx documentation:

scripts/build_docs.sh

Making changes

Recommended workflow:

Create a branch:

git checkout -b feature/short-description

Make edits in small commits with clear messages.
Run at least:

scripts/run_checks.sh
scripts/run_test_matrix.sh
scripts/build_docs.sh

Open a pull request on Codeberg.

See contributing for the full forking/PR workflow.