modern-python

•

4.5k3853 months ago

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

Quick Install

npxskills add trailofbits/skills--skill modern-python

Instructions

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

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)	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 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 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)

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 -v '^#' requirements.txt | grep -v '^-' | grep -v '^\s*$' | while read -r pkg; do
    uv add "$pkg" || echo "Failed to add: $pkg"
done

uv sync

Then:

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

From setup.py / setup.cfg

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

From flake8 + black + isort

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

From mypy / pyright

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

Quick Reference: uv Commands

Command	Description
`uv init`	Create new project
`uv init --package`	Create distributable package
`uv add <pkg>`	Add dependency
`uv add --group dev <pkg>`	Add to dependency group
`uv remove <pkg>`	Remove dependency
`uv sync`	Install dependencies
`uv sync --all-groups`

Ad-hoc Dependencies with `--with`

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

# Run Python with a temporary package
uv run --with requests python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"

# Run a module with temporary deps
uv run --with rich python -m rich.progress

# Multiple packages
uv run --with requests --with rich python script.py

# Combine with project deps (adds to existing venv)
uv run --with httpx pytest  # project deps + httpx

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

[dependency-groups]
dev = ["ruff", "ty"]
test = ["pytest", "pytest-cov", "hypothesis"]
docs = ["sphinx", "myst-parser"]

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

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

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)	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 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 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)

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 -v '^#' requirements.txt | grep -v '^-' | grep -v '^\s*$' | while read -r pkg; do
    uv add "$pkg" || echo "Failed to add: $pkg"
done

uv sync

Then:

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

From setup.py / setup.cfg

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

From flake8 + black + isort

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

From mypy / pyright

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

Quick Reference: uv Commands

Command	Description
`uv init`	Create new project
`uv init --package`	Create distributable package
`uv add <pkg>`	Add dependency
`uv add --group dev <pkg>`	Add to dependency group
`uv remove <pkg>`	Remove dependency
`uv sync`	Install dependencies
`uv sync --all-groups`

Ad-hoc Dependencies with `--with`

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

# Run Python with a temporary package
uv run --with requests python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"

# Run a module with temporary deps
uv run --with rich python -m rich.progress

# Multiple packages
uv run --with requests --with rich python script.py

# Combine with project deps (adds to existing venv)
uv run --with httpx pytest  # project deps + httpx

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

[dependency-groups]
dev = ["ruff", "ty"]
test = ["pytest", "pytest-cov", "hypothesis"]
docs = ["sphinx", "myst-parser"]

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

modern-python

Modern Python

When to Use This Skill

When NOT to Use This Skill

Anti-Patterns to Avoid

Decision Tree

Tool Overview

Security Tools

Quick Start: Minimal Project

Full Project Setup

1. Create Project Structure

2. Configure pyproject.toml

3. Install Dependencies

4. Add Makefile

Migration Guide

From requirements.txt + pip

From setup.py / setup.cfg

From flake8 + black + isort

From mypy / pyright

Quick Reference: uv Commands

Ad-hoc Dependencies with --with

Quick Reference: Dependency Groups

Best Practices Checklist

Read Next

Related Skills

skill-creator

skill-creator

1password

himalaya

Modern Python

When to Use This Skill

When NOT to Use This Skill

Anti-Patterns to Avoid

Decision Tree

Tool Overview

Security Tools

Quick Start: Minimal Project

Full Project Setup

1. Create Project Structure

2. Configure pyproject.toml

3. Install Dependencies

4. Add Makefile

Migration Guide

From requirements.txt + pip

From setup.py / setup.cfg

From flake8 + black + isort

From mypy / pyright

Quick Reference: uv Commands

Ad-hoc Dependencies with --with

Quick Reference: Dependency Groups

Best Practices Checklist

Read Next

Related Skills

skill-creator

skill-creator

1password

himalaya

Related Skills

skill-creator

skill-creator

1password

himalaya

Ad-hoc Dependencies with `--with`

Ad-hoc Dependencies with `--with`