Python Developer Tooling Handbook – Python Developer Tooling Handbook

What is PEP 810?

Tim Hopper — Fri, 08 May 2026 03:22:32 -0400

PEP 810: Explicit Lazy Imports adds a lazy keyword in front of an import or from statement that defers loading the module until the imported name is first used. Authored by Pablo Galindo Salgado, Germán Méndez Bravo, Thomas Wouters, and others, the PEP was accepted unanimously by the Steering Council on 3 November 2025 for Python 3.15. Python 3.15 reached beta 1 on 7 May 2026, the first build to ship the feature. PEP 810 is the second attempt at lazy imports in CPython after the implicit-everywhere PEP 690 was withdrawn in 2023; the explicit, opt-in design is the trade that got 810 across the line.

How to use uv with VS Code devcontainers

Tim Hopper — Fri, 08 May 2026 03:19:53 -0400

A devcontainer hands every teammate the same Python interpreter and the same locked dependencies. uv makes that hand-off cheap: a single uv sync --locked reads uv.lock and installs the resolved graph in seconds, on every machine.

This guide configures a VS Code devcontainer that uses uv to materialize the project’s virtual environment inside the container, points VS Code at the in-container interpreter, and uses the lockfile to keep team environments in sync.

Note

ty: Python Type Checker by Astral

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

ty (pronounced tee-why) is a static type checker and language server for Python from Astral (creators of Ruff and uv). It performs static analysis on Python code to identify type-related issues before runtime.

ty was initially known by the code name “Red-Knot” during its early development phase. The tool is in beta, with a stable 1.0 release targeted for 2026.

When to use ty

Use ty when you want a fast type checker that provides near-instant feedback during development, especially in a large codebase where mypy or pyright feel slow. Its “gradual guarantee” ensures that adding type annotations to working code never introduces new errors, which makes incremental adoption predictable. If you already use Ruff or uv, ty fits naturally into the same Astral toolchain. For a comparison of all three type checkers, see How do mypy, pyright, and ty compare?.

pyright: Python Static Type Checker by Microsoft

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

pyright is a static type checker and language server for Python, built and maintained by Microsoft. It analyzes type annotations to detect bugs before runtime and provides editor features like autocompletion, hover information, and go-to-definition.

pyright powers the Pylance extension for Visual Studio Code. Pylance is closed-source and adds features on top of pyright’s open-source language server, but pyright itself can be used with any editor that supports LSP.

When to use pyright

pyright is a strong choice for teams that want real-time type feedback in their editor, especially in VS Code through the Pylance extension. Its aggressive type inference catches bugs in unannotated code that mypy would skip by default.

Pyrefly: Python Type Checker by Meta

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

Pyrefly is a static type checker and language server for Python, developed by Meta. It performs static analysis on Python code to identify type-related issues before runtime and provides IDE features like code navigation, autocompletion, and semantic highlighting.

Pyrefly is a clean-slate implementation inspired by Meta’s earlier Pyre type checker. It uses a new type inference engine, a custom incremental computation model, and multi-threaded parallel checking.

When to use Pyrefly

Pyrefly is worth evaluating for large Python codebases where mypy or pyright feel slow and where aggressive type inference that catches errors in unannotated code is desirable. Its conformance score (90% of the typing spec test suite as of April 2026, per the Python typing conformance dashboard) is higher than mypy and ty, though lower than pyright and Zuban (another Rust-based checker).

pyproject.toml: The Standard Python Project Configuration File

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

pyproject.toml is the standard configuration file for a Python project. It is written in TOML and lives in the project root. A single file captures three kinds of information that older Python projects scattered across setup.py, setup.cfg, MANIFEST.in, requirements.txt, .flake8, mypy.ini, pytest.ini, and tox.ini: project metadata, build-system requirements, and third-party tool configuration.

PEP 518 introduced pyproject.toml in 2016 to declare build-system requirements in a tool-agnostic way. PEP 621 extended it in 2020 with a standardized [project] table for project metadata. Together, the two PEPs make pyproject.toml the canonical home for a Python project’s configuration.

How to use ty in CI

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

ty can run in CI with no installation step beyond uv. Because ty is a single binary with no runtime dependencies, it adds minimal overhead to your pipeline.

