Skip to content

livery.workshop._dev_release

livery.workshop._dev_release

Dev releases: the branch decides, the wheel comes from the branch.

workflow.release on a main-family branch runs the release train; on any other branch it is the dev act, this module: each member built straight from the branch at a dev version, no reserved branch, no PR, no tags. Publishing goes only to the configured custom index, a python index: a member whose distributions are all python's publishes through its own publish phase, with that index as its python registry target, and a member that releases anything else builds without a publish. Without an index the run is local, every member built into its dist/ and the publish skipped with the teaching. PyPI is never the fallback.

Classes:

Name Description
DevPlan

One package's derived dev release: the package and its version.

Functions:

Name Description
sanitise_branch

The branch name as version-segment identifiers.

semver_to_pep440

The dev grammar's PEP 440 form; anything else passes through.

public_version

The dev version's public PEP 440 form, without its local segment.

describe_distance

Commits since package's last release tag, and the short sha.

unchanged_since_release

The released version nothing unreleased has touched, or empty.

dev_version

Derive package's dev version, refusing an unchanged package.

build_dev

Build the dev wheel; the tree is byte-identical afterwards.

set_floors

Raise each floor between the set's members to the co-member's dev version.

released_to_the_index

Tell whether an index of kind takes what package releases, and name it.

dev_release

The dev act for a set: derive, confirm, build, publish.

Attributes:

Name Type Description
INDEX_VAR

INDEX_VAR module-attribute

INDEX_VAR = 'PYTHON_PUBLISH_INDEX'

DevPlan dataclass

DevPlan(package: Package, version: str)

One package's derived dev release: the package and its version.

Attributes:

Name Type Description
package Package
version str

package instance-attribute

package: Package

version instance-attribute

version: str

sanitise_branch

sanitise_branch(branch: str) -> str

The branch name as version-segment identifiers.

/ becomes .; every character outside [0-9A-Za-z-.] is dropped. ASCII only: PEP 440's local segment accepts nothing wider, and str.isalnum alone would wave Unicode through into a version the build backend refuses untaught.

Source code in packages/workshop/src/livery/workshop/_dev_release.py
def sanitise_branch(branch: str) -> str:
    """The branch name as version-segment identifiers.

    ``/`` becomes ``.``; every character outside ``[0-9A-Za-z-.]``
    is dropped. ASCII only: PEP 440's local segment accepts nothing
    wider, and ``str.isalnum`` alone would wave Unicode through into
    a version the build backend refuses untaught.
    """
    return "".join(
        c
        for c in branch.replace("/", ".")
        if (c.isalnum() and c.isascii()) or c in "-."
    )

semver_to_pep440

semver_to_pep440(semver: str) -> str

The dev grammar's PEP 440 form; anything else passes through.

1.2.3-dev.feat.x.4+gabc1234.20260901 becomes 1.2.3.dev4+feat.x.gabc1234.20260901: the branch moves into the local segment, because PEP 440's public half accepts only devN. A build backend refuses the display form outright, so every stamp goes through this.

Source code in packages/workshop/src/livery/workshop/_dev_release.py
def semver_to_pep440(semver: str) -> str:
    """The dev grammar's PEP 440 form; anything else passes through.

    ``1.2.3-dev.feat.x.4+gabc1234.20260901`` becomes
    ``1.2.3.dev4+feat.x.gabc1234.20260901``: the branch moves into
    the local segment, because PEP 440's public half accepts only
    ``devN``. A build backend refuses the display form outright, so
    every stamp goes through this.
    """
    match = _SEMVER_DEV.fullmatch(semver)
    if match is None:
        return semver
    base = match.group("base")
    branch = match.group("branch")
    distance = match.group("distance")
    local = match.group("local")
    tail = f"{branch}.{local}" if local else branch
    return f"{base}.dev{distance}+{tail}"

public_version

public_version(version: str) -> str

The dev version's public PEP 440 form, without its local segment.

