1"""Dev releases: the branch decides, the wheel comes from the branch.
3``workflow.release`` on a main-family branch runs the release
4train; on any other branch it is the dev act, this module: each
5member built straight from the branch at a dev version, no reserved
6branch, no PR, no tags. Publishing goes only to the configured
7custom index, a python index: a member whose distributions are all
8python's publishes through its own publish phase, with that index as
9its python registry target, and a member that releases anything else
10builds without a publish. Without an index the run is local, every
11member built into its ``dist/`` and the publish skipped with the
12teaching. PyPI is never the fallback.
13"""
15from __future__ import annotations
17import os
18import re
19from collections.abc import Generator
20from contextlib import contextmanager
21from dataclasses import dataclass
22from datetime import UTC, datetime
23from pathlib import Path
25import livery.footman as footman
26from livery import git
27from livery.footman import fail
28from livery.workshop import _lifecycle, _release_notes
29from livery.workshop._packages import Package
30from livery.workshop._publish import index_target
31from livery.workshop._update import latest_released
32from livery.workshop._versions import derive_version
34#: The environment variable naming the custom index dev wheels go to.
35INDEX_VAR = "PYTHON_PUBLISH_INDEX"
37# The dev grammar's display form: 1.2.3-dev.branch.name.N+sha.date
38_SEMVER_DEV = re.compile(
39 r"^(?P<base>\d+\.\d+\.\d+)"
40 r"-dev\.(?P<branch>.+?)\.(?P<distance>\d+)"
41 r"(?:\+(?P<local>.+))?$"
42)
45@dataclass(frozen=True)
46class DevPlan:
47 """One package's derived dev release: the package and its version."""
49 package: Package
50 version: str
53def sanitise_branch(branch: str) -> str:
54 """The branch name as version-segment identifiers.
56 ``/`` becomes ``.``; every character outside ``[0-9A-Za-z-.]``
57 is dropped. ASCII only: PEP 440's local segment accepts nothing
58 wider, and ``str.isalnum`` alone would wave Unicode through into
59 a version the build backend refuses untaught.
60 """
61 return "".join(
62 c
63 for c in branch.replace("/", ".")
64 if (c.isalnum() and c.isascii()) or c in "-."
65 )
68def semver_to_pep440(semver: str) -> str:
69 """The dev grammar's PEP 440 form; anything else passes through.
71 ``1.2.3-dev.feat.x.4+gabc1234.20260901`` becomes
72 ``1.2.3.dev4+feat.x.gabc1234.20260901``: the branch moves into
73 the local segment, because PEP 440's public half accepts only
74 ``devN``. A build backend refuses the display form outright, so
75 every stamp goes through this.
76 """
77 match = _SEMVER_DEV.fullmatch(semver)
78 if match is None:
79 return semver
80 base = match.group("base")
81 branch = match.group("branch")
82 distance = match.group("distance")
83 local = match.group("local")
84 tail = f"{branch}.{local}" if local else branch
85 return f"{base}.dev{distance}+{tail}"
88def public_version(version: str) -> str:
89 """The dev *version*'s public PEP 440 form, without its local segment.
91 ``1.2.3-dev.feat.x.4+gabc1234.20260901`` becomes ``1.2.3.dev4``. A
92 floor is a ``>=`` specifier, which cannot carry a local segment,
93 and a floor without one ignores a candidate's local label, so
94 ``>=1.2.3.dev4`` admits ``1.2.3.dev4+feat.x.gabc1234.20260901``.
95 """
96 return semver_to_pep440(version).partition("+")[0]
99def describe_distance(root: Path, package: Package) -> tuple[int, str]:
100 """Commits since *package*'s last release tag, and the short sha.
102 ``(0, sha)`` on the tag itself; with no tag at all, the whole
103 history's count. Position only: the age marker in a dev version,
104 not the content check (that is the unchanged refusal).
105 """
106 try:
107 described = git.run(
108 root, "describe", "--tags", "--long", "--match", f"{package.path}/v*"
109 ).strip()
110 except git.GitError:
111 # A package before its first release has no tag to describe;
112 # git refuses rather than answering empty, and the whole
113 # history's count below is the honest age.
114 described = ""
115 if described:
116 parts = described.rsplit("-", 2)
117 if len(parts) == 3:117 ↛ 119line 117 didn't jump to line 119 because the condition on line 117 was always true
118 return int(parts[1]), parts[2].lstrip("g")
119 count = git.run(root, "rev-list", "--count", "HEAD").strip()
120 sha = git.run(root, "rev-parse", "--short", "HEAD").strip()
121 return (int(count) if count.isdigit() else 0), (sha or "0000000")
124def unchanged_since_release(root: Path, package: Package) -> str:
125 """The released version nothing unreleased has touched, or empty.
127 Content, not position, judged against the release tag: HEAD can
128 be far past a package's tag with no commit touching it, and
129 the derivation then answers the released version back. Empty for a
130 package with unreleased changes, or one with no release yet.
131 """
132 released = latest_released(git.tags(root)).get(package.path, "")
133 derived = derive_version(root, package, released=released)
134 return released if released and derived == released else ""
137def dev_version(root: Path, package: Package, *, stamp: str = "") -> str:
138 """Derive *package*'s dev version, refusing an unchanged package.
140 The refusal is content, not position, and judged against the
141 release *tag*, never the stamped file version: HEAD can be far
142 past a package's tag with no commit touching it, and the
143 derivation then answers the released version back. Building that content
144 under ``<released>.devN`` mints a number that sorts below the
145 release it repeats, so no floor naming the release can ever
146 resolve it. A stamped-ahead ``pyproject.toml`` (a prepared bump
147 whose tag is not cut yet) is not a refusal: the tag is the
148 record of what was released.
150 The date *stamp* rides in the local segment so a dev pin's age
151 reads offline from a lock file; ``.dirty`` marks a tree whose
152 wheel no commit describes. The sha rides as ``git describe``
153 spells it, ``g`` first: a local segment of digits alone is a
154 number to a version parser, and a build backend drops its
155 leading zero, so a short sha such as ``0442877`` would read back
156 as another commit's.
157 """
158 released = unchanged_since_release(root, package)
159 derived = derive_version(root, package)
160 if released:
161 fail(
162 f"nothing unreleased touches {package.name}: a dev build here"
163 f" would carry the released code under {released}.dev<N>, which"
164 f" sorts below {released} and can satisfy no floor that names"
165 f" it. Pin the released {released} instead, or drop"
166 f" {package.member} from the set."
167 )
168 distance, sha = describe_distance(root, package)
169 when = stamp or datetime.now(UTC).strftime("%Y%m%d")
170 version = (
171 f"{derived}-dev.{sanitise_branch(git.current_branch(root))}.{distance}"
172 f"+g{sha}.{when}"
173 )
174 if not git.is_clean(root):
175 version += ".dirty"
176 return version
179def build_dev(root: Path, plan: DevPlan) -> Path:
180 """Build the dev wheel; the tree is byte-identical afterwards.
182 The version is stamped and the release notes' unreleased entry, when
183 an extension writes notes, is spliced into ``README.md`` under
184 ``## What's New`` for the build only; every touched file is restored
185 from an in-memory snapshot, never from git, because a dirty tree is
186 legal here and a checkout would discard its edits. The index page is the
187 only place the excerpt exists. Timestamps are restored with the
188 bytes: uv judges an editable install fresh by its
189 ``pyproject.toml``'s modification time, and a touched file would
190 make the next sync re-install the package while other processes read
191 its metadata.
192 """
193 package = plan.package
194 touched = [path for path in _lifecycle.version_files(package) if path.is_file()]
195 readme = package.directory / "README.md"
196 if readme.is_file():
197 touched.append(readme)
198 snapshots = {path: path.read_bytes() for path in touched}
199 stamps = {path: path.stat() for path in touched}
200 try:
201 _lifecycle.stamp(package, root, semver_to_pep440(plan.version))
202 notes = _release_notes.release_notes(root)
203 excerpt = notes.entry(root, package) if notes is not None else ""
204 if excerpt and readme.is_file():
205 original = readme.read_text("utf-8")
206 readme.write_text(
207 f"## What's New\n\n{excerpt}\n\n---\n\n{original}",
208 encoding="utf-8",
209 )
210 return _lifecycle.build_release(package, root)
211 finally:
212 for path, content in snapshots.items():
213 path.write_bytes(content)
214 stat = stamps[path]
215 os.utime(path, ns=(stat.st_atime_ns, stat.st_mtime_ns))
218@contextmanager
219def set_floors(root: Path, plans: tuple[DevPlan, ...]) -> Generator[list[str]]:
220 """Raise each floor between the set's members to the co-member's dev version.
222 The release train raises the floors within its set before it builds,
223 and a dev build needs the same: a dev version sorts below the release
224 it leads to, so a floor that names that release, or ``0.0.0`` for a
225 member never released, admits no dev wheel of it. Each floor names
226 the co-member's public dev version instead, raised by the stamp
227 phase the train runs. A set of one moves no floor, as a release of
228 one moves none.
230 The raise lasts for the block alone: every file the phase may touch,
231 each member's version files and its contract, is restored from an
232 in-memory snapshot when the block ends, a failure included, with its
233 timestamps, as the build restores what it stamps. Yields the files
234 the phase reported, relative to *root*.
235 """
236 from livery.workshop._contract import CONTRACT
237 from livery.workshop._release_driver import MemberPlan, bump_set_floors
239 homes = [
240 home
241 for plan in plans
242 for home in (
243 *_lifecycle.version_files(plan.package),
244 plan.package.directory / CONTRACT,
245 )
246 if home.is_file()
247 ]
248 snapshots = {path: path.read_bytes() for path in homes}
249 stamps = {path: path.stat() for path in homes}
250 try:
251 yield bump_set_floors(
252 root,
253 tuple(
254 MemberPlan(package=plan.package, version=public_version(plan.version))
255 for plan in plans
256 ),
257 )
258 finally:
259 for path, content in snapshots.items():
260 if not path.is_file() or path.read_bytes() != content:
261 path.write_bytes(content)
262 stat = stamps[path]
263 if path.stat().st_mtime_ns != stat.st_mtime_ns:
264 os.utime(path, ns=(stat.st_atime_ns, stat.st_mtime_ns))
267def released_to_the_index(package: Package, kind: str) -> tuple[bool, str]:
268 """Tell whether an index of *kind* takes what *package* releases, and name it.
270 The index takes a member whose set releases at least one
271 distribution and only distributions of the index's ecosystem. The
272 text names the ecosystems of what the member releases, or says it
273 releases none, for the line that says why a member built without a
274 publish.
275 """
276 released = sorted({found for found, _name in _lifecycle.distributions(package)})
277 taken = released == [kind]
278 named = f"{' and '.join(released)} distributions" if released else "no distribution"
279 return taken, named
282def dev_release(
283 root: Path,
284 members: tuple[Package, ...],
285 *,
286 local: bool = False,
287) -> None:
288 """The dev act for a set: derive, confirm, build, publish.
290 Every member's version derives before anything builds, so a
291 refusal costs nothing. With ``local`` (or with no custom index
292 configured, which degrades to the same run and says so) nothing
293 leaves the machine and nothing is asked. A member whose
294 distributions are python's publishes through its publish phase,
295 with the index as the python registry target and
296 ``UV_PUBLISH_TOKEN`` as its credential, as the release train hands
297 a member its target; a member that releases anything else builds,
298 is not asked about, and a line says why nothing published it. A
299 publish always confirms per member. Where nobody can answer,
300 ``livery.footman.confirm`` takes its default no and the refusal
301 teaches the explicit ``--yes``: a decline and an unanswered
302 question are told apart by [livery.footman.attended][], which
303 knows about ``--no-input`` and ``--dry-run`` as well as the
304 terminal, so silence never publishes under any of them. While the
305 members build, each floor one declares on another member of the
306 set names that member's dev version, as the release train raises
307 the floors within its set; a member built alone moves no floor.
308 """
309 branch = git.current_branch(root)
310 index = os.environ.get(INDEX_VAR, "")
311 plans = tuple(
312 DevPlan(package=package, version=dev_version(root, package))
313 for package in members
314 )
315 publishing = not local and bool(index)
316 target = index_target(index, os.environ.get("UV_PUBLISH_TOKEN", ""))
317 # What the index takes is read before anything builds, as every
318 # version is derived first.
319 releases = (
320 {
321 plan.package.path: released_to_the_index(plan.package, target.kind)
322 for plan in plans
323 }
324 if publishing
325 else {}
326 )
327 # The report names its act first: a dev build must never read as
328 # a release.
329 print(f" act: dev, from branch '{branch}'; no tags, no release PR")
330 if not local and not index:
331 print(
332 f" no custom index is configured ({INDEX_VAR} is unset), so"
333 " this dev release ran as --local: wheels build into each"
334 " member's dist/ and the publish is skipped. Set"
335 f" {INDEX_VAR} (and UV_PUBLISH_TOKEN) to publish dev wheels;"
336 " PyPI is never the fallback."
337 )
338 with set_floors(root, plans) as raised:
339 if raised:
340 print(f" floors raised within the set for the build: {', '.join(raised)}")
341 for plan in plans:
342 taken, named = releases.get(plan.package.path, (False, ""))
343 if taken and not footman.confirm(
344 f"Publish a dev release of {plan.package.name}"
345 f" {plan.version} from '{branch}'?"
346 ):
347 if not footman.attended():
348 raise SystemExit(
349 "a dev release nobody was asked about needs the explicit"
350 f" --yes global (`{footman.prog()} --yes workflow.release"
351 " ...`); silence never publishes."
352 )
353 print(f" skipped {plan.package.name}")
354 continue
355 dist = build_dev(root, plan)
356 wheel = next(iter(dist.glob("*.whl")), None)
357 built = wheel.name if wheel else "dist/"
358 print(f" built {plan.package.name} {plan.version} -> {built}")
359 if taken:
360 # The member's publish phase owns the upload, as in the
361 # release train's wave; a False is a re-run walking past
362 # what an earlier one published, which the step says.
363 if _lifecycle.publish(363 ↛ 341line 363 didn't jump to line 341 because the condition on line 363 was always true
364 plan.package,
365 root,
366 version=semver_to_pep440(plan.version),
367 target=target,
368 ):
369 print(f" published {plan.package.name} {plan.version} to {index}")
370 elif publishing:
371 print(
372 f" not published {plan.package.name}: the custom index takes"
373 f" {target.kind} distributions alone, and it releases {named}"
374 )