Python Boilerplate

A minimal, modern starting point for Python services. Ships with structured JSON logging (with optional Google Cloud Logging support), a src/ layout, and a fully wired tooling setup: uv for dependency management, ruff for linting and formatting, mypy for type checking, and pytest for tests.

Create a new project from this template

This repository is a GitHub template.

1. Click Use this template → Create a new repository on GitHub, or run:

gh repo create my-app --template baptiste-bonnaudet/python-boilerplate --private --clone

2. From the cloned repository, rename the package in one step:

make init name=my_app

This renames the boilerplate package to my_app (deriving a My App display name), rewrites every reference across the project, and then removes the bootstrap bits, this section, the init target, and scripts/init.sh, so your new project starts clean.

3. Install dependencies and run it:

make install
make run

Requirements

• uv
• Python 3.13 (uv will install it automatically if missing)

Getting started

uv sync                  # create .venv and install all dependencies
cp .env.example .env     # configure environment variables
uv run python -m boilerplate

Configuration

Configuration is read from environment variables (see .env.example):

Variable	Description	Default
LOG_LEVEL	DEBUG / INFO / WARNING / ERROR / CRITICAL	DEBUG
LOCAL_DEV	Truthy (1/true/yes) when running locally	false
GOOGLE_PROJECT_ID	When set, logs are emitted via Google Cloud's structured handler	unset

Development

Common tasks are exposed through the Makefile:

make install     # uv sync
make lint        # ruff check
make format      # ruff format
make typecheck   # mypy
make test        # pytest (unit)
make check       # lint + typecheck + test
make run         # run the app
make docker      # build the Docker image

The Makefile also exposes a template-only make init name=my_app target that renames the package for a new project (see Create a new project from this template). It removes itself once run.

Or call the tools directly via uv, e.g. uv run pytest.

Dev container

.devcontainer/ defines an isolated environment with the full toolchain and a default-deny egress firewall, so agent-driven sessions can run without permission prompts while confined to this repo and a known set of domains. Open the repo in VS Code and choose Reopen in Container. Add your project's own domains to ALLOWED_DOMAINS in .devcontainer/project-firewall.sh before relying on the network. See .devcontainer/README.md.

Pre-commit hooks

uv run pre-commit install

This runs ruff and a gitleaks secret scan on every commit.

Testing

Unit and integration tests live under tests/. Integration tests may require external credentials (e.g. GOOGLE_APPLICATION_CREDENTIALS).

uv run pytest tests/unit          # fast, no external dependencies
uv run pytest tests/integration   # requires credentials

Docker

docker build -t boilerplate:latest .
docker run --rm boilerplate:latest

The image uses a multi-stage uv build on python:3.13-slim and runs as a non-root user.

License

MIT