AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

python-pypi-package-builder

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 hints (PEP 484/526/544/561), Trusted Publishing (OIDC), and the full PyPA packaging flow. Use for: creating Python packages, pip-installable SDKs, CLI tools, framework plugins, pyproject.toml setup, py.typed, setuptools_scm, semver, mypy, pre-commit, GitHub Actions CI/CD, or PyPI publishing.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read github--python-pypi-package-builder at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 10

references/versioning-strategy.md

Versioning Strategy — PEP 440, SemVer, and Decision Engine

Table of Contents

  1. PEP 440 — The Standard
  2. Semantic Versioning (SemVer)
  3. Pre-release Identifiers
  4. Versioning Decision Engine
  5. Dynamic Versioning — setuptools_scm (Recommended)
  6. Hatchling with hatch-vcs Plugin
  7. Static Versioning — flit
  8. Static Versioning — hatchling manual
  9. DO NOT Hardcode Version (except flit)
  10. Dependency Version Specifiers
  11. PyPA Release Commands

1. PEP 440 — The Standard

All Python package versions must comply with PEP 440. Non-compliant versions (e.g., 1.0-beta, 2023.1.1.dev) will be rejected by PyPI.

Canonical form:  N[.N]+[{a|b|rc}N][.postN][.devN]

1.0.0            Stable release
1.0.0a1          Alpha pre-release
1.0.0b2          Beta pre-release
1.0.0rc1         Release candidate
1.0.0.post1      Post-release (packaging fix; same codebase)
1.0.0.dev1       Development snapshot — DO NOT upload to PyPI
2.0.0            Major release (breaking changes)

Epoch prefix (rare)

1!1.0.0          Epoch 1; used when you need to skip ahead of an old scheme

Use epochs only as a last resort to fix a broken version sequence.


2. Semantic Versioning (SemVer)

SemVer maps cleanly onto PEP 440. Always use MAJOR.MINOR.PATCH:

MAJOR  Increment when you make incompatible API changes (rename, remove, break)
MINOR  Increment when you add functionality backward-compatibly (new features)
PATCH  Increment when you make backward-compatible bug fixes

Examples:
  1.0.0 → 1.0.1   Bug fix, no API change
  1.0.0 → 1.1.0   New method added; existing API intact
  1.0.0 → 2.0.0   Public method renamed or removed

What counts as a breaking change?

| Change | Breaking? | |---|---| | Rename a public function | YES — MAJOR | | Remove a parameter | YES — MAJOR | | Add a required parameter | YES — MAJOR | | Add an optional parameter with a default | NO — MINOR | | Add a new function/class | NO — MINOR | | Fix a bug | NO — PATCH | | Update a dependency lower bound | NO (usually) — PATCH | | Update a dependency upper bound (breaking) | YES — MAJOR |


3. Pre-release Identifiers

Use pre-release versions to get user feedback before a stable release. Pre-releases are not installed by default by pip (pip install pkg skips them). Users must opt-in: pip install "pkg==2.0.0a1" or pip install --pre pkg.

1.0.0a1    Alpha-1: very early; expect bugs; API may change
1.0.0b1    Beta-1:  feature-complete; API stabilising; seek broader feedback
1.0.0rc1   Release candidate: code-frozen; final testing before stable
1.0.0      Stable: ready for production

Increment rule

Start:       1.0.0a1
More alphas: 1.0.0a2, 1.0.0a3
Move to beta: 1.0.0b1  (reset counter)
Move to RC:  1.0.0rc1
Stable:      1.0.0

4. Versioning Decision Engine

Use this decision tree to pick the right versioning strategy before writing any code.

Is the project using git and tagging releases with version tags?
├── YES → setuptools + setuptools_scm  (DEFAULT — best for most projects)
│         Git tag v1.0.0 becomes the installed version automatically.
│         Zero manual version bumping.
│
└── NO — Is the project a simple, single-module library with infrequent releases?
          ├── YES → flit
          │         Set __version__ = "1.0.0" in __init__.py.
          │         Update manually before each release.
          │
          └── NO — Does the team want an integrated build + dep management tool?
                    ├── YES → poetry
                    │         Manage version in [tool.poetry] version field.
                    │
                    └── NO → hatchling (modern, fast, pure-Python)
                              Use hatch-vcs plugin for dynamic versioning
                              or set version manually in [project].

Does the package have C/Cython/Fortran extensions?
└── YES (always) → setuptools (only backend with native extension support)

Summary Table

| Backend | Version source | Best for | |---|---|---| | setuptools + setuptools_scm | Git tags — fully automatic | DEFAULT for new projects | | hatchling + hatch-vcs | Git tags — automatic via plugin | hatchling users | | flit | __version__ in __init__.py | Very simple, minimal config | | poetry | [tool.poetry] version field | Integrated dep + build management | | hatchling manual | [project] version field | One-off static versioning |


5. Dynamic Versioning — setuptools_scm (Recommended)

setuptools_scm reads the current git tag and computes the version at build time. No separate __version__ update step — just tag and push.

pyproject.toml configuration

[build-system]
requires      = ["setuptools>=70", "setuptools_scm>=8"]
build-backend = "setuptools.backends.legacy:build"

[project]
name    = "your-package"
dynamic = ["version"]

