• Prerequisites
• Installation
• What's in the box ?
• Testing
• Docker

• Python >=3.12.3 <3.13 (tested with 3.12.5)
• pre-commit
• uv >=0.3.3 (tested with 0.4.0)
• docker (optional)

1. Clone the git repository

   git clone https://github.com/smarlhens/python-boilerplate.git

2. Go into the project directory

   cd python-boilerplate/

3. Checkout working branch

   git checkout <branch>

4. Enable pre-commit hooks

   pre-commit install

uv is an extremely fast Python package and project manager, written in Rust.

pyproject.toml file (pyproject.toml): orchestrate your project and its dependencies uv.lock file (uv.lock): ensure that the package versions are consistent for everyone working on your project

For more configuration options and details, see the configuration docs.

pre-commit is a framework for managing and maintaining multi-language pre-commit hooks.

.pre-commit-config.yaml file (.pre-commit-config.yaml): describes what repositories and hooks are installed

For more configuration options and details, see the configuration docs.

ruff is an extremely fast Python linter, written in Rust.

Rules are defined in the pyproject.toml.

For more configuration options and details, see the configuration docs.

mypy is an optional static type checker for Python that aims to combine the benefits of dynamic (or "duck") typing and static typing.

Rules are defined in the pyproject.toml.

For more configuration options and details, see the configuration docs.

bandit is a tool designed to find common security issues in Python code.

Rules are defined in the pyproject.toml.

For more configuration options and details, see the configuration docs.

docformatter is a tool designed to format docstrings to follow PEP 257.

Options are defined in the .pre-commit-config.yaml.

We are using pytest & pytest-cov to write tests.

To run tests:

uv run pytest tests

collected 1 item

tests/test_myapplication.py::test_hello_world PASSED

To run tests with coverage:

uv run pytest tests --cov=src

collected 1 item

tests/test_myapplication.py::test_hello_world PASSED

---------- coverage: platform linux, python 3.10.4-final-0 -----------
Name                            Stmts   Miss  Cover
---------------------------------------------------
src/myapplication/__init__.py       1      0   100%
src/myapplication/main.py           6      2    67%
---------------------------------------------------
TOTAL                               7      2    71%

To build the docker production image using Dockerfile:

docker build . -t my-python-application:latest

To build the docker development image using Dockerfile:

docker build . --target development -t my-python-application:dev

To run the python app example inside Docker:

docker run -it --rm my-python-application:latest # or :dev for development

Hello World

docker run -it --rm my-python-application:latest bash

We are using Makefile to manage the project.

To see the list of commands:

make

➜  api-spec git:(main) ✗ make
help                           Show this help
run                            Run the project
test                           Run the tests
lint                           Run the linter
format                         Run the formatter
typecheck                      Run the type checker
security                       Run the security checker
clean                          Clean the project
install                        Install the project