1.2.3-dev.feat.x.4+gabc1234.20260901 becomes 1.2.3.dev4. A floor is a >= specifier, which cannot carry a local segment, and a floor without one ignores a candidate's local label, so >=1.2.3.dev4 admits 1.2.3.dev4+feat.x.gabc1234.20260901.

Source code in packages/workshop/src/livery/workshop/_dev_release.py
def public_version(version: str) -> str:
    """The dev *version*'s public PEP 440 form, without its local segment.

    ``1.2.3-dev.feat.x.4+gabc1234.20260901`` becomes ``1.2.3.dev4``. A
    floor is a ``>=`` specifier, which cannot carry a local segment,
    and a floor without one ignores a candidate's local label, so
    ``>=1.2.3.dev4`` admits ``1.2.3.dev4+feat.x.gabc1234.20260901``.
    """
    return semver_to_pep440(version).partition("+")[0]

describe_distance

describe_distance(root: Path, package: Package) -> tuple[int, str]

Commits since package's last release tag, and the short sha.

(0, sha) on the tag itself; with no tag at all, the whole history's count. Position only: the age marker in a dev version, not the content check (that is the unchanged refusal).

Source code in packages/workshop/src/livery/workshop/_dev_release.py
def describe_distance(root: Path, package: Package) -> tuple[int, str]:
    """Commits since *package*'s last release tag, and the short sha.

    ``(0, sha)`` on the tag itself; with no tag at all, the whole
    history's count. Position only: the age marker in a dev version,
    not the content check (that is the unchanged refusal).
    """
    try:
        described = git.run(
            root, "describe", "--tags", "--long", "--match", f"{package.path}/v*"
        ).strip()
    except git.GitError:
        # A package before its first release has no tag to describe;
        # git refuses rather than answering empty, and the whole
        # history's count below is the honest age.
        described = ""
    if described:
        parts = described.rsplit("-", 2)
        if len(parts) == 3:
            return int(parts[1]), parts[2].lstrip("g")
    count = git.run(root, "rev-list", "--count", "HEAD").strip()
    sha = git.run(root, "rev-parse", "--short", "HEAD").strip()
    return (int(count) if count.isdigit() else 0), (sha or "0000000")

unchanged_since_release

unchanged_since_release(root: Path, package: Package) -> str

The released version nothing unreleased has touched, or empty.

Content, not position, judged against the release tag: HEAD can be far past a package's tag with no commit touching it, and the derivation then answers the released version back. Empty for a package with unreleased changes, or one with no release yet.

Source code in packages/workshop/src/livery/workshop/_dev_release.py
def unchanged_since_release(root: Path, package: Package) -> str:
    """The released version nothing unreleased has touched, or empty.

    Content, not position, judged against the release tag: HEAD can
    be far past a package's tag with no commit touching it, and
    the derivation then answers the released version back. Empty for a
    package with unreleased changes, or one with no release yet.
    """
    released = latest_released(git.tags(root)).get(package.path, "")
    derived = derive_version(root, package, released=released)
    return released if released and derived == released else ""

dev_version

dev_version(root: Path, package: Package, *, stamp: str = '') -> str

Derive package's dev version, refusing an unchanged package.

The refusal is content, not position, and judged against the release tag, never the stamped file version: HEAD can be far past a package's tag with no commit touching it, and the derivation then answers the released version back. Building that content under <released>.devN mints a number that sorts below the release it repeats, so no floor naming the release can ever resolve it. A stamped-ahead pyproject.toml (a prepared bump whose tag is not cut yet) is not a refusal: the tag is the record of what was released.

The date stamp rides in the local segment so a dev pin's age reads offline from a lock file; .dirty marks a tree whose wheel no commit describes. The sha rides as git describe spells it, g first: a local segment of digits alone is a number to a version parser, and a build backend drops its leading zero, so a short sha such as 0442877 would read back as another commit's.