[tool.setuptools_scm]
version_scheme = "post-release"
local_scheme   = "no-local-version"   # Prevents +g<hash> from breaking PyPI

__init__.py — correct version access

# your_package/__init__.py
from importlib.metadata import version, PackageNotFoundError

try:
    __version__ = version("your-package")
except PackageNotFoundError:
    # Package is not installed (running from a source checkout without pip install -e .)
    __version__ = "0.0.0.dev0"

__all__ = ["__version__"]

How the version is computed

git tag v1.0.0            →  installed_version = "1.0.0"
3 commits after v1.0.0    →  installed_version = "1.0.0.post3+g<hash>"  (dev only)
git tag v1.1.0            →  installed_version = "1.1.0"

With local_scheme = "no-local-version", the +g<hash> suffix is stripped for PyPI uploads while still being visible locally.

Critical CI requirement

- uses: actions/checkout@v4
  with:
    fetch-depth: 0    # REQUIRED — without this, git has no tag history
                      # setuptools_scm falls back to 0.0.0+d<date> silently

Every CI job that installs or builds the package must have fetch-depth: 0.

Debugging version issues

# Check what version setuptools_scm would produce right now:
python -m setuptools_scm

# If you see 0.0.0+d... it means:
# 1. No tags reachable from HEAD, OR
# 2. fetch-depth: 0 was not set in CI

6. Hatchling with hatch-vcs Plugin

An alternative to setuptools_scm for teams already using hatchling.

[build-system]
requires      = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"

[project]
name    = "your-package"
dynamic = ["version"]

[tool.hatch.version]
source = "vcs"

[tool.hatch.build.hooks.vcs]
version-file = "src/your_package/_version.py"

Access the version the same way as setuptools_scm:

from importlib.metadata import version, PackageNotFoundError
try:
    __version__ = version("your-package")
except PackageNotFoundError:
    __version__ = "0.0.0.dev0"

7. Static Versioning — flit

Use flit only for simple, single-module packages where manual version bumping is acceptable.

pyproject.toml

[build-system]
requires      = ["flit_core>=3.9"]
build-backend = "flit_core.buildapi"

[project]
name    = "your-package"
dynamic = ["version", "description"]

__init__.py

"""your-package — a focused, single-purpose utility."""
__version__ = "1.2.0"   # flit reads this; update manually before each release

flit exception: this is the ONLY case where hardcoding __version__ is correct. flit discovers the version by importing __init__.py and reading __version__.

Release flow for flit

# 1. Bump __version__ in __init__.py
# 2. Update CHANGELOG.md
# 3. Commit
git add src/your_package/__init__.py CHANGELOG.md
git commit -m "chore: release v1.2.0"
# 4. Tag (flit can also publish directly)
git tag v1.2.0
git push origin v1.2.0
# 5. Build and publish
flit publish
# OR
python -m build && twine upload dist/*

8. Static Versioning — hatchling manual

[build-system]
requires      = ["hatchling"]
build-backend = "hatchling.build"

[project]
name    = "your-package"
version = "1.0.0"   # Manual; update before each release

Update version in pyproject.toml before every release. No __version__ required (access via importlib.metadata.version() as usual).


9. DO NOT Hardcode Version (except flit)

Hardcoding __version__ in __init__.py when not using flit creates a dual source of truth that diverges over time.

# BAD — when using setuptools_scm, hatchling, or poetry:
__version__ = "1.0.0"    # gets stale; diverges from the installed package version

# GOOD — works for all backends except flit:
from importlib.metadata import version, PackageNotFoundError
try:
    __version__ = version("your-package")
except PackageNotFoundError:
    __version__ = "0.0.0.dev0"

10. Dependency Version Specifiers

Pick the right specifier style to avoid poisoning your users' environments.

# [project] dependencies — library best practices:

"httpx>=0.24"            # Minimum only — PREFERRED; lets users upgrade freely
"httpx>=0.24,<2.0"       # Upper bound only when a known breaking change exists in next major
"requests>=2.28,<3.0"    # Acceptable for well-known major-version breaks

# Application / CLI (pinning is fine):
"httpx==0.27.2"          # Lock exact version for reproducible deploys

# NEVER in a library:
# "httpx~=0.24.0"        # Too tight; blocks minor upgrades
# "httpx==0.27.*"        # Not valid PEP 440
# "httpx"                # No constraint; fragile against future breakage

11. PyPA Release Commands

The canonical sequence from code to user install.

# Step 1: Tag the release (triggers CI publish.yml automatically if configured)
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3

# Step 2 (manual fallback only): Build locally
python -m build
# Produces:
#   dist/your_package-1.2.3.tar.gz   (sdist)
#   dist/your_package-1.2.3-py3-none-any.whl  (wheel)

# Step 3: Validate
twine check dist/*

# Step 4: Test on TestPyPI first (first release or major change)
twine upload --repository testpypi dist/*
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ your-package==1.2.3

# Step 5: Publish to production PyPI
twine upload dist/*
# OR via GitHub Actions (recommended):
# push the tag → publish.yml runs → pypa/gh-action-pypi-publish handles upload via OIDC

# Step 6: Verify
pip install your-package==1.2.3
python -c "import your_package; print(your_package.__version__)"