GitHub Actions

The simplest approach uses uvx to run ty without adding it as a project dependency:

- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v7
- run: uvx ty check src/

To get inline annotations on pull requests, use the github output format:

How to migrate from pyright to ty

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

ty is a Python type checker developed by Astral (the creators of uv and Ruff). It ships as a single binary with no runtime dependencies, which eliminates pyright’s Node.js requirement.

ty is currently in beta. While actively developed, it’s still missing some features and may not be ready for full production adoption. This guide helps evaluate readiness and plan for migration.

Understanding ty

When to consider migrating

Projects wanting faster type checking on large codebases
Teams already using other Astral tools (Ruff, uv)
Projects wanting to eliminate Node.js dependency
Projects without complex platform-specific dependencies lacking stubs
Projects with simple pyright configuration

When to wait

Projects heavily dependent on pyright-specific features like --verifytypes
Projects requiring typeCheckingMode presets (until ty adds equivalents)
Projects with complex platform-specific dependencies lacking stubs
Projects where pyright’s specific type inference is depended upon

Installation and basic usage

Installing ty

ty is distributed as a standalone binary. The easiest way to use it is via uvx:

How to install the Astral plugins for Claude Code

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

Astral publishes an official Claude Code plugin that bundles three skills (/astral:uv, /astral:ruff, /astral:ty) and a ty language server. The skills give Claude up-to-date usage guidance for each tool, and the language server feeds live type-checking diagnostics into the conversation.

Prerequisites

Claude Code installed
uv installed (required by the ty language server)

Install the plugin for yourself

1. Add the Astral marketplace

Run this slash command inside Claude Code:

How do Python type checkers compare?

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

mypy, pyright, ty, Pyrefly, Basedpyright, and Zuban all analyze type annotations to catch bugs before runtime. They read the same type-hint annotations (from PEP 484, the standard that introduced Python’s type system in 2014) and largely agree on the parts of the spec a working program uses. They disagree on speed, default strictness, treatment of unannotated code, editor integration, and licensing, and those disagreements are what make the choice matter.

Here is the shape of the field in 2026:

Basedpyright: Python Type Checker (pyright Fork)

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

Basedpyright is a static type checker and language server for Python, maintained by DetachHead as a community fork of Microsoft’s pyright. It tracks upstream pyright closely and adds diagnostic rules, stricter defaults, and language-server features that Microsoft keeps exclusive to its closed-source Pylance extension.

The fork exists because pyright ships as an npm package and depends on Node.js, which makes it awkward to pin as a project dependency, and because the editor features most Python developers associate with “pyright” actually live in Pylance, whose license restricts it to official Microsoft VS Code builds. Basedpyright packages the language server on PyPI so uv add --dev basedpyright works, and re-implements Pylance-style features (inlay hints, semantic highlighting, docstring completion) in the open-source server so VS Code forks like Cursor, VSCodium, and Positron can use them.

pylint: Python Static Code Analyzer

Tim Hopper — Fri, 08 May 2026 03:18:58 -0400

pylint is a static code analysis tool that identifies programming errors, coding standard violations, and potential bugs in Python code. It analyzes source code without running it to find issues from basic syntax errors to complex design problems.

When to use pylint

Pylint fits codebases that depend on its semantic checks, such as cyclomatic complexity, duplicate-code detection, and design-rule enforcement that go beyond what style-focused linters catch. Teams with an established .pylintrc and CI pipelines tuned around its output keep a familiar tool backed by a long-running plugin ecosystem.

flake8: Python Linter

Tim Hopper — Fri, 08 May 2026 03:18:58 -0400

Flake8 has been largely superseded by newer tools like Ruff, which offer significantly faster performance and more features. Consider using Ruff for new projects.

Flake8 is a Python linting tool that enforces style consistency and checks for programming errors. It combines multiple code quality tools into a single interface: PyFlakes for logical errors, pycodestyle for style checking, and mccabe for code complexity checking.

Black: Python Code Formatter

Tim Hopper — Fri, 08 May 2026 03:18:58 -0400

Black is an opinionated Python code formatter that automatically formats Python code to conform to a strict subset of PEP 8. Black deliberately offers minimal configuration options, aiming to end arguments about code formatting by providing “one way” to format code.

