Development#

This is documentation for developers working in quivr itself.

Quivr’s development environment is managed with Hatch. To work on quivr, you’ll need hatch installed on your system, whether in a virtualenv or globally.

Development tasks#

Hatch manages local dependency state and can run tasks. These are defined in pyproject.toml.

Development Tasks#

Command

Action

hatch run dev:format

auto-format all code to comply with Black.

hatch run dev:lint

run ruff to check for common errors.

hatch run dev:test

run the primary test suite.

hatch run dev:doctest

run the doctests, which are embedded in the docstrings.

hatch run dev:typecheck

run the typechecker for internal consistency, and to validate typing tests

hatch run dev:benchmark

run the benchmark suite.

hatch run test:all

run the full suite of all tests (lint, typecheck, test, and doctest) on all target Python versions using containers.

In addition, there are some tasks that are for building documentation:

Documentation Tasks#

Command

Action

hatch run docs:make-html

build the HTML documentation. It will be built in docs/build/html, relative to the repo root.

hatch run docs:open-html

open the HTML documentation in your browser.

hatch run docs:clean

remove the built HTML documentation.

hatch run docs:rebuild

clean and rebuild the HTML documentation.

Test Suites#

quivr has three sorts of tests:

  • Unit tests: These are defined in ./test and use pytest.

  • Doctests: These are embedded in the docstrings of the code itself. They verify that the code examples in the documentation are correct.

  • Type tests: These are defined in ./test/typing_tests and verify that the type annotations in the code pass mypy’s type checking.

In addition, there is a benchmark suite, defined in ./test as well, directly in the relevant Python unit test files. These are microbenchmarks that measure performance of narrow portions of the code using pytest-benchmark. These are not run by default, but can be run with hatch run benchmark.

Running tests against multiple Python Versions#

The hatch run test:all command runs all the tests against a matrix of supported Python versions. This thorough test can be run locally, but you’d need to have all the Python versions installed.

A good way to do that is with pyenv. You can install multiple versions - for example, to install Python 3.10 and 3.11:

pyenv install 3.10 3.11

Then, you need to make them available to the hatch program. Do that by running pyenv global to set the versions:

pyenv global 3.10 3.11

You should be good to go. hatch run test:all should run in all environments. If any are listed as “skipped,” you can pyenv install them, declare them in a pyenv global list, and try again.

Running tests against multiple Python Versions#

The hatch run test:all command runs all the tests against a matrix of supported Python versions. This thorough test can be run locally, but you’d need to have all the Python versions installed.

A good way to do that is with pyenv. You can install multiple versions - for example, to install Python 3.10 and 3.11:

pyenv install 3.10 3.11

Then, you need to make them available to the hatch program. Do that by running pyenv global to set the versions:

pyenv global 3.10 3.11

You should be good to go. hatch run test:all should run in all environments. If any are listed as “skipped,” you can pyenv install them, declare them in a pyenv global list, and try again.

Release Checklist#

Before a release, ensure tests pass and docs can build:

hatch run test:all
hatch run docs:make-html

To do a quivr release:

  1. On the main branch:

  2. Run hatch version $NEW_VERSION. This will update quivr/version.py.

  3. Update CHANGELOG.md to label the current “Unreleased” changes as $NEW_VERSION with the current date. Do a check of commits since the last release to be sure all significant changes are documented.

  4. Commit the above two changes with a commit message in the form Version $NEW_VERSION.

  5. Tag the commit with v$NEW_VERSION (eg “v1.2.3”, not “1.2.3”).

  6. Push the commit, as well as the new tag (git push && git push --tags).

  7. Run hatch build and then hatch publish to build and publish to PyPI.

Running tests against multiple Python Versions#

The hatch run test:all command runs all the tests against a matrix of supported Python versions. This thorough test can be run locally, but you’d need to have all the Python versions installed.

A good way to do that is with pyenv. You can install multiple versions - for example, to install Python 3.10 and 3.11:

pyenv install 3.10 3.11

Then, you need to make them available to the hatch program. Do that by running pyenv global to set the versions:

pyenv global 3.10 3.11

You should be good to go. hatch run test:all should run in all environments. If any are listed as “skipped,” you can pyenv install them, declare them in a pyenv global list, and try again.

Release Checklist#

Before a release, ensure tests pass and docs can build:

hatch run test:all
hatch run docs:make-html

To do a quivr release:

  1. On the main branch:

  2. Run hatch version $NEW_VERSION. This will update quivr/version.py.

  3. Update CHANGELOG.md to label the current “Unreleased” changes as $NEW_VERSION with the current date. Do a check of commits since the last release to be sure all significant changes are documented.

  4. Commit the above two changes with a commit message in the form Version $NEW_VERSION.

  5. Tag the commit with v$NEW_VERSION (eg “v1.2.3”, not “1.2.3”).

  6. Push the commit, as well as the new tag (git push && git push --tags).

  7. Run hatch build and then hatch publish to build and publish to PyPI.

Running tests against multiple Python Versions#

The hatch run test:all command runs all the tests against a matrix of supported Python versions. This thorough test can be run locally, but you’d need to have all the Python versions installed.

A good way to do that is with pyenv. You can install multiple versions - for example, to install Python 3.10 and 3.11:

pyenv install 3.10 3.11

Then, you need to make them available to the hatch program. Do that by running pyenv global to set the versions:

pyenv global 3.10 3.11

You should be good to go. hatch run test:all should run in all environments. If any are listed as “skipped,” you can pyenv install them, declare them in a pyenv global list, and try again.

Release Checklist#

Before a release, ensure tests pass and docs can build:

hatch run test:all
hatch run docs:make-html

To do a quivr release:

  1. On the main branch:

  2. Run hatch version $NEW_VERSION. This will update quivr/version.py.

  3. Update CHANGELOG.md to label the current “Unreleased” changes as $NEW_VERSION with the current date. Do a check of commits since the last release to be sure all significant changes are documented.

  4. Commit the above two changes with a commit message in the form Version $NEW_VERSION.

  5. Tag the commit with v$NEW_VERSION (eg “v1.2.3”, not “1.2.3”).

  6. Push the commit, as well as the new tag (git push && git push --tags).

  7. Run hatch build and then hatch publish to build and publish to PyPI.

Running tests against multiple Python Versions#

The hatch run test:all command runs all the tests against a matrix of supported Python versions. This thorough test can be run locally, but you’d need to have all the Python versions installed.

A good way to do that is with pyenv. You can install multiple versions - for example, to install Python 3.10 and 3.11:

pyenv install 3.10 3.11

Then, you need to make them available to the hatch program. Do that by running pyenv global to set the versions:

pyenv global 3.10 3.11

You should be good to go. hatch run test:all should run in all environments. If any are listed as “skipped,” you can pyenv install them, declare them in a pyenv global list, and try again.

Release Checklist#

Before a release, ensure tests pass and docs can build:

hatch run test:all
hatch run docs:make-html

To do a quivr release:

  1. On the main branch:

  2. Run hatch version $NEW_VERSION. This will update quivr/version.py.

  3. Update CHANGELOG.md to label the current “Unreleased” changes as $NEW_VERSION with the current date. Do a check of commits since the last release to be sure all significant changes are documented. Remember to update the list of links at the very bottom of the changelog.

  4. Commit the above two changes with a commit message in the form Version $NEW_VERSION.

  5. Tag the commit with v$NEW_VERSION (eg “v1.2.3”, not “1.2.3”).

  6. Push the commit, as well as the new tag (git push && git push --tags).

  7. Run hatch build and then hatch publish to build and publish to PyPI.