Table of Contents

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

Prerequisites

• Python >=3.14.0 <3.15.0 (tested with 3.14.7)
• pre-commit >=3.2.0 <5.0.0 (tested with 4.6.2)
• uv >=0.12.2 (tested with 0.12.3)
• docker (optional)

Installation

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

5. Configure Python environment

   uv python install
   uv venv
   source .venv/bin/activate

What's in the box ?

uv

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

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

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

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.

ty

ty is a fast type checker from Astral, written in Rust. It runs alongside mypy as a second blocking type-checker.

Rules are defined in the pyproject.toml.

For more configuration options and details, see the ty documentation.

Testing

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

To run tests:

uv run pytest tests

collected 1 item
tests/test_python_boilerplate.py::test_hello_world PASSED

To run tests with coverage:

uv run pytest tests --cov=src

collected 1 item
tests/test_python_boilerplate.py::test_hello_world PASSED
---------- coverage: platform linux, python 3.14.6-final-0 -----------
Name                                 Stmts   Miss  Cover
--------------------------------------------------------
src/python_boilerplate/__init__.py       1      0   100%
src/python_boilerplate/main.py           6      2    67%
--------------------------------------------------------
TOTAL                                    7      2    71%

Validation

Lint & format

To run ruff lint check:

uv run ruff check src tests

To run ruff format check:

uv run ruff format --check src tests

To apply ruff formatting:

uv run ruff format src tests

Type check

To run mypy:

uv run mypy

Pre-commit

To run all pre-commit hooks against all files:

pre-commit run --all-files

Docker

Build

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

Run

To run the python app example inside Docker:

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

Hello World

Execute command inside container

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