pypi-package-scaffoldlisted

# PyPI Package Scaffold > "A library is only as good as its documentation and its tests. Semantic versioning is a contract > with your users — break it and you break trust." ## Core Philosophy A Python package is a contract with its users in three parts: the API surface (what's public), the version (what changes are breaking), and the metadata (who maintains it, license, supported Python versions). Packaging is not an afterthought — a package that cannot be installed reliably, has no tests, ships without type stubs, or lacks documentation is not ready for PyPI. The scaffold establishes all of these before the first publish, using the `src/` layout and Trusted Publishing. **Non-Negotiable Constraints:** 1. NO PUBLISH WITHOUT TESTS — `pytest` must pass (the publish job `needs: test`) before any upload. 2. SEMVER IS LAW — breaking changes require a major version bump; no exceptions. 3. METADATA REQUIRED — name, version, description, license, authors, readme, requires-python, classifiers. 4. MULTI-VERSION SUPPORT — `requires-python = ">=3.10"` minimum; test matrix covers 3.10–3.13. 5. DETERMINISTIC BUILDS — pinned build dependencies; `PYTHONHASHSEED=0` in CI; ship both sdist and wheel. Full principle table, KB lookups, command sequences, anti-patterns, discipline rules, and error recovery live in `references/conventions.md`. ## Workflow ``` SCAFFOLD Create the src-layout structure: src/<package>/{__init__.py (+__all__), py.typed, _internal/} tes