nonobie — Real dev skills, explained like a friend would

What you'll learn

By the end of this chapter you will:

Structure a project with src layout and a complete pyproject.toml
Build wheels and sdists with python -m build
Publish to TestPyPI, then PyPI, with trusted publishing
Version semantically and automate releases with tags

The why

Unpackaged code is difficult to reuse, test across environments, and distribute to teams. Packaging turns local scripts into installable products with versioned release discipline.

If users cannot install your tool reliably, they cannot depend on it.

Core concepts: Shipping Python code

Project anatomy and src layoutOpen section

Let's learn

text

mytool/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── mytool/
│       ├── __init__.py
│       └── __main__.py
└── tests/

The src/ layout prevents accidental imports from the repo root during local development.

pyproject.toml essentialsOpen section

Let's learn

toml

[project]
name = "mytool"
version = "0.1.0"
description = "My first installable CLI"
requires-python = ">=3.11"
 
[project.scripts]
mytool = "mytool.__main__:main"
 
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

This enables both python -m mytool and installed CLI script execution.

Build wheels and source distributionsOpen section

Let's learn

bash

python -m pip install --upgrade build
python -m build

Artifacts in dist/:

.whl: built distribution for install
.tar.gz: source distribution

Inspect artifacts before publishing.

TestPyPI then PyPIOpen section

Let's learn

bash

python -m pip install --upgrade twine
twine check dist/*
twine upload --repository testpypi dist/*

After on TestPyPI, publish to PyPI using trusted CI publishing or secure token workflows.

Versioning and release disciplineOpen section

Let's learn

Recommended flow:

semantic versioning (MAJOR.MINOR.PATCH)
changelog updates per release
CI checks before publish
git tag per released version

Release engineering is part of product quality.

Release rule

Always publish to TestPyPI first for every significant packaging change. It catches metadata and install failures before they hit users.

Common mistakes

Mistake	Symptom	Fix
Missing `build-system` section	Build fails immediately	Add valid backend and requirements
Hardcoding version in multiple places	Drift and inconsistent artifacts	Single-source version strategy
Publishing without artifact checks	Broken install for users	Run `twine check` and TestPyPI rehearsal
Importing from project root in tests	False-local success	Use `src/` layout and install package in test env
No entrypoint script mapping	CLI not discoverable	Define `[project.scripts]`

Practice: Prove your Mastery

beginner Challenge

4 min

Create Package Skeleton

Draft a minimal src-layout tree for a CLI package.

Input— given data

data

tool name: dataclean

Expected Output— your code should produce this

expected

Valid package structure

Write your solutionCtrl+Enter to run

Ctrl+Enter

beginner Challenge

5 min

Add Console Script Entry

Configure a CLI command in pyproject for package entrypoint.

Input— given data

data

entry function dataclean.cli:main

Expected Output— your code should produce this

expected

dataclean command available after install

Write your solutionCtrl+Enter to run

Ctrl+Enter

intermediate Challenge

6 min

Build and Inspect Artifacts

Generate dist artifacts and validate metadata before upload.

Input— given data

data

Working package project

Expected Output— your code should produce this

expected

wheel and sdist created and checked

Write your solutionCtrl+Enter to run

Ctrl+Enter

intermediate Challenge

6 min

Release Checklist Draft

Create a 6-step release checklist for a package team.

Input— given data

data

Version bump to 0.2.0

Expected Output— your code should produce this

expected

Repeatable publish workflow

Write your solutionCtrl+Enter to run

Ctrl+Enter

intermediate Challenge

7 min

Backend Selection Decision

Choose packaging backend for a small CLI team and justify tradeoffs.

Input— given data

data

Need simple config, fast builds

Expected Output— your code should produce this

expected

Reasoned backend choice

Write your solutionCtrl+Enter to run

Ctrl+Enter

Interview Questions

Beginner:

"Why use pyproject.toml?"

It standardizes package metadata, build configuration, and tooling configuration in one modern file.
"What is the difference between wheel and sdist?"

Wheel is a built install artifact; sdist is source package that can be built during installation.

Senior:

"How do you prevent broken releases?"

Enforce CI quality gates, artifact validation, TestPyPI rehearsal, and reproducible release runbooks.
"When would you keep setuptools over newer backends?"

When existing plugin ecosystems or advanced packaging hooks depend on setuptools capabilities and migration cost is high.

Summary

Packaging makes code installable, versioned, and team-ready.
pyproject.toml is the modern center of package metadata.
TestPyPI rehearsal reduces release risk.
Release discipline is a core engineering skill, not optional process overhead.

Quick recall

text

Need installable tool? -> package with pyproject
Need release artifact? -> python -m build
Need safe publish? -> TestPyPI first
Need repeatability? -> checklist + CI gates

Self-Check Quiz

Q1 / 3

MCQ

What does python -m build produce?

Chapter 9 — Packaging & Publishing

The why

Core concepts: Shipping Python code

Common mistakes

Practice: Prove your Mastery

Create Package Skeleton

Add Console Script Entry

Build and Inspect Artifacts

Release Checklist Draft

Backend Selection Decision

Interview Questions

Summary

Quick recall

Self-Check Quiz