Consider using Ruff instead of Black. Ruff provides the same formatting capabilities but with significantly better performance. Ruff also includes linting, import sorting, and other code quality tools in a single high-performance package.

When to use Black

Black suits codebases that already run it in CI or pre-commit hooks and teams that want a zero-config formatter to end style debates. It has been the default Python formatter for years, with stable output that editor plugins, pre-commit hooks, and CI configurations across the ecosystem rely on.

Build a Python library with a C++ extension

Tim Hopper — Fri, 08 May 2026 03:18:44 -0400

Python handles most tasks well, but numerical code and tight loops can hit its performance ceiling. C++ removes that ceiling. This tutorial walks you through creating a Python package where the performance-critical code lives in C++, compiled into a native extension module that Python imports like any other module.

You’ll use three tools together:

uv manages the Python project, dependencies, and virtual environment
scikit-build-core is the build backend that drives CMake to compile C++ code into a Python extension module
pybind11 is the C++ library that bridges C++ and Python, letting you write C++ functions callable from Python

Prerequisites

uv installed (installation guide)
A C++ compiler (g++ or clang++)
CMake 3.15 or later

Most macOS and Linux systems ship with a C++ compiler. On macOS, install the Xcode Command Line Tools (xcode-select --install). On Ubuntu/Debian, install the build-essential and cmake packages.

What is PEP 829?

Tim Hopper — Thu, 07 May 2026 13:56:14 -0400

PEP 829: Package Startup Configuration Files splits the two jobs that .pth files do today into two separate files. .pth keeps the sys.path extension job. A new <name>.start file takes over package initialization, replacing the import line that turns every .pth file into an exec() surface at interpreter startup. Authored by Barry Warsaw and accepted on 24 April 2026 for Python 3.15. Python 3.15 reached beta 1 on 7 May 2026, the first build to ship the .start mechanism for package authors to test against.

What is CPython's JIT Compiler?

Tim Hopper — Thu, 07 May 2026 13:56:14 -0400

CPython’s JIT compiler is an experimental feature, introduced in Python 3.13, that translates frequently executed Python bytecode into machine code while a program runs. It is off by default and requires no changes to Python source code. Its goal is to make CPython faster over successive releases without asking developers to switch runtimes or rewrite anything.

How CPython runs code without the JIT

CPython compiles .py files into bytecode, a compact set of instructions stored in .pyc files. The interpreter then executes those instructions one at a time in a loop: fetch the next bytecode, dispatch to the C function that implements it, repeat. Every Python program pays the cost of that fetch-and-dispatch cycle on every instruction.

Sampling vs deterministic profilers: which should I use?

Tim Hopper — Thu, 07 May 2026 13:56:14 -0400

Two different designs dominate Python profiling, and they produce two different kinds of lies about your program. A deterministic profiler intercepts every function call, records the entry and exit, and tallies the total. A sampling profiler peeks at the call stack on a timer and counts how often each function shows up. Both give you a list of hot functions, and the list will not always agree.

The difference matters because the choice changes what you can trust about the output.

profiling.sampling: Statistical Profiler in the Standard Library

Tim Hopper — Thu, 07 May 2026 13:56:14 -0400

profiling.sampling is the statistical sampling profiler that ships with Python 3.15, developed under the codename Tachyon. It samples the call stacks of a Python process on a timer rather than instrumenting every call, and it can attach to a process that is already running by PID. The CLI is invoked as python -m profiling.sampling, with run and attach as the two profiling entry points, dump for a single stack snapshot, and replay for converting saved binary profiles to other output formats.

How to Test Against Multiple Python Versions Using uv

Tim Hopper — Thu, 07 May 2026 13:56:14 -0400

A library that works on Python 3.11 can break on 3.12 because of removed deprecations, C API changes, or subtle differences in standard library behavior. Catching these failures before your users do requires running tests against each version you support. uv makes this straightforward: it downloads Python versions on demand, so there is no need to install them yourself.

Prerequisites

uv installed on your system
A Python project with pytest configured as a dependency (see Setting up testing with pytest and uv)

Run Tests Against a Single Alternate Version

Pass --python to select a specific Python version:

What is PEP 517/518 compatibility?

