python-packaging

Defines publishable Python package conventions covering pyproject.toml, src layout, versioning, and PyPI publishing.

Updated Jul 29, 2026
One-click install
npx skills add https://github.com/chris-prener/dev-kit --skill python-packaging-chris-prener
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: python-packaging
Source: https://github.com/chris-prener/dev-kit/tree/main/dev-kit/skills/python-packaging
Command: npx skills add https://github.com/chris-prener/dev-kit --skill python-packaging-chris-prener

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Structuring a Python project for publication involves many conventions — pyproject.toml metadata, src layout, semantic versioning, build backends, and PyPI release steps — that are easy to get wrong or inconsistent across projects. This Skill encodes those conventions so a package meets PyPI publishing standards on the first attempt. ## Core Features & Use Cases - Canonical package layout: Enforces a standard structure with src layout, pyproject.toml, tests, docs, LICENSE, and CHANGELOG. - Build and release workflow: Covers hatchling build configuration, semantic versioning with hatch, uv build, twine checks, and publishing to PyPI or TestPyPI. - Public API and quality gates: Defines init.py export rules, py.typed type-hint shipping, and a pre-release check sequence (ruff, mypy, pytest, build, twine). - Use Case: You have a working Python script collection and want to publish it as a package on PyPI. This Skill restructures it into src layout, writes compliant pyproject.toml metadata, sets up versioning, and walks through building and publishing the wheel. ## Quick Start Ask Claude to create a new publishable Python package named 'mypackage' with src layout and pyproject.toml configured for PyPI release.

Frequently Asked Questions about python-packaging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a publishable Python package with pyproject.toml?▼

Use a src layout with pyproject.toml defining project metadata, dependencies, and the hatchling build backend. Build with uv build, verify artifacts with twine check, and publish to PyPI with uv publish.

What is the difference between dependencies and dependency-groups in pyproject.toml?▼

The dependencies field lists runtime packages with minimum-version bounds only. The dependency-groups.dev field holds dev-only tools like pytest, ruff, mypy, and mkdocs, keeping them out of the published package requirements.

Should I use src layout or flat layout for a Python package?▼

This convention uses src layout, placing the importable package under src/<package_name>/. The wheel target is configured via tool.hatch.build.targets.wheel pointing at the src directory.

Why does my PyPI publish fail for an existing version?▼

PyPI rejects republishing an existing version number, and doing so breaks reproducibility for consumers. Bump the version with hatch version, tag the release in git, and publish the new number instead.

When should I not use this packaging workflow?▼

Do not use it for non-published Python projects, which belong to project scaffolding instead. It also excludes detailed testing patterns, CI workflow configuration, and mkdocs site theming, which are handled by separate conventions.