Python Developer Tooling Handbook – Python Tooling Explained

uv: A Complete Guide to Python's Fastest Package Manager

Tim Hopper — Mon, 04 May 2026 08:09:53 -0400

uv replaces a half-dozen traditional Python tools with a single binary: interpreter installation, virtual environments, dependency management, version locking, CLI tools, and code formatting. In benchmarks, it creates virtual environments 50x faster than python -m venv and installs packages 5-40x faster than pip depending on cache state.

Note

ty: A Complete Guide to Python's Fastest Type Checker

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

ty is a Python type checker and language server built by Astral, the team behind Ruff and uv. It checks Python code for type errors an order of magnitude faster than mypy. The same binary that runs ty check in CI also serves as a full language server, powering editor features like completions and go-to-definition.

Why ty exists

ty’s gradual guarantee makes incremental type adoption safe: adding annotations to your code will never introduce new errors. You can annotate a function’s return type and ty won’t flag callers that were already passing the wrong type just because the annotation appeared. Each annotation only narrows existing errors rather than creating new ones.

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.

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.

Why Doesn't the Authoritative Python Packaging Guide Mention the Best Thing that's Happened to Python Packaging?

Tim Hopper — Thu, 27 Feb 2025 14:56:00 +0000

uv is the most widely adopted new Python tool in years, yet the Python Packaging User Guide (PPUG) at packaging.python.org makes no mention of it. The reason has less to do with uv and more to do with how Python packaging governance works.

What uv Does

uv delivers 10-100x faster package operations than pip while consolidating functionality previously spread across multiple utilities (pip, pip-tools, virtualenv, pyenv, and more) into a single tool. Since its introduction in early 2024, it has become the default recommendation in many Python teams and communities.

Can you trust uv long-term?

Tim Hopper — Tue, 28 Apr 2026 16:07:27 -0400

In March 2026, OpenAI acquired Astral, the venture-backed startup behind uv. Before betting a team’s workflow on a tool whose owner’s priorities just changed, the reasonable question is what happens if Astral’s output slows or stops.

The handbook recommends uv. This page lays out why that recommendation survives the trust question, what would have to change before it doesn’t, and what to do today to keep your migration costs low.

Look at what you actually adopt

uv is dual-licensed under Apache 2.0 and MIT. That license cannot be revoked. Every release that has shipped is permanently available to fork, modify, or redistribute. Anyone, including you, can freeze the source tree at any commit and keep using it. No future owner can take that away.

Getting Started with Python Using Codex

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Codex CLI is OpenAI’s terminal-based coding agent. It reads your repository, edits files, runs commands, and iterates on errors, all from your terminal. Describe what you want in plain English, and Codex decides which files to read, which commands to run, and what code to write.

What separates Codex from other terminal agents is how it sandboxes every command the model runs. Codex isolates execution with OS-level enforcement (Seatbelt on macOS, Landlock and seccomp on Linux), not just application-layer checks. This means you can grant Codex more autonomy without worrying that a bad command will reach beyond your project directory or make network calls you didn’t authorize.

Do I need a project to use uv?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

If your Python life is a folder full of short scripts that glue APIs together and rename files, uv’s first move can look like overkill: uv init, then a pyproject.toml. uv works fine for scripts, but it assumes a different mental model from the pip install habit most script authors carry, and forcing the old habit onto uv is where people get stuck.

The short answer: no, you don’t need a project. You have four options, and the right one depends on what the script is.

Do you still need tox or nox if you use uv?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

For many projects, no. uv can run your test suite against multiple Python versions without any extra tool. But tox and nox do more than version switching, and the gap between “run pytest on 3.12” and “test five Python versions against two dependency sets in parallel” is where they still matter.

What uv handles on its own

uv run --python selects a Python version and executes a command in your project’s environment. If that version is not installed, uv downloads it automatically:

Do you still need tox or nox if you use uv?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Before uv, setting up multi-version testing meant installing Python interpreters by hand, configuring pyenv, and hoping tox found them all. uv removes that friction: uv run --python 3.12 pytest downloads Python 3.12 if it’s missing and runs your tests in one command. Teams that discover this often ask whether tox or nox are still worth the dependency.