Tim Hopper — Thu, 07 May 2026 07:17:13 -0400

PEP 518 introduced pyproject.toml in 2016 and defined the [build-system] table for declaring build-time dependencies in a tool-agnostic way. PEP 517 followed in 2017 and defined the hook API that every build backend implements and every build frontend calls. Together they replaced the setup.py-only build model and made it possible to use Hatchling, flit_core, poetry-core, uv_build, maturin, or any other backend with the same install commands.

The problem the PEPs solved

Before PEP 518, every Python package was built by running setup.py, a Python script that imported setuptools (or the older distutils) and called functions to declare metadata, list dependencies, and produce build artifacts. The installer had to execute setup.py to discover anything about the package, including which build dependencies the script itself needed. That ordering created a circular requirement: setuptools had to already be present before the installer could ask the project what it required.

Briefcase

Tim Hopper — Thu, 07 May 2026 07:15:39 -0400

Briefcase is the only mainstream Python packaging tool that ships to iOS and Android. It also packages applications for macOS, Windows, Linux, and the Web, producing platform-specific artifacts (.app/DMG, MSI, .deb/.rpm/AppImage/Flatpak, Xcode project, Gradle project, PyScript/Pyodide site) from a single pyproject.toml configuration.

Briefcase is part of the BeeWare project and is the packaging companion to Toga, BeeWare’s cross-platform GUI toolkit. Briefcase does not require Toga; it packages any Python application, GUI or otherwise. Install it with uv tool install briefcase or pipx install briefcase; the BSD 3-Clause license imposes no restrictions on applications it packages.

Run your first Python script with uv

Tim Hopper — Thu, 07 May 2026 07:15:18 -0400

uv can run Python scripts without any prior Python installation. This tutorial starts with a one-line script and builds up to using a third-party package through inline script metadata.

Prerequisites

Install uv on your system.

Tip

Setting up GitHub Actions with uv

Tim Hopper — Wed, 06 May 2026 06:25:49 -0400

Every push to main and every pull request should be tested and linted automatically. This tutorial sets up that pipeline using GitHub Actions and uv, running pytest and Ruff across multiple Python versions.

Prerequisites

uv installed (installation guide)
A GitHub account
Familiarity with setting up testing with pytest and uv

Clone the Example Project

This tutorial uses a small temperature-converter project with code and tests already written but no CI configured. Clone it and move into the directory:

pipx: Install Python CLI Tools in Isolation

Tim Hopper — Wed, 06 May 2026 06:23:54 -0400

pipx is a command line tool to install and run Python command line applications in isolated environments. Each installed application gets its own virtual environment, preventing dependency conflicts between tools while making their executables available on your PATH.

When to use pipx

Reach for pipx when installing standalone Python CLI tools (ruff, csvkit, httpie, cookiecutter) that should stay isolated from any project’s virtual environment and remain on PATH across shell sessions. It fits teams that already have pipx wired into setup scripts, documentation, or CI and prefer a narrowly-scoped tool over a general-purpose one. For new installations, uv provides equivalent isolation through uv tool install and uvx while also handling Python version and project management in the same binary.

Hatch: Python Project Manager

Tim Hopper — Wed, 06 May 2026 06:23:54 -0400

hatch is a Python project management tool maintained by the Python Packaging Authority (PyPA). It handles virtual environment management, dependency resolution, project scaffolding, and publishing through a unified interface that follows Python packaging standards. Its build backend, hatchling, is one of the most widely used on PyPI.

When to Use Hatch

Hatch suits library authors who want a single, standards-compliant tool covering scaffolding, building, publishing, and multi-version testing. Its environment matrix system runs tests across Python versions and dependency sets without a separate tool like tox or nox. PyPA governance backs the project.

How to write Claude Code hooks for Python projects

Tim Hopper — Wed, 06 May 2026 06:23:27 -0400

Claude Code hooks are scripts that run at specific points during a session, letting you enforce project conventions programmatically. A CLAUDE.md file suggests how Claude should behave; hooks guarantee it by blocking disallowed commands, auto-formatting files, or injecting context before Claude sees your prompt. See the official hooks documentation for the full reference.

How hooks work

Hooks fire on events during a Claude Code session. Claude Code supports over 25 event types (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop, and more). This guide covers the four most useful for Python projects:

How to use Python skills with Claude Code

Tim Hopper — Wed, 06 May 2026 06:23:27 -0400

Skills bottle up your Python workflow. Instead of re-explaining “tighten these type annotations” or “use uv instead of pip” every session, save the procedure to a markdown file once and let Claude Code reach for it when you ask, either by slash command or by describing the task in plain English. Long reference material that would crowd a CLAUDE.md only loads when the skill runs.

This guide installs the Astral plugin, walks through writing a custom Python skill, and shows when a skill beats CLAUDE.md or a hook.

How to Set Up CLAUDE.md for a Python Project

Tim Hopper — Wed, 06 May 2026 06:23:27 -0400

Claude Code reads a CLAUDE.md file in your project root every session. Without one, it falls back to pip install, bare python commands, and setup.py.

The Python Developer Tooling Handbook maintains a CLAUDE.md template for Python projects using uv, Ruff, and pytest.

What the template covers

Package management with uv (uv add, uv run, uv sync instead of pip)
Project creation with uv init and pyproject.toml (never setup.py)
Testing with pytest (discovery conventions, file layout, execution)
Linting and formatting with ruff
Type checking with ty or mypy
Pre-commit hooks with prek or pre-commit
Anti-patterns Claude should avoid (manual venvs, pip install, requirements.txt)

At 86 lines, the template stays inside Anthropic’s recommended 200-line limit for CLAUDE.md files.

How to configure Ruff with Claude Code

Tim Hopper — Wed, 06 May 2026 06:23:27 -0400

Claude Code does not run Ruff by default, so Python edits land unformatted and lint errors slip through unless you wire Ruff in yourself. Out of the box, Claude often calls bare ruff (which may resolve outside the project’s virtual environment) and skips formatting after edits. Wiring Ruff in correctly takes four layers, each with a different job.

This guide covers all four and how they stack together:

A CLAUDE.md instruction that points Claude at Ruff
The Astral plugin’s /astral:ruff skill for on-demand Ruff guidance
A PostToolUse hook that auto-formats every Python edit
A pre-commit gate that catches anything Claude missed before commit time

Prerequisites

Claude Code installed
uv installed
A Python project with Ruff added as a dev dependency (uv add --dev ruff)
jq installed if you want to use the shell version of the auto-format hook

Pick the right layer for your goal

Each layer answers a different question. Pick the ones that match what you actually need; nothing requires installing all four.

How to configure Claude Code to use virtual environments

Tim Hopper — Wed, 06 May 2026 06:23:27 -0400

Claude Code starts a fresh shell for every Bash tool call, so source .venv/bin/activate in one command has no effect on the next. Without configuration, Claude reaches for system Python and installs packages outside the project’s virtual environment. Four configuration patterns work around the stateless-shell limitation:

uv run for projects on uv, which sidesteps activation entirely
A CLAUDE.md instruction that tells Claude to call the venv’s interpreter directly
A .claude/settings.json env block that pre-sets VIRTUAL_ENV and PATH for every session
A PreToolUse hook that blocks bare python and pip so the rules are enforced, not just suggested

Trace why `source activate` doesn’t persist

Each Bash tool call Claude Code runs spawns a separate shell process. Environment changes made by source .venv/bin/activate (it sets VIRTUAL_ENV and prepends .venv/bin to PATH) live only inside that shell. When the next tool call starts a new shell, those variables are gone.

How to configure Claude Code to use uv

Tim Hopper — Wed, 06 May 2026 06:23:27 -0400

Claude Code defaults to pip when it needs to install packages or run scripts. A CLAUDE.md file in your project root overrides that default so every session uses uv instead.

Tip

Claude Code for Python: A Complete Guide

Tim Hopper — Wed, 06 May 2026 06:23:27 -0400

Claude Code is a terminal-based AI assistant that reads your files, runs commands, edits code, and iterates on errors. Describe what you want in plain English, and Claude Code determines which files to read, which commands to run, and what code to write. When something breaks, it reads the error, adjusts, and tries again.

This guide covers how to use Claude Code for Python development specifically. Each section is self-contained, so skip to whatever is relevant.

How to set up prek hooks for a Python project

