Skip to content

livery.workshop._update_driver

livery.workshop._update_driver

workflow.update: the update family on the engine.

One update: workflow.update.dependencies [names...] brings dependencies current in both of their homes, the lock for external dependencies and the floors for workspace siblings, which the lock cannot move because they resolve from source; the bare workflow.update runs it for every dependency. The extensions are dependencies like any other: the update installs what the lock moved to and writes the files the new wheels compose, so a new workshop and its files arrive in one pull request.

An update prepared while a release flies parks unarmed and waits, watching the releases; when the last completes it re-runs itself, picking up the fresh floors, and arms. Ctrl-C is safe: re-entry is the same state machine. A non-interactive run waits bounded, then parks at exit 0 with the same prose, parked is the verb having done its job.

Classes:

Name Description
UpdateDriver

One update flavor's driver for the shared engine.

Functions:

Name Description
run_gate

Run the gate with --fix over the update's changes; red stops.

wait_for_releases

Wait while releases fly; True when none remains in flight.

update_dependencies

Bring dependencies current in both of their homes.

update_default

Bring every dependency current: the bare workflow.update.dependencies.

Attributes:

Name Type Description
BOUNDED_WAIT
WAIT_POLL
update_group

BOUNDED_WAIT module-attribute

BOUNDED_WAIT = 15 * 60

WAIT_POLL module-attribute

WAIT_POLL = 15

update_group module-attribute

update_group = workflow.group('update', help='Bring the workspace current')

UpdateDriver

UpdateDriver(root: Path, flavor: str, *, armed: bool, names: tuple[str, ...] = (), refresh: bool = False)

One update flavor's driver for the shared engine.

Methods:

Name Description
discard

Refuse: an update has no release set, so nothing makes it stale.

prepare

Do the flavor's work, or resume what a killed run committed.

on_merged

Merging is an update's completion; nothing follows.

Attributes:

Name Type Description
kind
members tuple[str, ...]
watch float
name
armed
branch str
base str
Source code in packages/workshop/src/livery/workshop/_update_driver.py
def __init__(
    self,
    root: Path,
    flavor: str,
    *,
    armed: bool,
    names: tuple[str, ...] = (),
    refresh: bool = False,
) -> None:
    self._root = root
    self._names = names
    self._refresh = refresh
    self.name = f"update/{flavor}"
    self.armed = armed

kind class-attribute instance-attribute

members class-attribute instance-attribute

members: tuple[str, ...] = ()

watch class-attribute instance-attribute

watch: float = 0.0

name instance-attribute

name = f'update/{flavor}'

armed instance-attribute

armed = armed

branch property

branch: str

base property

base: str

discard

discard() -> None

Refuse: an update has no release set, so nothing makes it stale.

Only a release's moved set re-derives; an update behind its base merges the base in instead.

Source code in packages/workshop/src/livery/workshop/_update_driver.py
def discard(self) -> None:
    """Refuse: an update has no release set, so nothing makes it stale.

    Only a release's moved set re-derives; an update behind its
    base merges the base in instead.
    """
    fail(f"{self.name} never re-derives: an update has no release set")

prepare

prepare() -> Submission | None

Do the flavor's work, or resume what a killed run committed.