The short answer: uv replaces the plumbing (Python installs, virtual environment creation, dependency installation), not the orchestration. Whether you still need an orchestrator depends on what you’re asking it to do.

Does Poetry Support Python Standards for Dependency Management?

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

Poetry 2.0 supports standard PEP 621 project metadata in pyproject.toml. Before version 2.0, Poetry used only its own tool.poetry configuration format, but the 2.0 release adopted the standard project section.

Poetry now offers two configuration approaches. You can use project.dependencies for standard dependency declarations or tool.poetry.dependencies for Poetry-specific features, and you can combine both when needed.

Standard metadata makes projects more portable between build tools and aligns with emerging packaging standards.

Related Handbook Pages

Learn More

Enough Git to Supervise Your AI Coding Agent

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

AI coding agents like Claude Code, Codex, Cursor, and GitHub Copilot run Git commands on your behalf. You don’t need to memorize those commands, but you do need to understand what they mean. Otherwise you’re approving operations you can’t verify.

When your agent says “I’ve committed the changes and pushed to GitHub,” you should know where those changes went and how to undo them if something is wrong. This article provides that mental model. A companion how-to guide walks through putting your project on GitHub for the first time.

How do I ship a Python application to end users?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Python usually ships an environment rather than a native executable. It ships as code plus an interpreter plus dependencies, which is why distribution gets harder the moment the users are not Python developers themselves. The real question is not whether Python can be shipped well. It can. The question is which delivery shape fits the audience: an install command, a bundled app, a container image, or something that stops being Python at all.

How do pyenv and uv compare for Python interpreter management?

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

pyenv manages Python versions and gets out of the way; uv manages Python versions as part of controlling your entire workflow. That difference in scope shapes every other trade-off between the two tools.

Design Philosophy

pyenv

pyenv embodies the Unix principle of “do one thing well.” Its sole purpose is managing Python interpreter installations and version switching. This focused approach means pyenv integrates seamlessly with existing workflows; after selecting a Python version, developers use familiar tools like pip and venv for package management and virtual environments.

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:

How do Ruff and Pylint compare?

Tim Hopper — Fri, 01 May 2026 06:58:47 -0400

Ruff and Pylint are Python code analysis tools with overlapping but distinct capabilities.

Core Differences

Speed and Architecture

Ruff’s Rust implementation delivers dramatically faster performance than Pylint’s Python codebase. This speed advantage becomes particularly noticeable in large codebases where Ruff can analyze files orders of magnitude faster.

Rule Coverage

While Pylint implements approximately 409 rules, Ruff now exceeds 1,000 total rules, with around 209 overlapping with Pylint’s ruleset. However, these numbers continue to change, especially as Ruff undergoes rapid development.

How do uv and Poetry compare?

Tim Hopper — Fri, 10 Apr 2026 13:36:01 -0400

Poetry and uv both manage Python projects through pyproject.toml, create lockfiles, and handle virtual environments. Poetry has been the default recommendation for years; uv, built by Astral, arrived in 2024 with broader scope and faster dependency resolution. They differ in how.

Scope

Poetry handles dependency management, virtual environments, building, and publishing. Everything else it delegates. A different Python version requires pyenv. Running a CLI tool without installing it globally requires pipx.

How Does Hot Reloading Work in Python?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Every Django developer knows runserver restarts when you save a file. Every FastAPI developer knows uvicorn --reload. But ask “how do I auto-reload my Python script?” and the answer fractures. There is no --watch flag built into the python command, no universal file-watching convention that works across all Python projects.

This fragmentation is not an oversight. It reflects how Python loads and manages code at runtime, and why different development contexts require different reload strategies.

How Python Package Formats Evolved: From tar.gz to .whl

Tim Hopper — Sat, 11 Apr 2026 17:25:27 -0400