Source code in packages/workshop/src/livery/workshop/_dev_release.py
def dev_version(root: Path, package: Package, *, stamp: str = "") -> str:
    """Derive *package*'s dev version, refusing an unchanged package.

    The refusal is content, not position, and judged against the
    release *tag*, never the stamped file version: HEAD can be far
    past a package's tag with no commit touching it, and the
    derivation then answers the released version back. Building that content
    under ``<released>.devN`` mints a number that sorts below the
    release it repeats, so no floor naming the release can ever
    resolve it. A stamped-ahead ``pyproject.toml`` (a prepared bump
    whose tag is not cut yet) is not a refusal: the tag is the
    record of what was released.

    The date *stamp* rides in the local segment so a dev pin's age
    reads offline from a lock file; ``.dirty`` marks a tree whose
    wheel no commit describes. The sha rides as ``git describe``
    spells it, ``g`` first: a local segment of digits alone is a
    number to a version parser, and a build backend drops its
    leading zero, so a short sha such as ``0442877`` would read back
    as another commit's.
    """
    released = unchanged_since_release(root, package)
    derived = derive_version(root, package)
    if released:
        fail(
            f"nothing unreleased touches {package.name}: a dev build here"
            f" would carry the released code under {released}.dev<N>, which"
            f" sorts below {released} and can satisfy no floor that names"
            f" it. Pin the released {released} instead, or drop"
            f" {package.member} from the set."
        )
    distance, sha = describe_distance(root, package)
    when = stamp or datetime.now(UTC).strftime("%Y%m%d")
    version = (
        f"{derived}-dev.{sanitise_branch(git.current_branch(root))}.{distance}"
        f"+g{sha}.{when}"
    )
    if not git.is_clean(root):
        version += ".dirty"
    return version

build_dev

build_dev(root: Path, plan: DevPlan) -> Path

Build the dev wheel; the tree is byte-identical afterwards.

The version is stamped and the release notes' unreleased entry, when an extension writes notes, is spliced into README.md under ## What's New for the build only; every touched file is restored from an in-memory snapshot, never from git, because a dirty tree is legal here and a checkout would discard its edits. The index page is the only place the excerpt exists. Timestamps are restored with the bytes: uv judges an editable install fresh by its pyproject.toml's modification time, and a touched file would make the next sync re-install the package while other processes read its metadata.

Source code in packages/workshop/src/livery/workshop/_dev_release.py
def build_dev(root: Path, plan: DevPlan) -> Path:
    """Build the dev wheel; the tree is byte-identical afterwards.

    The version is stamped and the release notes' unreleased entry, when
    an extension writes notes, is spliced into ``README.md`` under
    ``## What's New`` for the build only; every touched file is restored
    from an in-memory snapshot, never from git, because a dirty tree is
    legal here and a checkout would discard its edits. The index page is the
    only place the excerpt exists. Timestamps are restored with the
    bytes: uv judges an editable install fresh by its
    ``pyproject.toml``'s modification time, and a touched file would
    make the next sync re-install the package while other processes read
    its metadata.
    """
    package = plan.package
    touched = [path for path in _lifecycle.version_files(package) if path.is_file()]
    readme = package.directory / "README.md"
    if readme.is_file():
        touched.append(readme)
    snapshots = {path: path.read_bytes() for path in touched}
    stamps = {path: path.stat() for path in touched}
    try:
        _lifecycle.stamp(package, root, semver_to_pep440(plan.version))
        notes = _release_notes.release_notes(root)
        excerpt = notes.entry(root, package) if notes is not None else ""
        if excerpt and readme.is_file():
            original = readme.read_text("utf-8")
            readme.write_text(
                f"## What's New\n\n{excerpt}\n\n---\n\n{original}",
                encoding="utf-8",
            )
        return _lifecycle.build_release(package, root)
    finally:
        for path, content in snapshots.items():
            path.write_bytes(content)
            stat = stamps[path]
            os.utime(path, ns=(stat.st_atime_ns, stat.st_mtime_ns))

set_floors

set_floors(root: Path, plans: tuple[DevPlan, ...]) -> Generator[list[str]]

