Python Developer Tooling Handbook
This is not a book about programming Python. Instead, the goal of this book is to help you understand the ecosystem of tools used to make Python development easier and more productive. For example, this book will help you make sense of the complex world of building Python packages: what exactly are uv, Poetry, Flit, Setuptools, and Hatch? What are the pros and cons of each? How do they compare to each other? It also covers tools for linting, formatting, and managing dependencies.
The handbook is structured according to the Diátaxis framework. There are four primary sections:
- Tutorial: This section provides step-by-step guides to help you get started in improving your Python development experience.
- How To: This section help you get things done in your Python project.
- Explanation: This section provides in-depth explanations to deepen your understanding Python development.
- Reference: This section provides detailed information about specific tools and concepts in Python development.
The book does not attempt to replace the documentation available for various tools; a link to the documentation for each tool is available on its Reference page. Also, the handbook is meant to complement, not replace, the Python Packaging Authority’s excellent Python Packaging User Guide. Also, be sure to check out the helpful Scientific Python Library Development Guide.
This book is a work in progress and will be updated regularly. If you have any suggestions or feedback, please feel free to use the feedback form at the bottom of any page page.
Tim Hopper
Raleigh, North Carolina
Recent Blog Posts
Teaching Claude Code Quality Patterns with a Custom Skill
January 9, 2026
Dagster’s dignified-python-313 skill guides Claude Code to write Python 3.13 code that matches their project conventions.
What It Covers
Modern Python 3.13 Patterns: Use native type syntax (list[str], str | None) instead of older alternatives. Skip from __future__ import annotations since Python 3.13 doesn’t need it.
CLI Development: Build Click interfaces with proper error handling. Use click.echo() for output, direct errors to stderr, and treat CLI commands as error boundaries that catch exceptions and exit with SystemExit(1).
ty is Built with AI
January 2, 2026
Tool creators are building their tools with AI coding assistants.
Boris Cherny, creator of Claude Code, didn’t open an IDE in December but wrote 200 PRs with Claude Code. Charlie Marsh, creator of ruff, uv, and ty, noted that all his PRs to ty were created with Claude Code. The tools building themselves.
Integration with Python Tooling
The handbook’s Modern Python Project Setup Guide for AI Assistants provides structured guidance so AI tools default to uv and modern patterns rather than falling back to pip commands.
How uv Achieved Its Performance
December 26, 2025
Andrew Nesbitt’s “How uv got so fast” explains that uv’s speed comes less from Rust and more from eliminating work entirely.
Speed Through Elimination
Rather than optimizing slow code paths, uv just removes them:
- No
.eggsupport - No
pip.conf - No bytecode compilation by default
- Ignoring
requires-pythonupper bounds reduces resolver backtracking
Rust-Independent Optimizations
Many of uv’s performance gains could work in pip:
- Parallel downloads instead of sequential
- Smart HTTP range requests for metadata
uv got fast by launching when PEP 658 infrastructure was ready and by skipping backward compatibility requirements that slow down pip.
ty: Astral's New Python Type Checker Released
December 16, 2025
Astral released ty, a Python type checker written in Rust, today. The company behind uv and Ruff designed ty as an alternative to mypy and Pyright, with performance as a primary focus.
Speed Benchmarks
According to Astral’s benchmarks:
- ty checks the home-assistant project in 2.19 seconds (20x faster than mypy’s 45.66 seconds)
- After editing a file in PyTorch, ty recomputes diagnostics in 4.7ms (80x faster than Pyright’s 386ms)
Key Features
ty includes several design choices that distinguish it from existing type checkers:
Teaching LLMs Python Best Practices
November 21, 2025
Large language models possess extensive Python knowledge from training data, yet they consistently struggle with modern tooling practices. Despite being trained on massive amounts of Python code, frontier models often default to outdated patterns like direct python or pip commands instead of using virtual environments and modern tools like uv.
how is it, that despite every frontier LLM being insanely python maxxed they rarely use virtural envs, and even adding rules like "we are using uv, do everything with uv" they ignore it and think the system python is broken. like, every time. that's actually an accomplishment
Claude Code Hooks for uv Projects
November 11, 2025
Claude Code supports custom hooks that guide the AI agent toward project-specific workflows. For Python projects using uv, hooks can prevent Claude from falling back to pip and python commands.
Note
This post builds on the interceptor approach for teaching AI agents about uv. Interceptors provide runtime feedback; hooks prevent problematic commands before execution.
Sync with uv: Eliminate Pre-commit Version Drift
September 26, 2025
Managing tool versions across multiple configuration files creates persistent headaches in Python development. When you upgrade ruff in your pyproject.toml, you must remember to manually update the pre-commit hook version in .pre-commit-config.yaml. This version drift causes inconsistent behavior between local development and pre-commit checks.
The sync-with-uv library solves this by automatically synchronizing tool versions between uv.lock and .pre-commit-config.yaml.
The Problem
Consider this common scenario:
# pyproject.toml
[dependency-groups]
lint = ["ruff>=0.1.0", "mypy>=1.0.0"]# .pre-commit-config.yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.1.5 # Must manually sync with pyproject.toml
hooks:
- id: ruffWhen uv lock --upgrade updates ruff to 0.1.8, the pre-commit hook stays pinned to 0.1.5. This creates confusing behavior where local checks differ from pre-commit results.
Analysis of the New Wave of Python Type Checkers
September 17, 2025
Rob Hand’s comparison of emerging type checkers is the first comprehensive look at three new Rust-based tools: ty (Astral), pyrefly (Meta), and zuban (David Halter).
Key Findings
Performance drives the rewrite. All three abandon Python implementations for Rust, targeting the bottlenecks that slow existing checkers on large codebases.
Conformance scores don’t predict usefulness. ty passes only 15% of the typing conformance suite’s tests but works well for everyday Python. The suite apparently focuses on edge cases most developers never hit.
prek: pre-commit, but fast
September 16, 2025
pre-commit is an essential tool in my development workflow for running ruff and [other tools. However, nobody wants to wait for their commits to be saved, and pre-commit isn’t always the fastest.
prek is a Rust-based drop-in replacement that runs 10x faster while using half the disk space.
Replacing pre-commit with prek is painless:
- Install with
uv tool install prek - Run
pre-commit uninstall && prek install
That’s it. No configuration changes, no compatibility issues.
uv format: Code Formatting Comes to uv (experimentally!)
August 21, 2025
The latest uv release (0.8.13) quietly introduced an experimental new command that Python developers have been waiting for: uv format. This addition brings code formatting directly into uv’s toolkit, eliminating the need to juggle multiple tools for basic Python development workflows.
What is uv format?
The uv format command provides Python code formatting through uv’s interface. Under the hood, it calls Ruff’s formatter to automatically style your code according to consistent standards.