/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

Guide for modern Python tooling and best practices, based on [trailofbits/cookiecutter-python](https://github.com/trailofbits/cookiecutter-python).

When to Use This Skill

• Creating a new Python project or package
• Setting up `pyproject.toml` configuration
• Configuring development tools (linting, formatting, testing)
• Writing Python scripts with external dependencies
• Migrating from legacy tools (when user requests it)

When NOT to Use This Skill

• **User wants to keep legacy tooling**: Respect existing workflows if explicitly requested
• **Python < 3.11 required**: These tools target modern Python
• **Non-Python projects**: Mixed codebases where Python isn't primary

Anti-Patterns to Avoid

| Avoid | Use Instead | |-------|-------------| | `[tool.ty]` python-version | `[tool.ty.environment]` python-version | | `uv pip install` | `uv add` and `uv sync` | | Editing pyproject.toml manually to add deps | `uv add <pkg>` / `uv remove <pkg>` | | `hatchling` build backend | `uv_build` (simpler, sufficient for most cases) | | Poetry | uv (faster, simpler, better ecosystem integration) | | requirements.txt | PEP 723 for scripts, pyproject.toml for projects | | mypy / pyright | ty (faster, from Astral team) | | `[project.optional-dependencies]` for dev tools | `[dependency-groups]` (PEP 735) | | Manual virtualenv activation (`source .venv/bin/activate`) | `uv run <cmd>` | | pre-commit | prek (faster, no Python runtime needed) |

**Key principles:**

• Always use `uv add` and `uv remove` to manage dependencies
• Never manually activate or manage virtual environments—use `uv run` for all commands
• Use `[dependency-groups]` for dev/test/docs dependencies, not `[project.optional-dependencies]`

Decision Tree

What are you doing?
│
├─ Single-file script with dependencies?
│   └─ Use PEP 723 inline metadata (./references/pep723-scripts.md)
│
├─ New multi-file project (not distributed)?
│   └─ Minimal uv setup (see Quick Start below)
│
├─ New reusable package/library?
│   └─ Full project setup (see Full Setup below)
│
└─ Migrating existing project?
    └─ See 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, pydocstyle | | **ty** | Type checking | mypy, pyright (faster alternative) | | **pytest** | Testing with coverage | unittest | | **prek** | Pre-commit hooks ([setup](./references/prek.md)) | pre-commit (faster, Rust-native) |

Security Tools

| Tool | Purpose | When It Runs | |------|---------|--------------| | **shellcheck** | Shell script linting | pre-commit | | **detect-secrets** | Secret detection | pre-commit | | **actionlint** | Workflow syntax validation | pre-commit, CI | | **zizmor** | Workflow security audit | pre-commit, CI | | **pip-audit** | Dependency vulnerability scanning | CI, manual | | **Dependabot** | Automated dependency updates | scheduled |

See [security-setup.md](./references/security-setup.md) for configuration and usage.

Quick Start: Minimal Project

For simple multi-file projects not intended for distribution:

# Create project with uv
uv init myproject
cd myproject

# Add dependencies
uv add requests rich

# Add dev dependencies
uv add --group dev pytest ruff ty

# Run code
uv run python src/myproject/main.py

# Run tools
uv run pytest
uv run ruff check .

Full Project Setup

If starting from scratch, ask the user if they prefer to use the Trail of Bits cookiecutter template to bootstrap a complete project with already preconfigured tooling.

uvx cookiecutter gh:trailofbits/cookiecutter-python

1. Create Project Structure

uv init --package myproject
cd myproject

This creates:

myproject/
├── pyproject.toml
├── README.md
├── src/
│   └── myproject/
│       └── __init__.py
└── .python-version

2. Configure pyproject.toml

See [pyproject.md](./references/pyproject.md) for complete configuration reference.

Key sections:

[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]
# Strict from day 1 for new projects
possibly-unresolved-reference = "error"
unused-ignore-comment = "warn"

3. Install Dependencies

# Install all dependency groups
uv sync --all-groups

# Or install specific groups
uv sync --group dev

4. Add 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

When a user requests migration from legacy tooling:

From requirements.txt + pip

First, determine the nature of the code:

**For standalone scripts**: Convert to PEP 723 inline metadata (see [pep723-scripts.md](./references/pep723-scripts.md))

**For projects**:

# Initialize uv in existing project
uv init --bare

# Add dependencies using uv (not by editing pyproject.toml)
uv add requests rich  # add each package

# Or import from requirements.txt (review each package before adding)
# Note: Complex version specifiers may need manual handling
grep