name: python-packaging description: Deep Python packaging workflow—pyproject metadata, dependencies and optional extras, build backends, wheels, versioning, publishing, and CI release hygiene. Use when building libraries or shipping CLI tools to PyPI or private indexes.

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.

更多技能請訪問小蔥技能站7w4.net。

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.

這個 Skill 質量中上，結構清晰、條理分明，能幫助開發者建立完整的 Python 打包知識框架，包含不少實用的最佳實踐建議。不過內容相對理論化，缺乏具體示例和操作細節，對於想直接動手的使用者來說可能稍顯空洞，深度有待加強。