Notes for contributors

Docs

We use MkDocs, which is make-based (hooray!) I recommend at least the quick start.

First of all review the docs right from your dev machine:

pip install -U mkdocs mkdocs-material
mkdocs serve

Once you've made any updates to the docs, you can deploy them via GitHub as simply as:

mkdocs gh-deploy

The docs will get propagated to: https://OoriData.github.io/Toolio/

Dev set up

For running the tests, working on contributions, etc, you need a virtualenv setup with the dev environment dependencies (pytest, pytest-cov, pytest-mock, etc.)):

pip install build hatch ruff pytest pytest-mock pytest-asyncio pytest-cov respx pgvector asyncpg pytest-asyncio

Code formatting etc.

Note: in order to pass CI, you'll also need to be lint clean. From the project dir you can just do:

ruff check .

Our project code convention settings are in pyproject.toml

Automated testing & coverage

To run the coverage tests:

pytest --cov=toolio test

You can also get other report formats by using e.g. --cov-report=html

Note: for reasons I'm still investigating (some of the more recent developments and issues in Python packaging are quite esoteric), some of the hatch tools such as hatch run are problematic. I suspect they might not like the way I rename directories during build, but I won't be compromising on that.

Releasing new versions

For now it's pretty simple. If it's a change you want to signal to users in any way, bump the release via hatch. From the checked out repo, do e.g.

hatch version micro

This would, for example, update the project version from 0.0.1 to 0.0.2, or from 0.0.9 to 0.0.10. It will update your local copy of __about__.py, so you'll want to commit & push that, alongside the other changes.

You can also use hatch version to make more significant releases, but you'll want to be clear what you're doing.

Releases

On Github

Pre-checklist:

• Update CHANGELOG.md check README.md
• Make sure tip of main is passing CI

https://github.com/OoriData/Toolio/releases and add a new release.

Set the version number (e.g. 0.3.0) as the release name, and select to create a new tag and use the same version number. You should be able to paste in the description from CHANGELOG.md. Then click Publish.

On PyPI

https://pypi.org/project/Toolio/

First, gather a tarball

python -m build

Then, Build a .whl

python -m build -w

STEPS MUST BE IN THIS ORDER. python -m build CREATES DYSFUNCTIONAL .whlS, BUT python -m build -w SUCCESSFULLY OVERWRITES IT WITH A FUNCTIONAL ONE

You have to have twine installed

pip install twine

You also need a ~/.pypirc file with your PyPI account details.

Then the actual upload:

twine upload dist/*

Smoke test

python3.11 -m venv $HOME/.local/venv/temp  # Replace with full path to desired Python exe
source $HOME/.local/venv/temp/bin/activate
pip install --upgrade pip
pip install toolio
python -c "import toolio"
# Make sure there's no error at this point
deactivate
rm -rf $HOME/.local/venv/temp