modern-python

Modern Python

Guide for modern Python tooling and best practices, based on 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

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

Security Tools

See security-setup.md for configuration and usage.

Quick Start: Minimal Project

For simple multi-file projects not intended for distribution:

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.

1. Create Project Structure

This creates:

2. Configure pyproject.toml

See pyproject.md for complete configuration reference.

Key sections:

3. Install Dependencies

4. Add Makefile

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)

For projects:

Then:

1. Delete requirements.txt, requirements-dev.txt
2. Delete virtual environment (venv/, .venv/)
3. Add uv.lock to version control

From setup.py / setup.cfg

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

From flake8 + black + isort

1. Remove flake8, black, isort via uv remove
2. Delete .flake8, pyproject.toml [tool.black], [tool.isort] configs
3. Add ruff: uv add --group dev ruff
4. Add ruff configuration (see ruff-config.md)
5. Run uv run ruff check --fix . to apply fixes
6. Run uv run ruff format . to format

From mypy / pyright

1. Remove mypy/pyright via uv remove
2. Delete mypy.ini, pyrightconfig.json, or [tool.mypy]/[tool.pyright] sections
3. Add ty: uv add --group dev ty
4. Run uv run ty check src/

Quick Reference: uv Commands

Ad-hoc Dependencies with --with

Use uv run --with for one-off commands that need packages not in your project:

When to use --with vs uv add:

• uv add: Package is a project dependency (goes in pyproject.toml/uv.lock)
• --with: One-off usage, testing, or scripts outside a project context

See uv-commands.md for complete reference.

Quick Reference: Dependency Groups

Install with: uv sync --group dev --group test

Best Practices Checklist

• Use src/ layout for packages
• Set requires-python = ">=3.11"
• Configure ruff with select = ["ALL"] and explicit ignores
• Use ty for type checking
• Enforce test coverage minimum (80%+)
• Use dependency groups instead of extras for dev tools
• Add uv.lock to version control
• Use PEP 723 for standalone scripts

Read Next

• migration-checklist.md - Step-by-step migration cleanup
• pyproject.md - Complete pyproject.toml reference
• uv-commands.md - uv command reference
• ruff-config.md - Ruff linting/formatting configuration
• testing.md - pytest and coverage setup
• pep723-scripts.md - PEP 723 inline script metadata
• prek.md - Fast pre-commit hooks with prek
• security-setup.md - Security hooks and dependency scanning
• dependabot.md - Automated dependency updates