bloodhound-python 0.1.0

A minimal but complete example of a modern Python package published to PyPI.

bloodhound-python

A minimal but complete example of a modern Python package: src layout, PEP 621 metadata in pyproject.toml, a typed library, a console script, tests, and a GitHub Actions release workflow that publishes to PyPI with Trusted Publishing (no API tokens stored anywhere).

Install

pip install bloodhound-python

Use it as a library

from bloodhound_python import Greeter, greet

greet("Ada")  # 'Hello, Ada!'
greet("Ada", salutation="Howdy")  # 'Howdy, Ada!'
Greeter(salutation="Hi", punctuation="?").greet("Ada")  # 'Hi, Ada?'

Use it from the shell

sample-greet Ada
sample-greet Ada --salutation Howdy --times 3
sample-greet --version

Develop

python -m venv .venv
.venv\Scripts\activate        # Windows;  source .venv/bin/activate on POSIX
pip install -e ".[dev]"

pytest                        # tests + coverage
ruff check . && ruff format --check .
mypy

Release

1. Bump __version__ in src/bloodhound_python/__init__.py (the single source of truth — pyproject.toml reads it via [tool.hatch.version]).

2. Update CHANGELOG.md.

3. Tag and push:

   git tag v0.1.0 && git push origin v0.1.0
   

The release.yml workflow builds the sdist and wheel, uploads them to TestPyPI, then publishes to PyPI. Configure both as Trusted Publishers for this repo first (PyPI → Your projects → Publishing), matching workflow name release.yml and environments testpypi / pypi.

Manual release, if you'd rather not use CI

pip install build twine
python -m build            # -> dist/*.whl and dist/*.tar.gz
twine check dist/*
twine upload dist/*

Layout

bloodhound-python/
├── pyproject.toml              # build backend, metadata, tool config
├── README.md                   # rendered as the PyPI project page
├── LICENSE
├── CHANGELOG.md
├── src/bloodhound_python/
│   ├── __init__.py             # public API + __version__
│   ├── core.py                 # library logic
│   ├── cli.py                  # console script entry point
│   └── py.typed                # ships inline type hints (PEP 561)
├── tests/
└── .github/workflows/          # ci.yml, release.yml

The src layout is deliberate: tests import the installed package rather than the working directory, so a missing py.typed or an unlisted subpackage fails in CI instead of after release.

License

MIT — see LICENSE.