Python boilerplate

---

A Python boilerplate using modern dev tools

Project setup

Development environment

# Clone the repository
git clone https://github.com/MrHDOLEK/python-boilerplate.git

# Navigate to project directory
cd python-boilerplate/

# Checkout working branch
git checkout <branch>

# Setup Python environment
uv python install
uv venv
source .venv/bin/activate

# Install dependencies
uv sync

# Install pre-commit hooks
pre-commit install

Tools & Features

just

Command runner holding the shortcuts for every routine task. Recipes live in Justfile.

# Install just (pick one)
brew install just
uv tool install rust-just

# List every available recipe
just

# Run the CLI
just run user list

# Tests
just test
just test-coverage

# Individual quality checks
just lint
just format
just type-check
just security

# Full quality gate: lint, formatting, types, security, tests
just check

# Autofix formatting and lint, then run the gate
just fix

uv

Fast Python package manager, written in Rust. Configuration in pyproject.toml and dependencies locked in uv.lock.

# Install a package
uv pip install <package>

# Run a command in the environment
uv run pytest tests

pre-commit

Framework for managing git hooks. Configuration in .pre-commit-config.yaml.

# Run against all files
pre-commit run --all-files

ruff

Fast Python linter and formatter. Rules defined in pyproject.toml. The default rule set is extended with S (flake8-bandit), so security scanning is part of an ordinary lint run.

# Format code
uv run ruff format .

# Check code
uv run ruff check .

# Security rules only
uv run ruff check . --select S

ty

Fast static type checker from Astral. Configuration in pyproject.toml under [tool.ty].

uv run ty check

Testing

Using pytest for tests:

# Run tests
uv run pytest tests

# Run tests with coverage
uv run pytest tests --cov=src

Docker

# Login to GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u $GITHUB_USERNAME --password-stdin
# Build production image
docker buildx build -f .docker/python/Dockerfile -t my-python-application:latest .
# Run the application
docker run -it --rm my-python-application:latest

Documentation

Learn more at these links:

• uv
• pre-commit
• ruff
• ty
• pytest