Packaging and Distribution: Ship Your Python

TIP

Learning Objectives: After this lesson, you'll understand modern Python packaging with pyproject.toml, manage dependencies effectively, create and publish packages to PyPI, and structure professional Python projects.

Modern Python Packaging

Python packaging has evolved significantly. Let's understand the modern approach.

The Packaging Landscape

pyproject.toml

Project Structure

Package Initialization

Dependency Management

Understanding Dependencies

Lock Files

Virtual Environments

Building and Publishing

Building Your Package

Publishing to PyPI

CLI Applications

Configuration Management

Best Practices

Practice Exercise

Complete Package Setup

Key Takeaways

Essential Commands

COPY
# Virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

# Check package
pip install --index-url https://test.pypi.org/simple/ mypackage

Next Steps

In the next and final lesson, we'll bring everything together in a Capstone Project: Building a Production-Ready CLI Tool—applying all concepts from the course in a comprehensive project.

Ready for the final project? Let's build something real!

Further Reading

The Modern Python Tooling Stack (2024+)

The packaging ecosystem has consolidated dramatically. If you learned Python before 2023, much of what you know is now legacy. Use these:

• uv — Astral's all-in-one project + dependency + Python-version manager (Rust-backed, ~10× faster than pip). Replaces pip, pip-tools, pyenv, virtualenv, poetry, pipx in one tool. The 2024 default.
• hatch — modern PyPA-blessed build backend + project manager. Strong alternative to uv if you prefer PyPA tooling.
• ruff — formatter + linter that replaces black, flake8, isort, and most of pylint.

Standards & Specs

• Python Packaging User Guide (PyPA) — the canonical reference.
• PEP 621 — pyproject.toml metadata — modern package metadata.
• PEP 660 — Editable installs via pyproject.toml — pip install -e . properly.
• PEP 668 — Externally Managed Environments — why Linux distros block pip install system-wide now.

Tutorials

• uv — Working on projects — the modern equivalent of "how do I start a Python project?"
• Real Python — How to Publish a Python Package to PyPI — still excellent walkthrough.
• Hynek Schlawack — Python Application Management — historically influential, still relevant on the dependency-pinning question.

When You Need More

• scikit-build-core — the modern way to build C/C++/Rust extensions.
• maturin — build PyO3-based Rust extensions; what polars, pydantic-core, and ruff use.
• cibuildwheel — build wheels for every platform/Python version on CI.

Books

• Book: Publishing Python Packages — Dane Hillard (Manning, 2022). Whole book on pyproject.toml + PyPI workflows.