iru-python-bump-version
Set a Python project's version (FastAPI service, Django project, or plain library/package) to an exact value in every place it keeps one, following this catalog's PEP 440 `X.Y.Z.dev0` development-vers
SKILL.md.claude/skills/iru-python-bump-version/SKILL.md
GitHubPython Bump Version
Set a Python project's version to an exact value across every file that must agree with it — pyproject.toml, any
__version__ literal, Django settings, a matching FastAPI(version=…), uv.lock — and, optionally, docs/antora.yml
and README/Antora version mentions. This skill never computes a version itself: it applies exactly the string it's
given, validated as PEP 440. The "which version comes next" logic belongs to the caller (typically iru-release) and
is defined in Step 5, so that caller has one place to read it from — the same contract iru-java-bump-version,
iru-typescript-bump-version, iru-android-bump-version, iru-swift-bump-version and iru-php-bump-version define
for their ecosystems.
Step 0 — Resolve inputs
- The positional argument is
<new-version>(e.g.1.4.0,1.5.0.dev0). Missing → ask for it before doing anything else; never guess or compute one here. args(key: valuelines), if present:sync-files: yes|no— also updatedocs/antora.ymland README/Antora mentions (Step 7). Omitted → ask once withAskUserQuestionafter Step 3 shows such mentions exist; don't ask when none do.next-version: <upcoming-version>— the upcoming development version (e.g.1.5.0.dev0) that "Current development version"/"Latest snapshot" markers should show after a release, while "Latest release" markers show<new-version>. Only meaningful withsync-files: yes; validated like<new-version>.dry-run: yes|no— defaultno.yesruns everything through showing the diff, then stops: nothing is written and no mutating command (uv lock) runs; say so plainly in the report.
Reject before touching anything a value that is obviously not a version (empty, or containing whitespace).
Step 1 — Write the helper and validate the version string
Python does have a version grammar — PEP 440 — and every packaging tool (pip, uv, build backends, PyPI) normalizes
to its canonical form. The helper below carries the PEP 440 pattern and renders the canonical form without needing
packaging installed (it runs on any python3 ≥ 3.8 — no tomllib, which only exists from 3.11, so it parses
pyproject.toml tables with anchored regexes instead). Write it once per run:
mkdir -p "$TMPDIR/iru-python-bump-version"
cat > "$TMPDIR/iru-python-bump-version/py_version.py" <<'PY'
import difflib, pathlib, re, subprocess, sys
args = sys.argv[1:]
dry, force, antora = "--dry-run" in args, "--force" in args, "--antora" in args
validate = "--validate" in args
args = [a for a in args if not a.startswith("--")]
new = args[0] if args else None # None => --list
root = pathlib.Path(".")
# PEP 440 (the public-version pattern from the spec, verbose form) + canonical rendering.
PEP440 = re.compile(r"""^\s*v?(?:(?P<epoch>[0-9]+)!)?(?P<release>[0-9]+(?:\.[0-9]+)*)
(?P<pre>[-_.]?(?P<pre_l>alpha|a|beta|b|preview|pre|c|rc)[-_.]?(?P<pre_n>[0-9]+)?)?
(?P<post>(?:-(?P<post_n1>[0-9]+))|(?:[-_.]?(?P<post_l>post|rev|r)[-_.]?(?P<post_n2>[0-9]+)?))?
(?P<dev>[-_.]?(?P<dev_l>dev)[-_.]?(?P<dev_n>[0-9]+)?)?
(?:\+(?P<local>[a-z0-9]+(?:[-_.][a-z0-9]+)*))?\s*$""", re.X | re.I)
def canonical(v):
m = PEP440.match(v)
if not m:
return None
s = (m["epoch"] + "!" if m["epoch"] and int(m["epoch"]) else "") + ".".join(str(int(x)) for x in m["release"].split("."))
if m["pre"]:
lab = {"alpha": "a", "beta": "b", "c": "rc", "pre": "rc", "preview": "rc"}.get(m["pre_l"].lower(), m["pre_l"].lower())
s += lab + str(int(m["pre_n"] or 0))
if m["post"]:
s += ".post" + str(int(m["post_n1"] or m["post_n2"] or 0))
if m["dev"]:
s += ".dev" + str(int(m["dev_n"] or 0))
if m["local"]:
s += "+" + ".".join(p if not p.isdigit() else str(int(p)) for p in re.split(r"[-_.]", m["local"].lower()))
return s
if validate:
c = canonical(new or "")
if c is None:
sys.exit(f"invalid: {new!r} is not a PEP 440 version")
print(f"canonical: {c}")
if c != new:
print(f"WARNING: {new} is valid PEP 440 but not canonical — packaging tools will normalize it to {c}")
if not re.fullmatch(r"\d+\.\d+\.\d+(\.dev\d+)?", c):
print("WARNING: not in this catalog's X.Y.Z / X.Y.Z.devN convention")
sys.exit(0)
is_release = new is not None and canonical(new) is not None and re.fullmatch(r"[0-9.]+", canonical(new)) is not None
def read(p):
return p.read_text(encoding="utf-8")
def ignored(p):
try:
return subprocess.run(["git", "check-ignore", "-q", str(p)], capture_output=True).returncode == 0
except FileNotFoundError:
return False
def tables(text):
"""Map TOML table name -> (start, end) offsets of its body (regex-based; no tomllib needed on Python < 3.11)."""
heads = [(m.group(1).strip(), m.start(), m.end()) for m in re.finditer(r"(?m)^[ \t]*\[\[?([^\[\]\n]+)\]\]?[ \t]*(?:#.*)?$", text)]
out = {}
for i, (name, _, end) in enumerate(heads):
out.setdefault(name, (end, heads[i + 1][1] if i + 1 < len(heads) else len(text)))
return out
def key_in(text, span, key):
rx = re.compile(r"(?m)^([ \t]*" + re.escape(key) + r"[ \t]*=[ \t]*)([\"'])([^\"'\n]*)(\2)")
return [m for m in rx.finditer(text, *span)] if span else []
VERSION_ASSIGN = re.compile(r"""(?m)^(__version__[ \t]*(?::[ \t]*str[ \t]*)?=[ \t]*)(["'])([^"'\n]*)(\2)""")
SETTINGS_ASSIGN = re.compile(r"""(?m)^((?:APP_)?VERSION[ \t]*(?::[ \t]*str[ \t]*)?=[ \t]*)(["'])([^"'\n]*)(\2)""")
SETTINGS_ENV = re.compile(r"""(?m)^((?:APP_)?VERSION[ \t]*(?::[ \t]*str[ \t]*)?=[ \t]*(?:os\.environ\.get|os\.getenv|env\.str|env)\([ \t]*["'](?:APP_)?VERSION["'][ \t]*,[ \t]*(?:default[ \t]*=[ \t]*)?)(["'])([^"'\n]*)(\2)""")
FASTAPI_CTOR = re.compile(r"""(FastAPI\((?:[^()]|\([^()]*\))*?\bversion[ \t]*=[ \t]*)(["'])([^"'\n]*)(\2)""", re.S)
SKIP = {".venv", "venv", ".git", "node_modules", "build", "dist", "docs", "tests", "test", "migrations", ".tox", ".nox", "site-packages"}
def walk(globs):
seen = []
for g in globs:
for p in sorted(root.glob(g)):
if p.is_file() and not (set(p.parts) & SKIP) and p not in seen and not ignored(p):
seen.append(p)
return seen
locs = [] # (path, regex, kind, role) role: primary|mirror|conditional|antora
notes = []
pp = root / "pyproject.toml"
text = read(pp) if pp.exists() else ""
tb = tables(text)
name = None
if "project" in tb:
n = key_in(text, tb["project"], "name")
name = n[0].group(3) if n else None
dynamic = False
if "project" in tb:
d = re.search(r"(?ms)^[ \t]*dynamic[ \t]*=[ \t]*\[(.*?)\]", text[tb["project"][0]:tb["project"][1]])
dynamic = bool(d and re.search(r"[\"']version[\"']", d.group(1)))
backend = ""
if "build-system" in tb:
b = key_in(text, tb["build-system"], "build-backend")
backend = b[0].group(3) if b else ""
requires = text[tb["build-system"][0]:tb["build-system"][1]] if "build-system" in tb else ""
def module_file(dotted):
parts = dotted.split(".")
for base in (root / "src", root):
for cand in (base.joinpath(*parts).with_suffix(".py"), base.joinpath(*parts, "__init__.py")):
if cand.exists():
return cand
return None
def stop_vcs(why):
print(f"version: dynamic — {why}; the version is derived from git tags, nothing to change")
sys.exit(0)
if dynamic:
hv = tb.get("tool.hatch.version")
sd = tb.get("tool.setuptools.dynamic")
pv = tb.get("tool.pdm.version")
if hv and key_in(text, hv, "source") and key_in(text, hv, "source")[0].group(3) == "vcs":
stop_vcs("[tool.hatch.version] source = \"vcs\" (hatch-vcs)")
if pv and key_in(text, pv, "source") and key_in(text, pv, "source")[0].group(3) == "scm":
stop_vcs("[tool.pdm.version] source = \"scm\"")
if re.search(r"setuptools[-_]scm|hatch-vcs|versioningit|dynamic-versioning|uv-dynamic-versioning", requires + text, re.I) \
or "tool.setuptools_scm" in tb:
stop_vcs("a VCS versioning plugin (setuptools-scm / hatch-vcs / versioningit / *-dynamic-versioning) is configured")
target = None
if hv and key_in(text, hv, "path"):
target = root / key_in(text, hv, "path")[0].group(3)
elif pv and key_in(text, pv, "path"):
target = root / key_in(text, pv, "path")[0].group(3)
elif sd:
body = text[sd[0]:sd[1]]
a = re.search(r"""version[ \t]*=[ \t]*\{[^}]*attr[ \t]*=[ \t]*["']([^"']+)["']""", body)
f = re.search(r"""version[ \t]*=[ \t]*\{[^}]*file[ \t]*=[ \t]*\[?[ \t]*["']([^"']+)["']""", body)
if a:
mod, _, attr = a.group(1).rpartition(".")
target = module_file(mod)
if attr != "__version__":
notes.append(f"attr {a.group(1)}: only __version__ literals are rewritten — check {attr} by hand")
elif f:
vf = root / f.group(1)
locs.append((vf, re.compile(r"\A()()([^\s]+)()"), "VERSION file (setuptools dynamic file)", "primary"))
elif "flit" in backend and name:
target = module_file(re.sub(r"[-.]+", "_", name).lower())
if target is not None:
if not target.exists():
sys.exit(f"dynamic version points at {target.as_posix()}, which does not exist")
locs.append((target, VERSION_ASSIGN, "__version__ (dynamic source)", "primary"))
if not locs:
sys.exit("dynamic version with an unrecognized source — explain to the user and stop; nothing was changed")
else:
if "project" in tb and key_in(text, tb["project"], "version"):
locs.append((pp, None, "[project].version", "primary"))
if "tool.poetry" in tb and key_in(text, tb["tool.poetry"], "version"):
locs.append((pp, None, "[tool.poetry].version", "primary"))
cfg = root / "setup.cfg"
if cfg.exists():
m = re.search(r"(?ms)^\[metadata\][^\[]*?^(version[ \t]*=[ \t]*)()([^\s]+)()", read(cfg))
if m and not m.group(3).startswith(("attr:", "file:")):
locs.append((cfg, re.compile(r"(?ms)(^\[metadata\][^\[]*?^version[ \t]*=[ \t]*)()([^\s]+)()"), "setup.cfg [metadata] version", "primary"))
spy = root / "setup.py"
if spy.exists() and re.search(r"""\bversion[ \t]*=[ \t]*["'][^"']+["']""", read(spy)):
locs.append((spy, re.compile(r"""(\bversion[ \t]*=[ \t]*)(["'])([^"'\n]+)(\2)"""), "setup.py version=", "primary"))
dyn_targets = {l[0] for l in locs if l[2].startswith("__version__")}
for p in walk(["src/*/__init__.py", "src/*/_version.py", "src/*/__about__.py", "src/*/version.py",
"*/__init__.py", "*/_version.py", "*/__about__.py", "*/version.py"]):
t = read(p)
if p not in dyn_targets and VERSION_ASSIGN.search(t):
locs.append((p, VERSION_ASSIGN, "__version__ literal", "primary"))
elif p not in dyn_targets and re.search(r"(?m)^__version__\s*=", t):
notes.append(f"{p.as_posix()}: __version__ is computed (e.g. importlib.metadata.version()) — follows pyproject, untouched")
for p in walk(["*/settings.py", "*/settings/*.py", "*/*/settings.py", "*/*/settings/*.py"]):
t = read(p)
if SETTINGS_ENV.search(t):
locs.append((p, SETTINGS_ENV, "settings VERSION env default", "primary"))
elif SETTINGS_ASSIGN.search(t):
locs.append((p, SETTINGS_ASSIGN, "settings VERSION literal", "primary"))
for p in walk(["app/*.py", "src/*/*.py", "src/*/*/*.py", "*/main.py"]):
if FASTAPI_CTOR.search(read(p)):
locs.append((p, FASTAPI_CTOR, "FastAPI(version=) literal — written only when it equals the package version", "conditional"))
ay = root / "docs" / "antora.yml"
if antora and ay.exists():
locs.append((ay, re.compile(r"(?m)^(version:[ \t]*)(['\"]?)([^\s'\"#]+)(\2)"), "docs/antora.yml version (release versions only)", "antora"))
if not locs:
sys.exit("No version location found (no [project].version, [tool.poetry].version, __version__ literal, setup.cfg/setup.py version)")
found, new_texts = [], {}
for path, rx, label, role in locs:
t = new_texts.get(path, read(path))
if rx is None: # pyproject table keys
span = tables(t)["project" if label.startswith("[project]") else "tool.poetry"]
hits = key_in(t, span, "version")[:1]
else:
hits = list(rx.finditer(t))[:1]
for m in hits:
found.append([path.as_posix(), t.count("\n", 0, m.start(3)) + 1, m.group(3), label, role, path, m])
for f in found:
print(f"{f[0]}:{f[1]}: {f[2]} [{f[3]}]")
for n in notes:
print(f"note: {n}")
primary = [f for f in found if f[4] == "primary"]
if not primary:
sys.exit("No primary version location found — only mirrors/conditional ones")
values = {f[2] for f in primary}
current = primary[0][2]
print(f"current: {current}")
if len(values) > 1:
print(f"WARNING: version locations disagree: {sorted(values)}", file=sys.stderr)
if new is not None and not force:
sys.exit("Refusing to write: confirm with the user, then re-run with --force to align every location")
if new is None:
sys.exit(0)
for f in sorted(found, key=lambda f: -f[6].start()): # rewrite back to front per file
path, m, role = f[5], f[6], f[4]
if role == "conditional" and f[2] != current:
print(f"note: {f[0]}:{f[1]} FastAPI version {f[2]} differs from the package version — left alone (separate API version)")
continue
if role == "antora" and (not is_release or f[2] in ("~", "true", "false", "")):
print(f"note: {f[0]} version left at {f[2]} (Antora's component version names releases only)")
continue
t = new_texts.get(path, read(path))
new_texts[path] = t[:m.start(3)] + new + t[m.end(3):]
for path, t in new_texts.items():
old = read(path)
if t == old:
continue
if dry:
sys.stdout.writelines(difflib.unified_diff(old.splitlines(True), t.splitlines(True), str(path), str(path)))
else:
path.write_text(t, encoding="utf-8")
print(f"updated {path.as_posix()}")
lock = root / "uv.lock"
if lock.exists() and name and re.search(r'(?m)^name = "' + re.escape(re.sub(r"[-_.]+", "-", name).lower()) + r'"\nversion = ', read(lock)):
print("next: uv lock (refreshes this project's own version entry in uv.lock)")
PY
python3 "$TMPDIR/iru-python-bump-version/py_version.py" "<new-version>" --validate
invalid: … is not a PEP 440 version(exit 1) → stop and ask for a valid value; nothing can install or build a package with it.WARNING: … not canonical→ the value is legal but every tool rewrites it (1.4.0-dev→1.4.0.dev0,v1.4.0→1.4.0,1.0-alpha.2→1.0a2): propose the printedcanonical:form and use it unless the user insists, so the file, the wheel name, the git tag, and PyPI all spell it the same way.WARNING: not in this catalog's X.Y.Z / X.Y.Z.devN convention→ flag, don't hard-stop: a project may deliberately ship1.4.0rc1or1.4.0.post1. Anything with a.devN,aN,bNorrcNpart counts as a pre-release below (never written todocs/antora.yml).
Step 2 — Survey the version locations
python3 "$TMPDIR/iru-python-bump-version/py_version.py" --list --antora
Run it from the repository root (the directory holding pyproject.toml, setup.cfg, or setup.py). Output: one
<file>:<line>: <value> [<location>] line per location, any note: lines, then current: <value>. What it looks
for, in this order:
| Location | When it is used |
|---|---|
pyproject.toml [project].version |
PEP 621 static version — the scaffold contract's single source (iru-setup-python-*), also uv/hatch/setuptools/flit/pdm projects |
pyproject.toml [tool.poetry].version |
Poetry projects (Poetry 1, or Poetry 2 without a [project] version); written alongside [project].version when both exist |
setup.cfg [metadata] version / setup.py version="…" |
legacy setuptools projects with a literal (an attr:/file: value is left alone) |
__version__ = "…" (optionally : str) in src/<pkg>/ or <pkg>/ __init__.py, _version.py, __about__.py, version.py |
only literal strings in files not ignored by git (a generated _version.py from setuptools-scm/hatch-vcs is skipped). __version__ = version("pkg") (importlib.metadata) is reported as a note: and left alone — it already follows pyproject.toml, which is this catalog's recommended pattern |
Django VERSION/APP_VERSION in */settings.py or */settings/*.py |
a literal, or the default of os.environ.get("APP_VERSION", "…")/os.getenv(…)/env(…, default="…") |
FastAPI(…, version="…") in app/*.py, src/<pkg>/**.py, */main.py |
conditional: rewritten only when it equals the package version (it then tracks the package); a different value ("v2", "2024-01") is a deliberate API version and is left alone with a note:. It feeds the OpenAPI info.version |
docs/antora.yml version: (with --antora) |
mirror, release versions only (Step 7); never part of the agreement check |
Migrations, tests, docs, build/, dist/, virtualenvs and node_modules/ are never searched. Then:
- Dynamic version, VCS-derived —
version: dynamic — … derived from git tags, nothing to change(exit 0): the project hasdynamic = ["version"]with hatch-vcs ([tool.hatch.version] source = "vcs"), setuptools-scm ([tool.setuptools_scm]orsetuptools-scminbuild-system.requires),[tool.pdm.version] source = "scm", versioningit, or a*-dynamic-versioningplugin. Stop here: explain that the build backend computes the version from the latest git tag (a dev build between tags gets a.devN+g<hash>version automatically), that the release is creating the tagX.Y.Z, and that no file was touched; skip Steps 4, 6 and 7.iru-releasethen treats it like a Swift library or a plain Composer package (Step 5). - Dynamic version, file-based —
[tool.hatch.version] path = "…",[tool.pdm.version] path = "…",[tool.setuptools.dynamic] version = {attr = "pkg.__version__"}/{file = "VERSION"}, or flit (module__version__): the helper lists that file as the(dynamic source)location and rewrites it;pyproject.tomlhas no version to write. Anattrthat isn't__version__gets anote:— check it by hand. - Unrecognized dynamic source or no location at all (non-zero exit) → don't invent one silently. Show
pyproject.tomland ask whether to addversion = "<new-version>"under[project](removing"version"fromdynamic), then re-run--list. - Locations disagree (
WARNING: version locations disagree) — show the list and ask whether to align every location to<new-version>(Step 4 then passes--force) or which to leave alone (edit only the others by hand and say so in the report). A stale__version__literal is the usual cause — aligning it is normally right, and worth suggesting a switch toimportlib.metadata.version()so it can't drift again. - The current version for the report (and for
iru-release, which reads it this way) is thecurrent:line — the first primary location ([project].version, else[tool.poetry].version, else the dynamic source file, …). With uv,uv version --shortprints the same value for a static[project].version(it errors on dynamic versions).
Step 3 — Look for mirrored mentions
grep -n -i "latest release\|current development version\|latest snapshot\|pip install\|uv add\|poetry add" README.md 2>/dev/null
grep -rln -i "latest release\|pip install\|uv add" docs/modules/ROOT/pages 2>/dev/null; grep -n '^version:\|^prerelease:' docs/antora.yml 2>/dev/null
grep -rn '"VERSION"[[:space:]]*:' --include='*.py' . 2>/dev/null | grep -v '/\.venv/\|/migrations/' # drf-spectacular SPECTACULAR_SETTINGS["VERSION"]
Only when something turns up is sync-files worth asking about (Step 0).
Step 4 — Preview (dry-run: yes) or apply
python3 "$TMPDIR/iru-python-bump-version/py_version.py" "<new-version>" --dry-run [--antora] # unified diff only
python3 "$TMPDIR/iru-python-bump-version/py_version.py" "<new-version>" [--antora] # write
Pass --antora only when Step 7's sync was accepted (sync-files: yes); add --force only after the user confirmed
aligning disagreeing locations (Step 2). The script rewrites exactly the first match of each location --list
printed — dependency version = "^2.0" specifiers, requires-python, other tables, other *_VERSION names, and every
other file stay untouched — and prints note:/next: lines:
next: uv lock—uv.lockrecords this project's own version ([[package]] name = "<project>"followed byversion = "…", present for a static version; uv omits it for a dynamic one). Runuv lockfrom the same directory (not withdry-run: yes): it rewrites only that entry (Updated <project> v<old> -> v<new>) and keeps every other pin, so it works offline (uv lock --offline) when the cache is warm. Without it, CI'suv sync --lockedfails with a stale-lockfile error.poetry.lock/pdm.lock/requirements*.txtdon't record the project's own version — nothing to refresh there.note: … FastAPI version … differs— the API version was left alone deliberately (Step 2 table); mention it.note: docs/antora.yml version left at …— a pre-release value; expected (Step 7).
Why not uv version <new-version> / poetry version <new-version>: each only rewrites its own pyproject.toml field,
not __version__ literals, Django settings, or the FastAPI constructor, so the locations would drift.
A non-zero exit at any point → stop, show the error, and treat nothing as updated; never fall back to hand edits.
Step 5 — The Python-catalog pre-release convention (for iru-release and other callers)
The Python equivalent of iru-java-bump-version's -SNAPSHOT, iru-typescript-bump-version's -dev.N and
iru-php-bump-version's -dev — the contract iru-release calls this skill against (two calls per release, each
passing a computed <new-version>), and the one the sync.yml written by iru-setup-python-github-workflows and the
iru-setup-python-* scaffolds (version = "0.1.0.dev0") use:
- Current development version:
X.Y.Z.dev0(e.g.1.4.0.dev0) on the integration branch — PEP 440's developmental-release segment, already in canonical form. PEP 440 orders1.3.0 < 1.4.0.dev0 < 1.4.0a1 < 1.4.0rc1 < 1.4.0, so a dev build always sorts before the release it leads to, and pip/uv skip it unless asked for pre-releases (--pre,--prerelease=allow) — it can never be picked up by accident.Nstays0; only increment it when a project deliberately publishes several dev builds of the same target. - Cutting a release: strip the
.devNsegment —X.Y.Z.dev0→X.Y.Z. Call this skill with<new-version>: X.Y.Z; that is also the call that movesdocs/antora.ymltoX.Y.Z(withsync-files: yes). A project that ships release candidates may cutX.Y.ZrcNfirst — a pre-release, so Antora is not touched for it. - Opening the next development cycle: bump the minor (this catalog's default, matching
iru-release's recommended "minor bump" and thesync.ymlworkflow) and append.dev0—X.Y.Z→X.(Y+1).0.dev0; a patch (X.Y.(Z+1).dev0) or major bump is the caller's choice. Call this skill again (or letsync.ymldo it after the release is published) with that exact value — this skill never decides which component to bump. - Git tags are the bare release version (
X.Y.Z, novprefix by this catalog's convention), matching the canonical PEP 440 string inpyproject.toml. - VCS-derived dynamic versions: no in-tree marker at all — the release is the git tag; there is nothing to strip
and no next-dev value to write (the backend derives
X.Y.(Z+1).devN+g<hash>between tags by itself), exactly likeiru-swift-bump-version's library case.iru-releaseskips its "must currently be a pre-release" check and its next-version question for it. - Non-canonical legacy spellings (
1.4.0-dev,1.4.0.dev,1.4.0-SNAPSHOT— the last one is not PEP 440 at all) count as the development marker when reading the current version, but every value this skill writes is the canonical.dev0form after Step 1.
Step 6 — Sanity check
Skip with dry-run: yes. Otherwise:
python3 "$TMPDIR/iru-python-bump-version/py_version.py" --list [--antora] # every location now shows <new-version>
uv lock --check --offline # only when uv.lock exists: lockfile is fresh
uv version --short # uv + static [project].version: prints <new-version>
python3 -c 'import ast,sys; [ast.parse(open(f).read(), f) for f in sys.argv[1:]]' <each rewritten .py file>
--list must print <new-version> for every primary location and no disagreement warning; ast.parse proves each
rewritten Python file still parses (the rewrite only replaces a quoted literal, but report it rather than assume).
For a Poetry project, poetry check when Poetry is installed; otherwise say it wasn't run.
Step 7 — Optionally sync other files that mirror the version
Ask (or honor sync-files) whether to update the mentions Step 3 found, mapping each by what it names — the same
rule as iru-java-bump-version's Step 7:
docs/antora.ymlversion:→<new-version>only for a release (Antora's component version names released versions; skip.devN/aN/bN/rcN), if the site tracks the release version at all — the helper's--antoraflag does exactly this and leaves~(an unversioned component) alone. Aprerelease:key, if the site uses one, is left as is and mentioned in the report.- "Latest release" markers (and a
Latest releaserow in the README's status table) →<new-version>when it is a release; untouched when<new-version>is a pre-release. - "Current development version"/"Latest snapshot" markers →
next-versionwhen given; otherwise<new-version>only if it is a pre-release, and untouched (warn in Step 8 that the caller should passnext-version) when it's a release — never regress a development marker to a release value. - An install snippet for this project's own package (
pip install <name>==X.Y.Z,uv add "<name>>=X.Y",<name> = "^X.Y") → the release value, only for a release; a service (FastAPI/Django) usually has none — then only the markers apply. - A drf-spectacular
SPECTACULAR_SETTINGS = {..., "VERSION": "…"}(the OpenAPIinfo.versionof a Django API) → same rule as the helper'sFastAPI(version=…):<new-version>only when it currently equals the package version; a separate API version ("1.0.0"for/api/v1/) is left alone and mentioned. - Antora pages under
docs/modules/ROOT/pages/with the same markers/snippets → as for the README.
Targeted, scoped substitutions only — never a repository-wide replace of the old string. Offered, not automatic: a README badge pulling the version live (PyPI/GHCR shields) must not be rewritten.
Step 8 — Report
- Every location from
--listwith its old value (and thecurrent:value), the new version, and whether the input was normalized to its canonical PEP 440 form. - Every file changed (by the script, by
uv lock, and by Step 7), or for a VCS-derived dynamic version that nothing changed because the git tag is the version. - Any disagreement that was aligned with
--forceafter the user confirmed, any FastAPI API version left alone, any computed__version__noted, and whetherdocs/antora.ymlwas written (release) or left (pre-release). - Whether this was a
dry-run, and the Step 6 result (--listagreement,uv lock --check,ast.parseper file). - Warn explicitly: review the diff before committing (this skill commits nothing); a
.devNversion uploaded to PyPI is permanent (PyPI never lets a version be re-uploaded) — only release versions should be published; a container image or OpenAPI document built from this commit carries the new version.
Verification notes
Verified in $TMPDIR/iru-verify/python/docs-bump/ with uv 0.12.8 by running the exact helper above with the host's
python3 3.9.6 (no tomllib, no packaging) against a uv init --lib project and hand-written fixtures:
--validate: canonical output matchedpackaging.version.Version(viauv run --with packaging) for1.4.0-dev→1.4.0.dev0,1.0-alpha.2→1.0a2,1!2.0.post-3→1!2.0.post3,1.0.0-1→1.0.0.post1,2.0RC1.dev→2.0rc1.dev0,1.0+ubuntu-1→1.0+ubuntu.1,01.02.003→1.2.3;not.a.version→ exit 1.- uv library (
[project].version = "0.1.0.dev0",__version__literal,app/main.pyFastAPI(title=str("x"), version="0.1.0.dev0"),docs/antora.ymlversion: 0.0.9):--dry-runprinted the diff and wrote nothing (checksums unchanged);0.1.0 --antorarewrote all four;uv lockprintedUpdated demo-lib v0.1.0.dev0 -> v0.1.0and changed only that entry;0.2.0.dev0 --antorarewrote the three code locations and leftantora.ymlat0.1.0with the note;uv lock --offlinethenuv lock --check --offlinepassed;uv version --shortprinted the new value. - Poetry
[tool.poetry] version = "1.2.0-dev"→1.2.0, with arequests = { version = "^2.0" }dependency untouched. hatch-vcs and setuptools-scm ([tool.setuptools_scm]) → "derived from git tags", exit 0, nothing written.[tool.hatch.version] path→__about__.pyrewritten, aversion("acme")__init__.pyreported as computed.[tool.setuptools.dynamic] version = {attr = "acme.__version__"}with__version__: str = …→ rewritten.setup.cfg[metadata] versionandsetup.pysetup(version=…)→ rewritten. - Django
APP_VERSION = os.environ.get("APP_VERSION", "0.5.0.dev0")inconfig/settings/base.py→ listed and rewritten; aVERSION = …insidemigrations/ignored. pyproject1.0.0.dev0vs__version__ = "0.9.0"→ refused with the disagreement warning;--forcealigned both. AFastAPI(..., version="v2")→ left alone with the note. A git-ignored_version.py→ not listed. Apyproject.tomlwith no version → non-zero exit.
Not verified: a real Poetry 2 / PDM project end-to-end (poetry check), flit's module lookup (implemented, no
fixture), and real scaffolds from iru-setup-python-* (written in parallel) — run --list on the first real scaffold
and adjust nothing silently if a location is missing.
Sources
- irurueta docs: programming-languages/python/virtual-environments-and-packaging.adoc (PEP 621
[project]table, interchangeable backends, build/publish) - irurueta docs: backend/fastapi/openapi-and-interactive-docs.adoc (
FastAPI(version=…)is the API version, bumped each release) - irurueta docs: backend/fastapi/deployment.adoc (committed
uv.lock,importlib.metadata.version) - PEP 440 — Version Identification and Dependency Specification (normalization,
.devNordering)