modern-python

name	modern-python
description	Configures Python projects with modern tooling (uv, ruff, ty). Use when creating projects, writing standalone scripts, or migrating from pip/Poetry/mypy/black.

Modern Python

Ref: trailofbits/cookiecutter-python

Tool Choices

Use	Instead of	Why
uv add / uv sync	uv pip install, manual pyproject.toml edits	Manages lockfile and venv automatically
uv run <cmd>	source .venv/bin/activate	No manual venv management
uv_build backend	hatchling	Simpler, sufficient for most cases
uv	Poetry	Faster, better ecosystem integration
pyproject.toml / PEP 723	requirements.txt	Modern standard
ty	mypy / pyright	Faster, from Astral team
[dependency-groups] (PEP 735)	[project.optional-dependencies]	Dedicated dev/test grouping
[tool.ty.environment] python-version	[tool.ty] python-version	Correct config nesting
prek (setup)	pre-commit	Faster, Rust-native

Decision Tree

What are you doing?
│
├─ Single-file script with dependencies?
│   └─ PEP 723 inline metadata (./references/pep723-scripts.md)
│
├─ New multi-file project (not distributed)?
│   └─ Minimal uv setup (Quick Start below)
│
├─ New reusable package/library?
│   └─ Full project setup (Full Setup below)
│
└─ Migrating existing project?
    └─ Migration Guide below

Tool Overview

Tool	Purpose	Replaces
uv	Package/dependency management	pip, virtualenv, pip-tools, pipx, pyenv
ruff	Linting and formatting	flake8, black, isort, pyupgrade
ty	Type checking	mypy, pyright
pytest	Testing with coverage	unittest
prek	Pre-commit hooks	pre-commit

Security Tools

Tool	Purpose
shellcheck	Shell script linting
detect-secrets	Secret detection
actionlint	Workflow syntax validation
zizmor	Workflow security audit
pip-audit	Dependency vulnerability scanning

See security-setup.md for configuration.

Quick Start: Minimal Project

uv init myproject && cd myproject
uv add requests rich
uv add --group dev pytest ruff ty

uv run python src/myproject/main.py
uv run pytest
uv run ruff check .

Full Project Setup

For distributable packages, consider the Trail of Bits cookiecutter:

uvx cookiecutter gh:trailofbits/cookiecutter-python

Or manually:

uv init --package myproject && cd myproject

pyproject.toml Configuration

See pyproject.md for complete reference.

[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = []

[dependency-groups]
dev = [{include-group = "lint"}, {include-group = "test"}, {include-group = "audit"}]
lint = ["ruff", "ty"]
test = ["pytest", "pytest-cov"]
audit = ["pip-audit"]

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["ALL"]
ignore = ["D", "COM812", "ISC001"]

[tool.pytest]
addopts = ["--cov=myproject", "--cov-fail-under=80"]

[tool.ty.terminal]
error-on-warning = true

[tool.ty.environment]
python-version = "3.11"

[tool.ty.rules]
possibly-unresolved-reference = "error"
unused-ignore-comment = "warn"

Install and Verify

uv sync --all-groups

Makefile

.PHONY: dev lint format test build

dev:
uv sync --all-groups

lint:
uv run ruff format --check && uv run ruff check && uv run ty check src/

format:
uv run ruff format .

test:
uv run pytest

build:
uv build

Migration Guide

From requirements.txt + pip

Scripts: Convert to PEP 723 inline metadata (pep723-scripts.md)

Projects:

uv init --bare
uv add requests rich  # add each dependency
uv sync

Then delete requirements.txt, requirements-dev.txt, old venvs. Add uv.lock to version control.

From setup.py / setup.cfg

1. uv init --bare to create pyproject.toml
2. uv add each dependency from install_requires
3. uv add --group dev for dev dependencies
4. Copy metadata (name, version, description) to [project]
5. Delete setup.py, setup.cfg, MANIFEST.in

From flake8 + black + isort → ruff

1. Remove old tools, delete .flake8, [tool.black], [tool.isort] configs
2. uv add --group dev ruff
3. Configure ruff (ruff-config.md)
4. uv run ruff check --fix . && uv run ruff format .

From mypy / pyright → ty

1. Remove old tools, delete mypy.ini, pyrightconfig.json
2. uv add --group dev ty
3. uv run ty check src/

uv Command Reference

Command	Description
uv init / uv init --package	Create project / distributable package
uv add <pkg>	Add dependency
uv add --group dev <pkg>	Add to dependency group
uv remove <pkg>	Remove dependency
uv sync / uv sync --all-groups	Install dependencies
uv run <cmd>	Run command in venv
uv run --with <pkg> <cmd>	Run with temporary dependency (one-off usage)
uv build / uv publish	Build / publish package

References

• pyproject.md — pyproject.toml reference
• uv-commands.md — uv command reference
• ruff-config.md — Ruff configuration
• testing.md — pytest and coverage
• pep723-scripts.md — PEP 723 inline metadata
• prek.md — Pre-commit hooks
• security-setup.md — Security tools
• dependabot.md — Automated updates
• migration-checklist.md — Migration cleanup