Tim Hopper — Wed, 06 May 2026 06:22:32 -0400

This guide assumes you have a Python project managed with uv. If you haven’t created a project yet, see the project creation tutorial.

prek is a fast drop-in replacement for pre-commit that runs hooks faster, uses less disk space, and ships as a single binary with no Python dependency. It reads the same .pre-commit-config.yaml files, so the configuration in this guide also works with pre-commit. See the pre-commit version of this guide for the original tool.

How to set up pre-commit hooks for a Python project

Tim Hopper — Wed, 06 May 2026 06:22:32 -0400

This guide assumes you have a Python project managed with uv. If you haven’t created a project yet, see the project creation tutorial.

pre-commit is a framework that manages Git hooks. It runs tools like linters and formatters automatically before each commit, catching problems before they reach version control. This guide walks through installing pre-commit, configuring hooks for a Python project, and integrating it with Ruff and mypy.

How to migrate from Black to Ruff formatter

Tim Hopper — Wed, 06 May 2026 06:22:32 -0400

Ruff’s ruff format command is a drop-in replacement for Black. It follows the same formatting style, reads the same defaults (88-character lines, double quotes, space indentation), and formats 10-100x faster. Ruff also handles linting and import sorting, so the migration is often a chance to consolidate three tools (Black, flake8, isort) into one.

This guide covers translating Black’s configuration, reformatting the codebase, updating pre-commit hooks, and updating CI.

Check your starting point

Commit any pending changes. The migration reformats files, so starting from a clean working tree makes the diff easy to review.
Note your current Black version. Ruff’s formatter tracks Black’s stable style; the reformatting diff should be empty or nearly empty if your project already runs a recent Black release.

Add Ruff to the project

Add Ruff as a development dependency:

How to configure Ruff for Django

Tim Hopper — Wed, 06 May 2026 06:22:32 -0400

Ruff’s default rule set knows nothing about Django. It will not flag CharField(null=True), but it will flag every long line in an auto-generated migration. This guide fixes that: enable the DJ rule set, give Ruff the per-file ignores Django’s generated code needs, and produce a configuration block that catches Django-specific bugs without burying them under noise.

This guide assumes a working Django project. Follow Set up a Django project with uv first if there isn’t one yet.

Ruff: A Complete Guide to Python's Fastest Linter and Formatter

Tim Hopper — Wed, 06 May 2026 06:22:32 -0400

Ruff replaces flake8, Black, isort, pyupgrade, pydocstyle, and dozens of other Python code quality tools with a single binary. It re-implements over 1,000 lint rules from dozens of existing tools and runs 10-100x faster than the tools it replaces.

Astral (the team behind uv and ty) builds and maintains Ruff.

Why Ruff exists

Ruff gives Python developers a single tool for linting, formatting, import sorting, and code modernization. One dev dependency, one configuration section in pyproject.toml, one CI step. It ships as a standalone binary with no runtime dependencies, so installation is fast and there are no version conflicts to manage.

How to configure recommended Ruff defaults

Tim Hopper — Tue, 05 May 2026 16:21:56 -0400

This guide assumes you have a Python project set up. If you haven’t created a project yet, see the project creation tutorial before proceeding.

This guide shows how to configure Ruff with a curated set of linting rules that extend beyond the defaults. When starting a new project, it’s easier to enable a comprehensive set of rules from the beginning and selectively disable any that don’t fit the project’s needs, rather than gradually adding rules later when there’s already code to fix.

Set up a data science project with uv

Tim Hopper — Tue, 05 May 2026 06:58:20 -0400

This tutorial sets up a data analysis project with uv so that every dependency is pinned, notebooks run in the right environment, and a collaborator can reproduce your setup with a single command.

Prerequisites

Install uv following the installation guide. No separate Python install is required.

Create the project

$ uv init weather_analysis
Initialized project `weather-analysis` at `/path/to/weather_analysis`
$ cd weather_analysis

This creates a project directory with a pyproject.toml, a main.py, and a README.md. The pyproject.toml stores all project metadata and dependencies:

Set up a Django project with uv

Tim Hopper — Tue, 05 May 2026 06:57:20 -0400

Most Django setup guides still tell you to install Python and a virtual environment by hand before you reach runserver. This tutorial uses uv for the Python install and the virtual environment. Every manage.py command runs against a pinned interpreter.