In 2000, installing a third-party Python package meant downloading a tarball, extracting it, and running python setup.py install. There was no dependency resolution, no uninstall command, no record of what got installed where. Removing a package meant deleting files by hand and hoping none were missed.

Twenty-five years later, uv pip install numpy fetches a pre-built binary wheel and drops it into place in under a second. The journey between those two moments is a story of each generation solving one problem while inadvertently creating the next.

How Python tools adopt uv under the hood

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

You don’t have to switch to uv to get uv’s speed. Pixi, Hatch, PDM, and tox now use uv’s resolver and installer as their backend, which means your existing tool may already run on uv under the hood.

Which tools use uv

Tool	What it delegates to uv	How to enable
Pixi	PyPI dependency resolution and installation	Automatic (default behavior)
Hatch	Dependency installation and venv creation	`installer = "uv"` in env config
PDM	Dependency resolution and installation	`pdm config use_uv true` (experimental)
tox (via tox-uv)	Dependency installation and venv creation	Install the `tox-uv` plugin
nox	Dependency installation	Enable nox’s uv backend
prek	Python version and venv management for hooks	Automatic

Pixi uses uv by default for all PyPI packages. Prek does the same for hook environments. The rest require opt-in configuration.

Is Conda actually free?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

The conda package manager is open source and always free. The Anaconda repository that ships as the default package source for Anaconda Distribution and Miniconda is not. Confusing “conda” with “Anaconda” causes organizations to either pay for licenses they don’t need or violate terms they didn’t know existed.

What costs money

Anaconda, Inc. operates a curated package repository at repo.anaconda.com. Accessing that repository requires a paid license for any organization (for-profit, nonprofit, or government) with more than 200 employees or contractors. The threshold counts all employees across the entire organization, including affiliates.

Modern Python Project Setup Guide for AI Assistants

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Important

For AI assistants: this guide is meant to be ingested directly. Paste it (or link it) into your project’s CLAUDE.md, AGENTS.md, .cursorrules, or .github/copilot-instructions.md so coding agents follow the same conventions you would. A plain markdown version is available for direct ingestion into agent contexts.

Python Tooling for C# Developers

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Installing .NET gives you everything in one box. Installing Python gives you a box and a list of parts to assemble yourself. The runtime, the dependency sandbox, and the project tooling are separate concerns, maintained by separate communities, and chosen by the developer. That separation is the single biggest adjustment for someone coming from .NET.

This guide maps C#/.NET concepts to their closest Python equivalents and explains where the mental models diverge.

Python Tooling for Go Developers

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Go ships one toolchain that handles compilation, dependency management, testing, formatting, and vetting. Python does not. That single difference explains most of the friction a Go developer will encounter when picking up Python, and most of that friction disappears once the mental model clicks.

What Will Feel Familiar, and What Will Not

Many Go tools have Python counterparts, though the boundaries between them fall in different places.

Python Tooling for Java Developers

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Your first day writing Python, you will look for Maven and not find it. No single tool compiles code, resolves dependencies, runs tests, and packages artifacts in one standardized lifecycle. Python’s tooling is lighter and more modular, with small tools that each handle one concern. This article maps Java concepts to their Python counterparts and explains where the mental models diverge.

What Will Feel Familiar, and What Will Not

Java	Python	Notes
SDKMAN (version installation)	`uv python install`	Python version management (the JDK bundles runtime, compiler, and tools; `uv python install` only provides the interpreter)
Maven / Gradle	uv	Closest single tool for deps/envs/builds (but no standardized lifecycle phases)
pom.xml / build.gradle	pyproject.toml	Central project configuration file
Maven Central	PyPI	Public package registry
JUnit	pytest	Testing framework
Checkstyle / SpotBugs	Ruff	Linting and some bug-pattern checks (partial SpotBugs overlap)
google-java-format	`ruff format`	Code formatting
Java’s static type checking	mypy / pyright / ty	Optional, gradual (separate tools, not a compiler)
`mvn package` / `mvn deploy`	`uv build` + `uv publish`	`uv build` creates distribution artifacts for library publishing; Python has no WAR equivalent
JAR (library)	wheel / sdist	Distribution formats (scoped to library packaging)

