Python Poetry bootstrap template

Author: Benjamin Roland

This repository contains the backbone, configuration and make targets to set up a repeatable Python development environment with Poetry.

For additional context, read the accompanying blog post.

🚦 Requirements

Make sure you have Poetry >=2.0 installed on your system (see instruction).

Then, assuming you have a Unix shell with make, use the following target to set up a new Poetry-managed replicable environment for your project :

make init

👷 CI/CD tools

• 🚀 Package management tool: Poetry
• 🎭 Code formatting: Black and isort to tidy code and imports.
• ✅ Code quality: mypy, Ruff
• 🧪 Tests: pytest
• 📤 pre-commit hooks

All tools configurations live in a single pyproject.toml — no scattered files.

🔖 Dynamic Versioning

poetry-dynamic-versioning is used to enforce VCS tags as a single source of truth for project versioning.

📤 Pre-commit hooks

Pre-commit hooks prevent code with identified issues to be committed and submitted for code review. We use :

• built-in pre-commit hooks for common linting/code quality checks.
• pyupgrade to keep up with PEP syntax upgrade.
• Black and isort for proper code formatting.
• Ruff and mypy hooks to catch code quality issues early.

📝 Documentation

The template ships with a pre-built documentation structure for Sphinx, with Autodoc extension and the neat Furo them. Use the update-doc make target to populate documentation source, and adapt the index.rst and conf.py files as needed.

Use a GitHub Action to deploy the documentation on GitHub Pages (see example here).

🔩 Dissecting Makefile

The Makefile provides several targets to assist in development and code quality :

• init creates a project-specific virtual environment and installs the dependencies of the .lock file, if present (see here for an intro on Poetry .lock file).
• ci launches black, ruff, mypy and pytest on your source code.
• pre-commit set up and/or update pre-commit hooks (see pre-commit documentation) and run them on all your staged files.
• coverage run tests under coverage and produces a coverage report.
• update-doc and build-doc updates and builds your documentation with Sphinx for local previsualisation.
• clean clears bytecode, poetry/pip caches, and pre-commit hooks. Use with caution.

🚛 Adapting and Extending this template

• Python version and dependencies are listed in and can be added to the pyproject.toml file manually or with the poetry add command
• For application deployment, add dockerization.
• Poetry exposes methods for struggleless publishing of your package on PyPi.
• For CI/CD, GitHub Actions need to be set up to check commits and trigger different build (see example here).

Credits

This template is heavily inspired by Cepedus Poetry-FastAPI bootstrap template.