Development Guide

Setting up a development environment

It is recommended to conduct development of this library in a virtual environment.

To install the development dependencies, use:

pip install -r deps/dev-requirements.txt



almanac’s testing strategy is split up into two categories: documentation tests and unit tests. Documentation tests mainly serve to verify that the code examples in the Python docstrings and in the documentation site do not become out of date. This is a nice complement to the unit tests, which enforce the public contract of this framework.


Code examples are scattered throughout the framework’s docstrings, in the format expected by Python’s doctest module.

To test all of the doctests (across the library code and the documentation site sources), use:

pytest almanac/ docs/

Unit tests

Unit tests are written to be executed via pytest. To run all of the unit tests, use:

pytest tests/

To run a collection of unit tests, use something like:

pytest tests/

To run a single unit test, use something like:

pytest tests/ -k "test_prompt_str_customization"


All of the code in this framework is style-linted with flake8 and type-linted with mypy. An EditorConfig configuration file is also included in the root of this project’s repository to aid in style-conforming automatic formatting.

Running the linters is fairly straightforward:

flake8 .
mypy .


Release builds are performed using setuptools, with the extra layer of convenience provided by twine.

When it’s time to cut a release, use the following steps:

# Build the source tarball and wheel.
python bdist_wheel sdist

# Verify that PyPI will accept our upload.
twine check dist/*.whl dist/*.gz

# Upload to PyPI.
twine upload dist/*.whl dist/*.gz