Notes for contributors

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 pip install twine ruff pytest pytest-mock pytest-asyncio pytest-cov respx pgvector asyncpg pytest-asyncio

Mock PGVector

OgbujiPT utilizes a docker image of PGVector an open-source vector similarity search for Postgres. To set up for testing, you can just do:

docker pull ankane/pgvector
docker run --name mock-postgres -p 5432:5432 \
    -e POSTGRES_USER=mock_user -e POSTGRES_PASSWORD=mock_password -e POSTGRES_DB=mock_db \
    -d ankane/pgvector

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 .

NOTE: make sure you don't have anything running on port 0.0.0.0:5432

Our project code convention settings are in pyproject.toml

Automated testing & coverage

To run the coverage tests:

pytest --cov=ogbujipt 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/uogbuji/OgbujiPT/releases and add a new release.

Set the version number (e.g. v0.10.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.

Official PyPI publish on GH Release

Automatic on GH release. Updates https://pypi.org/project/OgbujiPT/

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 ogbujipt
python -c "import ogbujipt"
# Make sure there's no error at this point
deactivate
rm -rf $HOME/.local/venv/temp

OBSOLETE Publishing steps

First, gather a tarball

python -m build

Then, Build a .whl

python -m build -w

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

Have to have twine installed:

pip install twine

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

OBSOLETE Test distribution upload

twine upload --repository testpypi dist/*

Make sure things look good at https://test.pypi.org/project/OgbujiPT/

OBSOLETE Official distribution upload

Then the actual upload:

twine upload dist/*