Committed-but-unsubmitted work on the branch is submitted as it stands, redoing nothing: every subject on the branch is the driver's own conventional chore: line, so resuming is safe; a foreign subject stops with the options, someone's hand-made commits are not silently shipped. A refresh driver (the re-run after a parked update's releases finish) runs the work again on the branch instead, so the floors those releases earned land as a second commit.

Source code in packages/workshop/src/livery/workshop/_update_driver.py
def prepare(self) -> Submission | None:
    """Do the flavor's work, or resume what a killed run committed.

    Committed-but-unsubmitted work on the branch is submitted as
    it stands, redoing nothing: every subject on the branch is the
    driver's own conventional ``chore:`` line, so resuming is
    safe; a foreign subject stops with the options, someone's
    hand-made commits are not silently shipped. A *refresh*
    driver (the re-run after a parked update's releases finish)
    runs the work again on the branch instead, so the floors
    those releases earned land as a second commit.
    """
    root = self._root
    resumed = False
    if git.current_branch(root) == self.branch or git.local_branch_exists(
        root, self.branch
    ):
        if git.current_branch(root) != self.branch:
            git.switch(root, self.branch)
        subjects = git.subjects_ahead(root, self.base)
        if subjects:
            # A "Merge " subject is the engine's own MERGE_DEFAULT
            # bringing the base in, never someone's hand-made work.
            foreign = [
                s
                for s in subjects
                if not s.startswith("chore:") and not s.startswith("Merge ")
            ]
            if foreign:
                listed = "\n".join(f"    {s}" for s in foreign)
                fail(
                    "the update branch carries commits this driver did"
                    f" not make:\n{listed}\n  submit them yourself with"
                    f" `{footman.prog()} submit`, or abort the update with"
                    f" `{footman.prog()} workflow.abort {self.name}` and"
                    " start over."
                )
            if not self._refresh:
                print("  resuming the committed update from its branch")
                return Submission(title=subjects[-1], body="")
            resumed = True
    elif self.branch in git.remote_branches(root, ""):
        # The engine returns to the branch it started from and
        # drops the local copy once the pull request holds the
        # branch, so a re-run resumes from origin's copy.
        git.fetch(root)
        git.run(root, "checkout", "-b", self.branch, f"origin/{self.branch}")
        return self.prepare()
    else:
        git.create_branch(root, self.branch)
    toolchain_before = _locked_workshop(self._root)
    notes = self._work()
    # The new wheels ship the files they compose: install them, then
    # write those files, so the lock and what it brings land together.
    run_uv("sync", root=self._root)
    from livery.workshop._templates import apply_project

    notes += [f"composed: {path}" for path in apply_project(self._root)]
    if git.is_clean(root):
        if resumed:
            # A refresh with nothing new: the committed work stands.
            subjects = git.subjects_ahead(root, self.base)
            return Submission(title=subjects[-1], body="")
        git.switch(root, self.base)
        git.delete_branch(root, self.branch)
        return None
    run_gate(self._root)
    title = f"chore: {self.name.replace('/', ' ')}"
    git.commit_all(root, title + "\n\n" + "\n".join(f"- {n}" for n in notes))
    toolchain_after = _locked_workshop(self._root)
    if (
        toolchain_after != toolchain_before
        and toolchain_after
        and not os.environ.get(_REEXEC_FLAG)
    ):
        # The update just moved the running toolchain itself, and
        # the synced venv now holds newer code than this process.
        # The submit re-runs in a fresh interpreter so a fix the
        # update ships can protect its own submission; the resume
        # path submits the committed branch and redoes nothing.
        self._reexec()
    return Submission(title=title, body="\n".join(f"- {n}" for n in notes))

on_merged

on_merged() -> None

Merging is an update's completion; nothing follows.

Source code in packages/workshop/src/livery/workshop/_update_driver.py
def on_merged(self) -> None:
    """Merging is an update's completion; nothing follows."""

run_gate

run_gate(root: Path) -> None

Run the gate with --fix over the update's changes; red stops.

A red gate leaves the changes uncommitted on the workflow branch: fix the tree there and run the same update verb again, it resumes from that state. The gate's own output carries in the refusal, because the caller is often a script that sees only this message and would otherwise be told a gate is red with no word about which step.

Source code in packages/workshop/src/livery/workshop/_update_driver.py
def run_gate(root: Path) -> None:
    """Run the gate with ``--fix`` over the update's changes; red stops.

    A red gate leaves the changes uncommitted on the workflow branch:
    fix the tree there and run the same update verb again, it
    resumes from that state. The gate's own output carries in the
    refusal, because the caller is often a script that sees only
    this message and would otherwise be told a gate is red with no
    word about which step.
    """
    result = tools.uv.opts(cwd=root, nofail=True, recorded=False)(
        "run", "fm", "check", "--fix"
    )
    if result.code != 0:
        fail(
            f"the gate is red on the update's changes (exit"
            f" {result.code}):\n{result.stdout[-6000:]}"
            f"{result.stderr[-3000:]}\n"
            "  The changes are uncommitted on this branch: fix the"
            " tree, then run the same update verb again to resume."
        )

wait_for_releases

wait_for_releases(repo: Repository, root: Path, *, interactive: bool, timeout: float = BOUNDED_WAIT, poll: float = WAIT_POLL) -> bool

Wait while releases fly; True when none remains in flight.

The parked update's promise: it finishes itself once the last release completes. Interactive runs wait indefinitely, Ctrl-C always safe (re-entry resumes); non-interactive runs wait timeout then answer False, and the caller parks at exit 0.

Source code in packages/workshop/src/livery/workshop/_update_driver.py
def wait_for_releases(
    repo: Repository,
    root: Path,
    *,
    interactive: bool,
    timeout: float = BOUNDED_WAIT,
    poll: float = WAIT_POLL,
) -> bool:
    """Wait while releases fly; True when none remains in flight.

    The parked update's promise: it finishes itself once the last
    release completes. Interactive runs wait indefinitely, Ctrl-C
    always safe (re-entry resumes); non-interactive runs wait
    *timeout* then answer False, and the caller parks at exit 0.
    """
    from livery.workshop._verdict import (
        FollowTimedOut,
        ForgeUnreachable,
        Pending,
        follow,
    )

    announced = False

    def read() -> bool | Pending:
        nonlocal announced
        live = _live_releases(repo, root)
        if not live:
            return True
        if not announced:
            announced = True
            listed = ", ".join(live)
            print(
                f"  Release(s) in progress: {listed}. This update will be"
                " finished automatically once they all finish. Ctrl-C is"
                f" safe; run `{footman.prog()} workflow.update` any time to continue"
                " later."
            )
        return Pending()

    try:
        follow(
            repo,
            read,
            subject="the releases in flight",
            interval=poll,
            timeout=None if interactive else timeout,
            quiet=None,
        )
    except FollowTimedOut:
        return False
    except ForgeUnreachable as exc:
        fail(exc.line.strip())
    return True

update_dependencies

update_dependencies(*names: str, armed: Annotated[bool, doc("arm the update's PR to merge on green")] = False) -> None

Bring dependencies current in both of their homes.

Bare upgrades every external dependency through the lock and raises every sibling floor to its latest release; naming dependencies scopes which move, never where, one workspace lock is one resolution. A named sibling moves its floor and only its floor, since the lock cannot move what resolves from source.

Source code in packages/workshop/src/livery/workshop/_update_driver.py
@update_group.task(name="dependencies")
def update_dependencies(
    *names: str,
    armed: Annotated[bool, doc("arm the update's PR to merge on green")] = False,
) -> None:
    """Bring dependencies current in both of their homes.

    Bare upgrades every external dependency through the lock and
    raises every sibling floor to its latest release; naming
    dependencies scopes which move, never where, one workspace lock
    is one resolution. A named sibling moves its floor and only its
    floor, since the lock cannot move what resolves from source.
    """
    _drive("dependencies", armed=armed, names=names)

update_default

update_default(armed: Annotated[bool, doc("arm the update's PR to merge on green")] = False) -> None

Bring every dependency current: the bare workflow.update.dependencies.

Source code in packages/workshop/src/livery/workshop/_update_driver.py
@update_group.default
def update_default(
    armed: Annotated[bool, doc("arm the update's PR to merge on green")] = False,
) -> None:
    """Bring every dependency current: the bare `workflow.update.dependencies`."""
    _drive("dependencies", armed=armed)