python-project-template

Template for BonvinLab Python projects. src-layout, pytest, GitHub Actions for CI, Docker, and PyPI publishing.

What's in here

• src/<package>/ is the package, with main.py (argparse CLI stub), utils.py (example functions), log.py (logging setup)
• tests/ — matching pytest tests
• .github/workflows/test.yml automated actions that run pytest on push/PR to main, matrix of ubuntu-latest/macos-latest x Python 3.10/3.14
• .github/workflows/docker-publish.yml automated action that builds and pushes a Docker image to GHCR on tag push
• .github/workflows/publish.yml is an action publishes to PyPI on GitHub release

Getting started

1. Use this template on GitHub when creating a new repository.

2. Rename the package: src/python_project_template/ → src/your_package_name/, update name in pyproject.toml.

3. Install:

   pip install -e ".[dev]"

4. Run tests:

   pytest

5. Fill in the stubs in main.py, utils.py, log.py, and update the tests to match.

6. Start programming (:

Docker

The Dockerfile installs the package with pip install . and runs python -m your_package_name.main as the entrypoint, update that module path after renaming.

docker-publish.yml action builds the image and pushes it to GHCR (ghcr.io/<owner>/<repo>) on every tag push, tagged to match.

Build and run locally:

docker build -t your-image-name .
docker run --rm your-image-name

Publishing to PyPI

publish.yml uses trusted publishing, to configure it:

1. Go to pypi.org: Publishing -> add a trusted publisher with your repo name, workflow publish.yml.
2. Update the url in publish.yml to your project's PyPI page.
3. Make a GitHub release, the workflow will run and publish your code to PyPi