End-to-end skill for building, testing, linting, versioning, and publishing a production-grade Python library to PyPI. Covers all four build backends (setuptools+setuptools_scm, hatchling, flit, poetry), PEP 440 versioning, semantic versioning, dynamic git-tag versioning, OOP/SOLID design, type hint

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 arrow , humanize , boltons , more itertools API client / SDK Class with methods, auth, retry logic Import API only httpx or requests boto3 , stripe python , openai CLI tool Command functions + argument parser [project.scripts] or [project.entry points] click or typer black , ruff , httpie , rich Framework plugin Plugin class, hook registration [project.entry points."framework.plugin"] Framework dep pytest , django , flask Data processing library Classes + functional pipeline Import API only Optional: numpy , pandas pydantic , marshmallow , cerberus Mixed / generic Combination of above Varies Varies Many real world packages Decision Rule: Ask the user if unclear. A package can combine types (e.g., SDK with a CLI entry point) — use the primary type for structural decisions and add secondary type patterns on top. For implementation patterns of each type, see references/library patterns.md . Package Naming Rules PyPI name: all lowercase, hyphens — my python library Python import name: underscores — my python library Check availability: https://pypi.org/search/ before starting Avoid shadowing popular packages (verify pip install <name fails first) 3. Folder Structure Decision Decision Tree Quick Rule Summary Situation Use New project, unknown future size src/ layout (safest default) Single purpose, 1–4 modules Flat layout Large library, many contributors src/ layout Multiple packages in one repo Namespace / monorepo Migrating old flat project Keep flat; migrate to src/ at next major version 4. Build Backend Decision Decision Tree Backend Comparison Backend Version source Config C extensions Best for setuptools + setuptools scm git tags (automatic) pyproject.toml + optional setup.py shim Yes Projects with git tag releases; any complexity hatchling manual or plugin pyproject.toml only No New pure Python projects; fast, modern flit version in init .py pyproject.toml only No Very simple, single module packages poetry pyproject.toml field pyproject.toml only No Teams wanting integrated dep management For all four complete pyproject.toml templates, see references/pyproject toml.md . 5. PyPA Packaging Flow This is the canonical end to end flow from source code to user install. Every step must be understood before publishing. Key PyPA Concepts Concept What it means sdist Source distribution — your source + metadata; used when no wheel is available wheel (.whl) Pre built binary — pip extracts directly into site packages; no build step PEP 517/518 Standard build system interface via pyproject.toml [build system] table PEP 621 Standard [project] table in pyproject.toml ; all modern backends support it PEP 639 license key as SPDX string (e.g., "MIT" , "Apache 2.0" ) — not {text = "MIT"} PEP 561 py.typed empty marker file — tells mypy/IDEs this package ships type information For complete CI workflow and publishing setup, see references/ci publishing.md . 6. Project Structure Templates A. src/ Layout (Recommended default for new projects) B. Flat Layout (Small / focused packages) C. Namespace / Monorepo Layout (Multiple related packages) Each sub package has its own pyproject.toml . They share the your org namespace via PEP 420 implicit namespace packages (no init .py in the namespace root). Internal Module Guidelines File Purpose When to include init .py Public API surface; re exports; version Always py.typed PEP 561 typed package marker (empty) Always core.py Primary class / main logic Always config.py Settings dataclass or Pydantic model When configurable exceptions.py Exception hierarchy ( YourBaseError → specifics) Always models.py Data models / DTOs / TypedDicts When data heavy utils.py Internal helpers (not part of public API) As needed types.py Shared TypeVar , TypeAlias , Protocol definitions When complex typing cli.py CLI entry points (click/typer) CLI type only backends/ Plugin/strategy pattern When swappable implementations compat.py Python version compatibility shims When 3.9–3.13 compat needed 7. Versioning Strategy PEP 440 — The Standard Semantic Versioning (recommended) Dynamic versioning with setuptools scm (recommended for git tag workflows) Required pyproject.toml config: Critical: always set fetch depth: 0 in every CI checkout step. Without full git history, setuptools scm cannot find tags and the build version silently falls back to 0.0.0+dev . Static versioning (flit, hatchling manual, poetry) Version specifier best practices for dependencies Version bump → release flow For complete pyproject.toml templates for all four backends, see references/pyproject toml.md . Where to Go Next After understanding decisions and structure: 1. Set up pyproject.toml → references/pyproject toml.md All four backend templates (setuptools+scm, hatchling, flit, poetry), full tool configs, py.typed setup, versioning config. 2. Write your library code → references/library patterns.md OOP/SOLID principles, type hints (PEP 484/526/544/561), core class design, factory functions, init .py , plugin/backend pattern, CLI entry point. 3. Add tests and code quality → references/testing quality.md conftest.py , unit/backend/async tests, parametrize, ruff/mypy/pre commit setup. 4. Set up CI/CD and publish → references/ci publishing.md ci.yml , publish.yml with Trusted Publishing (OIDC, no API tokens), CHANGELOG format, release checklist. 5. Polish for community/OSS → references/community docs.md README sections, docstring format, CONTRIBUTING, SECURITY, issue templates, anti patterns table, and master release checklist. 6. Design backends, config, transport, CLI → references/architecture patterns.md Backend system (plugin/strategy pattern), Settings dataclass, HTTP transport layer, CLI with click/typer, backend injection rules. 7. Choose and implement a versioning strategy → references/versioning strategy.md PEP 440 canonical forms, SemVer rules, pre release identifiers, setuptools scm deep dive, flit static versioning, decision engine (DEFAULT/BEGINNER/MINIMAL). 8. Govern releases and secure the publish pipeline → references/release governance.md Branch strategy, branch protection rules, OIDC Trusted Publishing setup, tag author validation in CI, tag format enforcement, full governed publish.yml . 9. Simplify tooling with Ruff → references/tooling ruff.md Ruff only setup replacing black/isort/flake8, mypy config, pre commit hooks, asyncio mode=auto (remove @pytest.mark.asyncio), migration guide.

python-pypi-package-builder