📖 技能介绍

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.

7w4.net小葱技能。

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.