Modern Python Tooling Engine

Comprehensive Python development tooling guide covering modern package managers (uv, rye, poetry), formatting (ruff), type checking (mypy, pyright), testing (pytest), and project setup for production Python applications.

When to Use This Skill

Choose Modern Python Tooling when:

• Setting up a new Python project with modern best practices
• Migrating from pip/virtualenv to uv or poetry
• Configuring linting, formatting, and type checking
• Setting up CI/CD pipelines for Python projects
• Standardizing Python development workflows across a team

Consider alternatives when:

• Building data science projects — use conda or mamba
• Need Jupyter-first workflow — use JupyterLab configuration
• Working on legacy Python 2 projects — use traditional tooling

Quick Start

Copy
# Activate Python tooling
claude skill activate complete-modern-python-tooling-engine

# Set up new project
claude "Set up a new Python project with uv, ruff, mypy, and pytest"

# Migrate existing project
claude "Migrate this project from pip + requirements.txt to uv with pyproject.toml"

Example: Modern Python Project Setup

Copy
# Install uv (fastest Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create new project
uv init my-project
cd my-project

# Add dependencies
uv add fastapi uvicorn pydantic
uv add --dev pytest ruff mypy pre-commit

# pyproject.toml configuration

Copy
# pyproject.toml
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.109",
    "uvicorn>=0.27",
    "pydantic>=2.5",
]

[tool.uv]
dev-dependencies = [
    "pytest>=8.0",
    "pytest-asyncio>=0.23",
    "ruff>=0.3",
    "mypy>=1.8",
    "pre-commit>=3.6",
]

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

[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "B", "SIM", "RUF"]
ignore = ["E501"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

[tool.mypy]
python_version = "3.12"
strict = true
warn_return_any = true
disallow_untyped_defs = true

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"

Core Concepts

Modern Python Tool Stack

Category	Tool	Purpose
Package Manager	uv	Fast dependency resolution, virtual envs, Python version management
Linter + Formatter	Ruff	10-100x faster than flake8+isort+black combined
Type Checker	mypy / Pyright	Static type analysis
Testing	pytest	Test runner with powerful fixtures
Task Runner	just / make	Script organization
Pre-commit	pre-commit	Git hook management
Build	hatch / setuptools	Package building

Ruff vs Traditional Tools

Feature	Ruff	Traditional
Linting	ruff check	flake8 + plugins
Formatting	ruff format	black
Import sorting	Built-in (I rules)	isort
Speed	10-100x faster	Baseline
Configuration	Single pyproject.toml section	Multiple config files
Auto-fix	ruff check --fix	Limited per-tool

Copy
# Common development commands
# Run linter
uv run ruff check .

# Auto-fix lint issues
uv run ruff check --fix .

# Format code
uv run ruff format .

# Type check
uv run mypy src/

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

# Run all checks (pre-commit)
uv run pre-commit run --all-files

Configuration

Parameter	Description	Default
python_version	Target Python version	3.12
package_manager	Package manager: uv, poetry, pip	uv
linter	Linter: ruff, flake8	ruff
formatter	Formatter: ruff, black	ruff
type_checker	Type checker: mypy, pyright, none	mypy
test_framework	Testing: pytest, unittest	pytest
line_length	Maximum line length	100
strict_typing	Enable strict mypy mode	true

Best Practices

1. Use uv for everything — it replaces pip, virtualenv, pyenv, and pipx — uv is a single tool that manages Python versions, creates virtual environments, resolves dependencies, and installs packages 10-100x faster than pip. It's a drop-in replacement with full compatibility.

2. Configure all tools in pyproject.toml — Consolidate configuration for ruff, mypy, pytest, and build settings in a single pyproject.toml file. Eliminate separate setup.cfg, .flake8, mypy.ini, and pytest.ini files for easier maintenance.

3. Use Ruff for both linting and formatting — Ruff replaces flake8, isort, black, pyflakes, and dozens of plugins with a single, fast tool. Enable rule sets incrementally: start with E+F (errors), add I (imports), N (naming), UP (pyupgrade), then B and SIM.

4. Enable strict mypy mode from the start — Adding types to an existing untyped codebase is painful. Start with strict = true in mypy config and maintain full type coverage. Use reveal_type() during development and cast() only when truly necessary.

5. Set up pre-commit hooks for automatic quality enforcement — Configure pre-commit with ruff (lint + format), mypy, and tests on staged files. This catches issues before they enter the repository without relying on CI feedback loops.

Common Issues

uv lock file conflicts in team environments. Use uv.lock (committed to git) for reproducible installs. When conflicts arise, delete uv.lock and regenerate with uv lock. Pin major versions in pyproject.toml dependencies but let the lock file handle exact versions.

Mypy reports errors in third-party libraries without type stubs. Install type stubs: uv add --dev types-requests types-pyyaml. For libraries without stubs, add [[tool.mypy.overrides]] with ignore_missing_imports = true for specific packages rather than disabling globally.

Ruff and mypy disagree on import ordering or unused imports. Configure both tools consistently. Ruff's I rules handle import sorting — disable isort in other tools. For "unused import" conflicts, ruff may remove an import that mypy needs for type checking. Use # noqa: F401 on type-only imports or use TYPE_CHECKING blocks.