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.