Python Packaging (Deep Workflow)

Packaging connects source to installable artifacts. Prioritize reproducible builds, accurate dependencies, and safe automated releases.

When to Offer This Workflow

Trigger conditions:

• New library or CLI; choosing among Poetry, Hatch, setuptools, uv, etc.
• Broken installs on some Python versions or platforms
• Publishing to PyPI or a private index from CI

Initial offer:

Use six stages: (1) project layout, (2) metadata & entry points, (3) dependencies, (4) build backend & wheels, (5) versioning & tags, (6) publish & CI). Confirm supported Python versions and target index.

Stage 1: Project Layout

Goal: Prefer src/ layout to avoid accidental imports from the repo root; one clear import package name.

Exit condition: pip install . in a clean venv imports the package correctly.

Stage 2: Metadata & Entry Points

Goal: pyproject.toml with PEP 621 metadata; [project.scripts] or [project.gui-scripts] for CLIs.

Practices

• Link README; specify license SPDX identifier
• Use classifiers for PyPI discoverability

Stage 3: Dependencies

Goal: Separate runtime deps from optional extras (dev, docs, speedups); pin strategy differs for libraries vs applications.

Libraries

• Avoid overly tight upper bounds unless necessary (avoid dependency hell for consumers)

Applications

• Use lockfiles (pip-tools, uv, poetry lock) for reproducible deploys

Stage 4: Build Backend & Wheels

Goal: Choose build backend (hatchling, setuptools, flit); emit wheel + sdist where appropriate.

Native extensions

• Use cibuildwheel or similar for manylinux/macOS/windows matrices

Stage 5: Versioning & Tags

Goal: Single source of truth for version (static in pyproject or dynamic from VCS); git tags match releases.

Stage 6: Publish & CI

Goal: PyPI trusted publishing (OIDC) preferred over long-lived API tokens in secrets.

Practices

• Test with TestPyPI when learning the flow
• Restrict token scope and enable 2FA on PyPI accounts

Final Review Checklist

• src layout and imports verified in clean venv
• pyproject metadata complete; console scripts work
• Dependency policy documented (extras, bounds)
• Artifacts build for intended platforms
• Versioning aligned with tags; CI publishing secure

Tips for Effective Guidance

• Add py.typed for typed libraries (PEP 561).
• Lazy-import heavy optional deps inside functions to keep CLI startup fast.
• Namespace packages are easy to misconfigure—prefer one clear top-level package name.

Handling Deviations

• Monorepos: coordinate versions or use independent packages per folder with clear tooling.
• Docker-only apps: still package for testability; Dockerfile installs the wheel.