Confirm uv is installed

If you do not already have uv, follow the installation guide. No separate Python install is required; uv will download an interpreter on first use.

mypy: Python Static Type Checker

Tim Hopper — Tue, 05 May 2026 06:57:20 -0400

mypy is a static type checker for Python that analyzes type annotations to detect bugs before runtime. It has been the default Python type checker since 2012 and has the broadest ecosystem support of any Python type checking tool.

When to use mypy

Use mypy when you want to catch type-related bugs before runtime by adding static type checking to a Python project. It is the most established Python type checker with broad ecosystem support, making it a reliable default for projects that are adopting type annotations incrementally. For faster checking or tighter VS Code integration, consider pyright; for an emerging alternative from the creators of Ruff, see ty.

Zuban: Mypy-Compatible Python Type Checker

Tim Hopper — Tue, 05 May 2026 06:56:59 -0400

Zuban is a static type checker and language server for Python, written in Rust by David Halter, author of Jedi (the longstanding Python autocompletion library) and parso. It runs in two modes: zuban mypy (aliased as zmypy) behaves as a mypy-compatible drop-in, and zuban check applies a pyright-style inference strategy.

Zuban launched as open source under AGPL-3.0 in September 2025, with a paid commercial license available for organizations that cannot accept AGPL’s source-disclosure requirements. That licensing split is the tool’s most load-bearing distinguishing factor: it funds full-time development in a way that MIT-licensed competitors cannot, but it also rules Zuban out for many proprietary codebases unless the team buys a commercial license.

What is a Python language server?

Tim Hopper — Tue, 05 May 2026 06:56:59 -0400

Type a dot after a variable in your editor and a list of methods appears. Hover a function and its signature shows up in a tooltip. Right-click an import and “Go to definition” jumps to the source. Most Python developers have used these features for years without knowing the name of the program behind them.

That program is a language server. It is a separate process running alongside your editor, and it is doing most of the work readers usually credit to “the editor.” Naming it explains why VS Code, Neovim, Cursor, and Zed give you the same autocomplete on the same file, and why a faster type checker makes your editor feel faster.

How to configure mypy and django-stubs in a uv project

Tim Hopper — Tue, 05 May 2026 06:56:59 -0400

Run mypy on a Django project without django-stubs and the first error is Need type annotation for "name" on every model field. mypy cannot infer that models.CharField(max_length=200) resolves to str or that Question.objects.filter() returns a QuerySet[Question]. The django-stubs package and its bundled mypy plugin fill those gaps.

This guide installs both with uv and configures everything from a single pyproject.toml, with an override pattern for adopting type checking gradually on a legacy Django codebase.

How to deploy a uv project to AWS Lambda

Tim Hopper — Tue, 05 May 2026 06:55:50 -0400

AWS Lambda packages a Python function as either a zip archive (up to 250 MB unzipped) or a container image (up to 10 GB). Both formats need every dependency the function imports, compiled for Lambda’s Linux runtime, with no virtual environment and no pip install step at runtime. uv is fast at producing exactly that shape, and its lockfile makes the resulting deployment reproducible.

Pick a packaging format

Format	Pick when
Container image	Production services, dependencies near or above the 250 MB zip limit, native libraries that don’t ship manylinux wheels, image-based local testing.
Zip archive	Small functions, simple dependencies, fastest cold starts on Python managed runtimes.
Lambda layer + zip	Dependencies change rarely, function code changes often.

The zip and layer paths use the same uv export + uv pip install --target recipe; only the zip layout differs. The container path uses Lambda’s official Python base image and uv pip install at build time.

Why should I use a virtual environment?

Tim Hopper — Tue, 05 May 2026 06:54:22 -0400

A virtual environment is an isolated Python runtime environment that allows you to work on different Python projects with different dependencies without conflicts. Virtual environments are fundamental to Python development.

The Problem Virtual Environments Solve

Real-world analogy

Think of a virtual environment like a clean workshop for each project. Instead of having all your tools mixed together in one garage (which could lead to version conflicts or missing dependencies), each project gets its own dedicated space with exactly the tools it needs.

When you install Python packages globally (directly into your system Python), several problems arise:

virtualenv: Python Virtual Environment Tool

Tim Hopper — Tue, 05 May 2026 06:54:22 -0400

virtualenv creates isolated Python virtual environments. Virtual environments are self-contained directories that contain a Python installation for a particular version of Python, plus additional packages.

When to use virtualenv

virtualenv fits projects that need broader Python version support than the standard library’s venv module offers, or that benefit from its faster environment creation through cached seed packages. Most modern projects on Python 3.3 or later can use venv, which ships in the standard library and covers the same core workflow without an extra dependency. For new work, uv creates and manages virtual environments automatically as part of its run and sync commands, removing most of the manual steps either tool requires.

pyenv: Python Version Manager

Tim Hopper — Tue, 05 May 2026 06:54:22 -0400

pyenv is a command-line tool for installing, managing, and switching between multiple Python interpreter versions on macOS and Linux. It intercepts Python commands through shell shims, routing them to whichever interpreter version is active for the current directory, user, or system.

When to use pyenv

pyenv fits workflows where Python version management should remain separate from package management. It pairs with pip, venv, or any other packaging tool without imposing opinions on how dependencies are managed. If you want a single tool that also handles dependencies and virtual environments, uv covers version management alongside those workflows.

Create your first Python project with uv

Tim Hopper — Mon, 04 May 2026 10:58:58 -0400

This Python uv tutorial walks you through building a text analysis tool that counts words, measures sentence length, and reports word frequency. No prior Python experience required; uv handles the Python install, project scaffolding, and dependency management for you.

Prerequisites

Before we begin, make sure you have uv installed on your system. You can install it following the directions from the uv documentation.

Tip

Python Developer Tooling Handbook – Python Developer Tooling Handbook

What is PEP 810?

How to use uv with VS Code devcontainers

ty: Python Type Checker by Astral

When to use ty

pyright: Python Static Type Checker by Microsoft

When to use pyright

Pyrefly: Python Type Checker by Meta

When to use Pyrefly

pyproject.toml: The Standard Python Project Configuration File

How to use ty in CI

GitHub Actions

How to migrate from pyright to ty

Understanding ty

When to consider migrating

When to wait

Installation and basic usage

Installing ty

How to install the Astral plugins for Claude Code

Prerequisites

Install the plugin for yourself

1. Add the Astral marketplace

How do Python type checkers compare?

Basedpyright: Python Type Checker (pyright Fork)

pylint: Python Static Code Analyzer

When to use pylint

flake8: Python Linter

Black: Python Code Formatter

When to use Black

Build a Python library with a C++ extension

Prerequisites

What is PEP 829?

What is CPython's JIT Compiler?

How CPython runs code without the JIT

Sampling vs deterministic profilers: which should I use?

profiling.sampling: Statistical Profiler in the Standard Library

How to Test Against Multiple Python Versions Using uv

Prerequisites

Run Tests Against a Single Alternate Version

What is PEP 517/518 compatibility?

The problem the PEPs solved

Briefcase

Run your first Python script with uv

Prerequisites

Setting up GitHub Actions with uv

Prerequisites

Clone the Example Project

pipx: Install Python CLI Tools in Isolation

When to use pipx

Hatch: Python Project Manager

When to Use Hatch

How to write Claude Code hooks for Python projects

How hooks work

How to use Python skills with Claude Code

How to Set Up CLAUDE.md for a Python Project

What the template covers

How to configure Ruff with Claude Code

Prerequisites

Pick the right layer for your goal

How to configure Claude Code to use virtual environments

Trace why source activate doesn’t persist

How to configure Claude Code to use uv

Claude Code for Python: A Complete Guide

How to set up prek hooks for a Python project

How to set up pre-commit hooks for a Python project

How to migrate from Black to Ruff formatter

Check your starting point

Add Ruff to the project

How to configure Ruff for Django

Ruff: A Complete Guide to Python's Fastest Linter and Formatter

Why Ruff exists

How to configure recommended Ruff defaults

Set up a data science project with uv

Prerequisites

Create the project

Set up a Django project with uv

Confirm uv is installed

mypy: Python Static Type Checker

When to use mypy

Zuban: Mypy-Compatible Python Type Checker

Trace why `source activate` doesn’t persist