Package and Distribute Python Code

Python Packaging is a comprehensive guide to creating, structuring, and distributing Python packages using modern tooling, pyproject.toml, and PyPI publishing. It covers core concepts - the recommended src/ layout versus the simpler flat layout, a multi-package monorepo layout with each package under its own src/ tree, the modern packaging standards (PEP 517/518 build-system requirements, PEP 621 metadata in pyproject.toml, PEP 660 editable installs), build backends (setuptools, hatchling, flit, poetry), and distribution channels (PyPI, TestPyPI, private repositories like JFrog or AWS CodeArtifact). It walks through 20 numbered patterns with working code: minimal and full-featured pyproject.toml files covering build-system, project metadata, classifiers, optional dependency groups, project URLs, console-script entry points, and tool configuration for black, ruff, mypy, pytest, and coverage; dynamic and git-based versioning via setuptools-scm; CLI patterns using both Click and argparse; local building and checking:

pip install build twine
python -m build
twine check dist/*

publishing to TestPyPI then PyPI with twine upload, including a ~/.pypirc token-auth template; an automated GitHub Actions publish workflow triggered on release; including and loading package data files via importlib.resources; namespace packages split across multiple repositories; C extensions built with Cython or setup.py; semantic versioning and dependency version-constraint syntax (>=, ~=, ==); editable installs and isolated-environment testing; a README template with PyPI, Python-version, and CI badges; multi-architecture wheel building via cibuildwheel across Ubuntu, Windows, and macOS; and installing from or publishing to a private package index. It closes with .gitignore and MANIFEST.in templates and a 13-item publishing checklist covering tests, documentation, versioning, and TestPyPI validation.

Use it when creating Python libraries for distribution, building command-line tools with entry points, publishing packages to PyPI or private repositories, setting up Python project structure, creating installable packages with dependencies, building wheels and source distributions, versioning and releasing Python packages, creating namespace packages, or implementing package metadata and classifiers. Do not use it when the task is unrelated to Python packaging or needs a different domain or tool outside this scope.

Input is Python source code intended for distribution, plus its dependencies and metadata such as name, version, license, and entry points. Output is a pyproject.toml-driven package with buildable wheel and source distributions, published to TestPyPI, PyPI, or a private index, complete with a git tag, CHANGELOG entry, and a README carrying installation and usage instructions, plus a py.typed marker file when the package ships inline type hints.

Build backends covered are setuptools, hatchling, flit, and poetry; publishing uses build and twine, targeting PyPI, TestPyPI, or a private index such as JFrog or AWS CodeArtifact; CLI entry points use Click or argparse; CI examples run on GitHub Actions with cibuildwheel for multi-OS wheel builds, and linting, typing, and testing tools referenced include black, ruff, mypy, pytest, and coverage.

Python developers and maintainers packaging a library or CLI tool for distribution, setting up a modern pyproject.toml-based project, automating PyPI releases, or configuring Sphinx-based documentation builds.