shield_lock
JinDaGe
← Back to skills
extension
Category: OtherNo API key required

Python Packaging

Deep Python packaging workflow—pyproject metadata, dependencies and optional extras, build backends, wheels, versioning, publishing, and CI release hygiene....

personAuthor: codekungfuhubclawhub
open_in_newRepositorydownloadDownload package

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.