Python-Pypi-Package-Builder

# Python PyPI Package Builder Skill

A complete, battle-tested guide for building, testing, linting, versioning, typing, and

publishing a production-grade Python library to PyPI — from first commit to community-ready

release.

> **AI Agent Instruction:** Read this entire file before writing a single line of code or

> creating any file. Every decision — layout, backend, versioning strategy, patterns, CI —

> has a decision rule here. Follow the decision trees in order. This skill applies to any

> Python package type (utility, SDK, CLI, plugin, data library). Do not skip sections.

---

Quick Navigation

| Section in this file | What it covers |

|---|---|

| [1. Skill Trigger](#1-skill-trigger) | When to load this skill |

| [2. Package Type Decision](#2-package-type-decision) | Identify what you are building |

| [3. Folder Structure Decision](#3-folder-structure-decision) | src/ vs flat vs monorepo |

| [4. Build Backend Decision](#4-build-backend-decision) | setuptools / hatchling / flit / poetry |

| [5. PyPA Packaging Flow](#5-pypa-packaging-flow) | The canonical publish pipeline |

| [6. Project Structure Templates](#6-project-structure-templates) | Full layouts for every option |

| [7. Versioning Strategy](#7-versioning-strategy) | PEP 440, semver, dynamic vs static |

| Reference file | What it covers |

|---|---|

| `references/pyproject-toml.md` | All four backend templates, `setuptools_scm`, `py.typed`, tool configs |

| `references/library-patterns.md` | OOP/SOLID, type hints, core class design, factory, protocols, CLI |

| `references/testing-quality.md` | `conftest.py`, unit/backend/async tests, ruff/mypy/pre-commit |

| `references/ci-publishing.md` | `ci.yml`, `publish.yml`, Trusted Publishing, TestPyPI, CHANGELOG, release checklist |

| `references/community-docs.md` | README, docstrings, CONTRIBUTING, SECURITY, anti-patterns, master checklist |

| `references/architecture-patterns.md` | Backend system (plugin/strategy), config layer, transport layer, CLI, backend injection |

| `references/versioning-strategy.md` | PEP 440, SemVer, pre-release, setuptools_scm deep-dive, flit static, decision engine |

| `references/release-governance.md` | Branch strategy, branch protection, OIDC, tag author validation, prevent invalid tags |

| `references/tooling-ruff.md` | Ruff-only setup (replaces black/isort), mypy config, pre-commit, asyncio_mode=auto |

**Scaffold script:** run `python skills/python-pypi-package-builder/scripts/scaffold.py --name your-package-name`

to generate the entire directory layout, stub files, and `pyproject.toml` in one command.

---

1. Skill Trigger

Load this skill whenever the user wants to:

- Create, scaffold, or publish a Python package or library to PyPI

- Build a pip-installable SDK, utility, CLI tool, or framework extension

- Set up `pyproject.toml`, linting, mypy, pre-commit, or GitHub Actions for a Python project

- Understand versioning (`setuptools_scm`, PEP 440, semver, static versioning)

- Understand PyPA specs: `py.typed`, `MANIFEST.in`, `RECORD`, classifiers

- Publish to PyPI using Trusted Publishing (OIDC) or API tokens

- Refactor an existing package to follow modern Python packaging standards

- Add type hints, protocols, ABCs, or dataclasses to a Python library

- Apply OOP/SOLID design patterns to a Python package

- Choose between build backends (setuptools, hatchling, flit, poetry)

**Also trigger for phrases like:** "build a Python SDK", "publish my library", "set up PyPI CI",

"create a pip package", "how do I publish to PyPI", "pyproject.toml help", "PEP 561 typed",

"setuptools_scm version", "semver Python", "PEP 440", "git tag release", "Trusted Publishing".

---

2. Package Type Decision

Identify what the user is building **before** writing any code. Each type has distinct patterns.

Decision Table

| Type | Core Pattern | Entry Point | Key Deps | Example Packages |

|---|---|---|---|---|

| **Utility library** | Module of pure functions + helpers | Import API only | Minimal |