Important

Python Tooling for Rust Developers

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Cargo manages dependencies, builds code, runs tests, and publishes crates. Separate tools handle formatting (rustfmt, invoked via cargo fmt) and linting (clippy, via cargo clippy), while rustup manages toolchain installation. Python has no single tool with that scope, but uv comes closest. This article maps Rust tooling concepts to their Python counterparts so Rust developers can orient quickly.

What Will Feel Familiar, and What Will Not

Most Rust workflows have a recognizable Python equivalent:

Python Tooling for TypeScript Developers

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

TypeScript developers moving to Python often expect a single tool like npm that handles everything. Python splits those responsibilities differently, and the reasons behind that split affect how every tool behaves. This guide maps TypeScript/JS concepts to their Python equivalents and covers the daily workflow.

What Will Feel Familiar, and What Will Not

Most TypeScript/JS tools have a reasonable Python counterpart. The table below provides a rough translation.

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.

Should I run `python setup.py`?

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

No. Commands like python setup.py sdist, python setup.py bdist_wheel, and python setup.py install are deprecated.

Instead to build a wheel or sdist, use python -m build (build):

pip install build

python -m build  # builds both sdist and wheel
python -m build --sdist
python -m build --wheel

To install a package, use pip install:

Should I use Homebrew to install Python?

Tim Hopper — Mon, 04 May 2026 08:02:03 -0400

Homebrew ships Python because dozens of its own packages depend on it. Tools like glib, cmake, and awscli all pull in Python as a build or runtime dependency. When Homebrew installs Python, it is satisfying its own dependency graph, not setting up a development environment for you.

This distinction matters because Homebrew treats Python the same way it treats any other dependency: as something to keep current. Running brew upgrade can bump Python from 3.12 to 3.13 without warning, removing the previous minor version’s site-packages directory in the process.

src layout vs flat layout: which to use and why

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

A packaging mistake can pass every local pytest run and still break in production. The choice between flat layout and src layout decides whether your tests catch it before users do.

Compare the two layouts

Flat layout places the package directory directly at the project root:

- pyproject.toml
- README.md
- - __init__.py
  - core.py
- - test_core.py

Src layout nests the package under a src/ directory:

Understanding dependency groups in uv

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

uv separates project dependencies into dependency groups (for development workflows) and optional dependencies (extras, for features shipped to users). Knowing which to use keeps your pyproject.toml clean and your users’ installs lean.

	Dependency groups	Optional dependencies
Audience	Developers of the project	Users of the project
Published to PyPI	No	Yes
pyproject.toml section	`[dependency-groups]`	`[project.optional-dependencies]`
Install syntax	`uv sync --group test`	`uv sync --extra viz`
Typical contents	pytest, ruff, sphinx	matplotlib, boto3

Separate the tools from the product

The [project] table in pyproject.toml declares the packages that every user of a library or application needs:

Understanding the Conda/Anaconda Ecosystem

Tim Hopper — Fri, 10 Apr 2026 11:13:55 -0400

Conda is not Anaconda. Conda is a package manager; Anaconda is a distribution that bundles conda with over 1,500 pre-installed packages. Confusing the two is common, and it leads to choosing the wrong installer or paying for a commercial license you don’t need.

The conda ecosystem operates as a parallel system to Python’s standard packaging tools like PyPI, pip, and virtual environments. Conda uses its own package format, repository structure, and environment management. The two ecosystems can coexist, but they work independently.

uv for Non-Python Teams

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

A Java shop ships a database. In the corner of the repo sits a 200-line Python script that reshapes CI logs for humans. Nobody writes Python full time, but every new hire inherits it and spends an afternoon getting python3 to find the right pandas. That’s the tax for not being a Python shop.

uv removes it. For teams whose primary language isn’t Python, uv is the whole Python toolchain: one binary that replaces pip, virtualenv, pyenv, pipx, and pip-tools well enough that the Python onboarding doc shrinks to two lines.

