python-packaging

# 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.