Raise each floor between the set's members to the co-member's dev version.

The release train raises the floors within its set before it builds, and a dev build needs the same: a dev version sorts below the release it leads to, so a floor that names that release, or 0.0.0 for a member never released, admits no dev wheel of it. Each floor names the co-member's public dev version instead, raised by the stamp phase the train runs. A set of one moves no floor, as a release of one moves none.

The raise lasts for the block alone: every file the phase may touch, each member's version files and its contract, is restored from an in-memory snapshot when the block ends, a failure included, with its timestamps, as the build restores what it stamps. Yields the files the phase reported, relative to root.

Source code in packages/workshop/src/livery/workshop/_dev_release.py
@contextmanager
def set_floors(root: Path, plans: tuple[DevPlan, ...]) -> Generator[list[str]]:
    """Raise each floor between the set's members to the co-member's dev version.

    The release train raises the floors within its set before it builds,
    and a dev build needs the same: a dev version sorts below the release
    it leads to, so a floor that names that release, or ``0.0.0`` for a
    member never released, admits no dev wheel of it. Each floor names
    the co-member's public dev version instead, raised by the stamp
    phase the train runs. A set of one moves no floor, as a release of
    one moves none.

    The raise lasts for the block alone: every file the phase may touch,
    each member's version files and its contract, is restored from an
    in-memory snapshot when the block ends, a failure included, with its
    timestamps, as the build restores what it stamps. Yields the files
    the phase reported, relative to *root*.
    """
    from livery.workshop._contract import CONTRACT
    from livery.workshop._release_driver import MemberPlan, bump_set_floors

    homes = [
        home
        for plan in plans
        for home in (
            *_lifecycle.version_files(plan.package),
            plan.package.directory / CONTRACT,
        )
        if home.is_file()
    ]
    snapshots = {path: path.read_bytes() for path in homes}
    stamps = {path: path.stat() for path in homes}
    try:
        yield bump_set_floors(
            root,
            tuple(
                MemberPlan(package=plan.package, version=public_version(plan.version))
                for plan in plans
            ),
        )
    finally:
        for path, content in snapshots.items():
            if not path.is_file() or path.read_bytes() != content:
                path.write_bytes(content)
            stat = stamps[path]
            if path.stat().st_mtime_ns != stat.st_mtime_ns:
                os.utime(path, ns=(stat.st_atime_ns, stat.st_mtime_ns))

released_to_the_index

released_to_the_index(package: Package, kind: str) -> tuple[bool, str]

Tell whether an index of kind takes what package releases, and name it.

The index takes a member whose set releases at least one distribution and only distributions of the index's ecosystem. The text names the ecosystems of what the member releases, or says it releases none, for the line that says why a member built without a publish.

Source code in packages/workshop/src/livery/workshop/_dev_release.py
def released_to_the_index(package: Package, kind: str) -> tuple[bool, str]:
    """Tell whether an index of *kind* takes what *package* releases, and name it.

    The index takes a member whose set releases at least one
    distribution and only distributions of the index's ecosystem. The
    text names the ecosystems of what the member releases, or says it
    releases none, for the line that says why a member built without a
    publish.
    """
    released = sorted({found for found, _name in _lifecycle.distributions(package)})
    taken = released == [kind]
    named = f"{' and '.join(released)} distributions" if released else "no distribution"
    return taken, named

dev_release

dev_release(root: Path, members: tuple[Package, ...], *, local: bool = False) -> None

The dev act for a set: derive, confirm, build, publish.

Every member's version derives before anything builds, so a refusal costs nothing. With local (or with no custom index configured, which degrades to the same run and says so) nothing leaves the machine and nothing is asked. A member whose distributions are python's publishes through its publish phase, with the index as the python registry target and UV_PUBLISH_TOKEN as its credential, as the release train hands a member its target; a member that releases anything else builds, is not asked about, and a line says why nothing published it. A publish always confirms per member. Where nobody can answer, livery.footman.confirm takes its default no and the refusal teaches the explicit --yes: a decline and an unanswered question are told apart by livery.footman.attended, which knows about --no-input and --dry-run as well as the terminal, so silence never publishes under any of them. While the members build, each floor one declares on another member of the set names that member's dev version, as the release train raises the floors within its set; a member built alone moves no floor.

