Virtual Environments, pyproject.toml, Packaging, Publishing, Linting, and CI for Professional Python Projects

Read before you buy: the PDF here is a free sample — the first 20 pages of the 475-page book (payments, sales and reviews on this demo site are sample data). Get the full e-book at thenexbooks on Gumroad.

Stop fighting your Python setup. Learn how the modern toolchain fits together, from your first virtual environment to a published, tested, 1.0 release.

Most Python projects start as a script. Then people start to depend on it: a colleague needs to install it, a new laptop has a different Python, a dependency update breaks something, and suddenly you are choosing between requirements.txt, setup.py, pyproject.toml, uv, Poetry, PDM, and Hatch without a clear picture of what each one actually does.

This book gives you that picture. It explains why each piece of the Python toolchain exists before showing how to use it, so you can make confident decisions today and keep up as the tools evolve. It is not a Python language course: it is for developers who can already write Python and now need to build projects other people can install, trust, and contribute to.

What's inside

• Interpreters and versions: the Windows py launcher, PATH pitfalls, system Pythons, version managers, and choosing requires-python
• Virtual environments in depth: what venv really creates, activation on every shell, isolation, and recreating instead of copying
• pip done properly: requirements files, constraints, offline installs, hash-checking mode, and why pip freeze is not a dependency strategy
• Reproducible environments: dependency resolution, lock files, and the new standard lock file format
• uv, Poetry, PDM, Hatch, and plain pip compared task by task, and how to choose
• pyproject.toml line by line: build-system, project, and tool tables, the src layout, dependencies, extras, and dependency groups
• Packaging explained: sdists and wheels, build frontends and backends, setuptools and hatchling, entry points and console scripts, plugins
• Versioning with Semantic Versioning and PEP 440, single-sourcing the version, changelogs, metadata, licensing, and typed packages
• Code quality: pytest fixtures and parametrize, Ruff for linting and formatting, mypy in strict mode, and pre-commit and nox automation
• Documentation, GitHub Actions CI across operating systems and Python versions, and publishing to TestPyPI and PyPI with Trusted Publishing
• Production and maintenance: supply-chain security, monorepos and workspaces, Docker images for Python apps, deprecations, contributors, and upgrades

One running example, start to finish. You follow kiteline, a fictional open-source geospatial library and command-line tool maintained by a volunteer group called Kiteline OSS. It calculates distances and bearings, converts units, and summarizes GPX tracks. It begins as a forty-line script and becomes a typed, tested, documented package with a console command, continuous integration on three operating systems, an automated release workflow, and a 1.0 release. Every number can be checked: London to Paris is 343.56 km in the tests, on the command line, and in the book.

Current and honest. The book targets Python 3.12 and newer. Commands that run locally — virtual environments, pip, building wheels, pytest, Ruff, mypy — were executed and their real output is shown; steps that need the network or fast-changing tools, such as uploading to PyPI or running uv and Poetry, are clearly marked with representative output. It contains no invented benchmarks or statistics. Every chapter includes hands-on steps, configuration files, Tips, Notes, Warnings, exercises, and Key Takeaways, and the appendices give you a cheat sheet, copy-ready templates, a release checklist, and a glossary.

Format: PDF, 475 pages (A4), linked table of contents and bookmarks. English. First Edition, 2026. Published by thenexbooks. This book is independent and is not affiliated with, sponsored by, or endorsed by the Python Software Foundation or any of the projects mentioned.

Table of Contents

Part I — From Scripts to Projects

• Ch 1 · From Script to Project: What Modern Python Tooling Solves
• Ch 2 · Python Interpreters and Versions: The py Launcher, PATH, and Version Managers
• Ch 3 · Virtual Environments in Depth: venv, Activation, and Isolation
• Ch 4 · pip and Requirements Files: Installing, Pinning, and Constraints
• Ch 5 · Reproducible Environments: Lock Files, Hashes, and Dependency Resolution

Part II — Project Structure and pyproject.toml

• Ch 6 · Project Managers Compared: uv, Poetry, PDM, Hatch, and Plain pip
• Ch 7 · pyproject.toml Anatomy: build-system, project, and tool Tables
• Ch 8 · Project Layout: src Layout, Packages, Modules, and Data Files
• Ch 9 · Dependencies Done Right: Version Specifiers, Extras, and Dependency Groups
• Ch 10 · Editable Installs and the Everyday Development Loop

Part III — Building and Packaging

• Ch 11 · How Packaging Works: Sdists, Wheels, Build Backends, and Frontends
• Ch 12 · Building with setuptools and hatchling
• Ch 13 · Entry Points and Console Scripts: Shipping the kiteline CLI
• Ch 14 · Versioning: Semantic Versioning, PEP 440, Single-Sourcing, and Changelogs
• Ch 15 · Metadata, Licensing, READMEs, and Typed Packages

Part IV — Code Quality

• Ch 16 · Testing with pytest: Layout, Fixtures, Parametrize, and Coverage
• Ch 17 · Linting and Formatting with Ruff
• Ch 18 · Static Typing with mypy
• Ch 19 · Automating Checks: pre-commit, nox, and Task Runners

Part V — Documentation, CI, and Publishing

• Ch 20 · Documentation: Docstrings, READMEs, and Documentation Sites
• Ch 21 · Continuous Integration with GitHub Actions for Python Projects
• Ch 22 · Publishing to TestPyPI and PyPI: Tokens and Trusted Publishing
• Ch 23 · Release Engineering: Tags, Changelogs, and Automated Releases

Part VI — Production and Maintenance

• Ch 24 · Security and the Software Supply Chain
• Ch 25 · Monorepos and Multi-Package Projects
• Ch 26 · Docker for Python Applications
• Ch 27 · Maintaining an Open-Source Project: Contributors, Deprecations, and Upgrades
• Ch 28 · Case Study: kiteline from Script to 1.0

Appendices
A · Tooling Cheat Sheet
B · Templates and Reference
C · Release and Production Checklist
D · Glossary

Book details