uv init: project types, flags, and examples

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

The uv command uv init creates a new Python project with a pyproject.toml, a virtual environment, and a lockfile. Different flags produce different project layouts — applications, reusable libraries, packageable CLI tools, or a minimal scaffold — each suited to a specific use case.

Flag	Build System	Structure	Entry Point	Distribution	Use Case
`--app` (default)	No	Flat	`main.py`	Not intended	Web apps, scripts
`--lib`	Yes	`src/` layout	None	PyPI packages	Reusable libraries
`--package`	Yes	`src/` layout	Console script	Installable apps	CLI tools
`--bare`	No	Minimal	None	Manual setup	Custom projects
`--no-package`	No	Flat	`main.py`	Explicitly blocked	Internal apps

Common uv init commands

`uv init my-project`

The default form creates a new directory and an application project inside it:

uv vs pixi vs conda for Scientific Python

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Your scientific Python project needs CUDA, GDAL, or HDF5, and pip install cannot help. Which tool should manage those native dependencies alongside your Python code? The answer depends on where your packages live: PyPI, conda-forge, or both.

Three tools cover the spectrum. uv installs from PyPI. pixi installs from conda-forge and PyPI together. conda installs from conda channels.

What each tool can install

uv resolves packages from PyPI, plus Git URLs, local paths, and private indexes. It cannot install non-Python dependencies like the CUDA toolkit, GDAL, or HDF5.

Versioning Python packages: SemVer, CalVer, and PEP 440

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Every Python package that lands on PyPI carries a version string. Three names show up whenever teams argue about what should be in it: PEP 440, Semantic Versioning (SemVer), and Calendar Versioning (CalVer). They describe different layers, and confusing them produces the kind of debate that burns an hour of standup and ships nothing.

PEP 440 is the grammar. It defines what a legal Python version string looks like and how releases sort. Every installer, from pip to uv to Poetry, enforces it. SemVer and CalVer are policies. They tell maintainers what the numbers should mean, not whether they’re allowed. A project can follow either policy (or neither) and still be valid PEP 440.

What are Optional Dependencies and Dependency Groups?

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

Optional Dependencies: End-User Features

Optional dependencies, defined in pyproject.toml under [project.optional-dependencies] (part of the PEP 621 standard), are designed to:

Package optional features that some users may want
Allow users to install specific feature sets using the pip install package[extra] syntax
Get published to PyPI along with the package

For example:

[project.optional-dependencies]
aws = [
    "boto3>=1.26.0",
    "s3fs>=2023.1.0",
]
visualization = [
    "matplotlib>=3.7.0",
    "seaborn>=0.12.0",
]

This allows users to choose the features they need:

What Are Wheel Variants?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

A default NumPy wheel for x86_64 has to run on every x86-64 CPU that has ever shipped, with the baseline instruction set fixed when AMD64 was defined in 2003. Every SIMD instruction Intel and AMD have added since then is off-limits to the installer, because a wheel filename has no place to declare “needs AVX2” or “needs SSE4”. On scientific workloads, Ralf Gommers of Quansight put the performance left on the table at 10x to 20x.

What Happens When You Run `uv run`

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

uv doesn’t replace Python. It orchestrates Python. When you type uv run pytest, uv sets up the right environment and then hands off to a real Python interpreter to do the actual work. The command is equivalent to activating a virtual environment and running python -m pytest inside it, except uv handles every setup step automatically.

That setup involves finding your project, choosing a Python interpreter, creating or reusing a virtual environment, checking the lockfile, and syncing packages. Each step short-circuits if the work is already done, which is why uv run feels instant on repeated invocations but takes longer the first time.

What is a .python-version file?

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

A .python-version file is a simple text file that specifies which Python version should be used for a particular project or directory. When present, Python version management tools like uv and pyenv automatically use the specified Python version when working in that directory.

The file contains a single line with a Python version specification, e.g.,

3.11.5

This approach provides environment-specific Python version control without requiring manual activation or configuration each time you work on a project.

What is a build backend?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