Source code in packages/workshop/src/livery/workshop/_dev_release.py
def dev_release(
    root: Path,
    members: tuple[Package, ...],
    *,
    local: bool = False,
) -> None:
    """The dev act for a set: derive, confirm, build, publish.

    Every member's version derives before anything builds, so a
    refusal costs nothing. With ``local`` (or with no custom index
    configured, which degrades to the same run and says so) nothing
    leaves the machine and nothing is asked. A member whose
    distributions are python's publishes through its publish phase,
    with the index as the python registry target and
    ``UV_PUBLISH_TOKEN`` as its credential, as the release train hands
    a member its target; a member that releases anything else builds,
    is not asked about, and a line says why nothing published it. A
    publish always confirms per member. Where nobody can answer,
    ``livery.footman.confirm`` takes its default no and the refusal
    teaches the explicit ``--yes``: a decline and an unanswered
    question are told apart by [livery.footman.attended][], which
    knows about ``--no-input`` and ``--dry-run`` as well as the
    terminal, so silence never publishes under any of them. While the
    members build, each floor one declares on another member of the
    set names that member's dev version, as the release train raises
    the floors within its set; a member built alone moves no floor.
    """
    branch = git.current_branch(root)
    index = os.environ.get(INDEX_VAR, "")
    plans = tuple(
        DevPlan(package=package, version=dev_version(root, package))
        for package in members
    )
    publishing = not local and bool(index)
    target = index_target(index, os.environ.get("UV_PUBLISH_TOKEN", ""))
    # What the index takes is read before anything builds, as every
    # version is derived first.
    releases = (
        {
            plan.package.path: released_to_the_index(plan.package, target.kind)
            for plan in plans
        }
        if publishing
        else {}
    )
    # The report names its act first: a dev build must never read as
    # a release.
    print(f"  act: dev, from branch '{branch}'; no tags, no release PR")
    if not local and not index:
        print(
            f"  no custom index is configured ({INDEX_VAR} is unset), so"
            " this dev release ran as --local: wheels build into each"
            " member's dist/ and the publish is skipped. Set"
            f" {INDEX_VAR} (and UV_PUBLISH_TOKEN) to publish dev wheels;"
            " PyPI is never the fallback."
        )
    with set_floors(root, plans) as raised:
        if raised:
            print(f"  floors raised within the set for the build: {', '.join(raised)}")
        for plan in plans:
            taken, named = releases.get(plan.package.path, (False, ""))
            if taken and not footman.confirm(
                f"Publish a dev release of {plan.package.name}"
                f" {plan.version} from '{branch}'?"
            ):
                if not footman.attended():
                    raise SystemExit(
                        "a dev release nobody was asked about needs the explicit"
                        f" --yes global (`{footman.prog()} --yes workflow.release"
                        " ...`); silence never publishes."
                    )
                print(f"  skipped {plan.package.name}")
                continue
            dist = build_dev(root, plan)
            wheel = next(iter(dist.glob("*.whl")), None)
            built = wheel.name if wheel else "dist/"
            print(f"  built {plan.package.name} {plan.version} -> {built}")
            if taken:
                # The member's publish phase owns the upload, as in the
                # release train's wave; a False is a re-run walking past
                # what an earlier one published, which the step says.
                if _lifecycle.publish(
                    plan.package,
                    root,
                    version=semver_to_pep440(plan.version),
                    target=target,
                ):
                    print(f"  published {plan.package.name} {plan.version} to {index}")
            elif publishing:
                print(
                    f"  not published {plan.package.name}: the custom index takes"
                    f" {target.kind} distributions alone, and it releases {named}"
                )