python-packaging

by codekungfu

Install this Skill

curl -fsSL -o python-packaging.zip https://skill.seembox.com/api/v1/skills/python-packaging/download && unzip python-packaging.zip

Download python-packaging.zip

SKILL.md About

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

---

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

_meta.json Metadata

{
  "ownerId": "kn79jhw85bss2z4dbpshhxg64x82zn3p",
  "publishedAt": 1774396861501,
  "slug": "python-packaging",
  "version": "1.0.0"
}