A build backend is a library that turns your Python source code into distributable packages: wheels and sdists. It reads your project metadata, processes your source tree, and produces the archives that get uploaded to PyPI or installed locally.

Build backends work in tandem with build frontends. The frontend is the tool a developer invokes (uv, pip, python -m build). It typically creates an isolated build environment, installs the backend and its dependencies, and calls standardized hook functions. The backend does the actual work of producing artifacts. All PEP 517-compliant backends implement the same hook API; the mandatory hooks are build_wheel and build_sdist, so any compliant frontend can invoke any backend without special-case code.

What is a build frontend?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

A build frontend is a tool that invokes build backends to create Python packages. It provides the user interface and orchestrates the build process while delegating the build work to build backends.

Common Build Frontends

pip: Default package installer, builds during installation
build: Dedicated PEP 517 builder from PyPA
uv: High-performance alternative to pip
poetry/hatch/pdm: Full-featured project management tools with build capabilities

Key Responsibilities

Discovering and loading build backends
Managing build environments
Handling build configuration
Processing build output (wheels/sdists)
Reporting build progress and errors

Build frontends implement PEP 517’s standardized interface for interacting with build backends, ensuring consistent behavior across different tools.

Example Usage

Using the build frontend to create distributions:

What is a lockfile?

Tim Hopper — Fri, 24 Apr 2026 16:46:22 -0400

A lockfile is a text file enumerating the specific version of every dependency used by a project; it serves as a contract that guarantees reproducible environments across different systems and time periods.

A lockfile might record:

Exact versions of all direct and transitive dependencies
Cryptographic hashes to verify package integrity
Platform-specific requirements and constraints
Metadata about how dependencies were resolved

This creates a “single source of truth” for project dependencies that can be reliably reproduced.

What is a PEP?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Python Enhancement Proposals (PEPs) are the foundational documents that guide Python’s evolution. They propose new language features, collect community input on issues, and document Python design decisions. They record the language’s history and future direction through carefully deliberated proposals.

Not all PEPs are accepted. Rejected PEPs often contain valuable discussion and insights about Python’s design philosophy.

Core Purpose and Process

PEPs serve multiple functions in Python’s ecosystem:

What is a Python application?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

A Python application is a self-contained program designed to be used directly by end users, in contrast to a Python package, which is designed to be imported and reused by other Python code.

Application vs Package Comparison

Applications and packages serve different purposes:

Applications:

Have a main entry point (e.g., main.py or command-line interface)
Focus on end-user functionality
Often include configuration files and user settings
May bundle dependencies for deployment
Typically not imported by other Python code

Packages:

What is a Python Interpreter?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

A Python interpreter is the executable program that reads .py files and runs them. When someone says “I have Python 3.12 installed,” they mean a python3.12 binary exists somewhere on their system that can execute Python code. Every Python project needs an interpreter, and most of the complexity in Python tooling comes from managing which interpreter runs where.

Where interpreters come from

Python interpreters arrive on a system through several channels:

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.

What is a Python module?

Tim Hopper — Sat, 11 Apr 2026 17:42:24 -0400

A module is the basic unit of code Python can import. Any .py file is a module. So is any compiled extension, which ships as a .so file on Linux and macOS or a .pyd file on Windows. Anything that implements Python’s import protocol counts too, but the file cases cover what most developers ever see.

The PyPA glossary gives this concept three separate entries (Module, Pure Module, Extension Module), which is a hint that the vocabulary confuses people. This page walks through each flavor, and then untangles the bit that trips up almost every beginner: how modules relate to import packages and to the things you pip install.

What is a Python package?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

A Python package is a collection of related code modules (files) bundled with metadata describing how the package should be installed and used.

There are three common formats for Python packages, each serving different purposes:

Wheels: Pre-built binary distributions that can be quickly installed with pip or uv.
Source distributions (sdists): Raw source code that may need to be built during installation
Conda packages: A format specific to the Conda ecosystem that can include non-Python components

Package vs Application Comparison

Packages and applications serve different purposes: