Skip to content

livery.workshop._reconcile

livery.workshop._reconcile

The per-command hook: a sync runs before a command, frozen and offline.

Runs at footman's per-task moment, before the first task of a command, from the hook in livery.workshop._env_tasks. It runs the sync verb's work on the root the hook found (livery.workshop._sync.sync_checkout), in the mode that changes nothing a commit holds and touches no network, as a plain call: footman gives a task called from a hook a directory of its own and a row in the run's report, and a failed row fails the command. The sync reads the receipts a checkout keeps of its last sync (livery.workshop._reconcile.current): the uv lock and the manifests the venv was installed from, the tool receipts against toolroom.lock, and the receipt of the files the extensions write for the checkout alone. A current checkout costs those reads and nothing else; one that is not is brought current from what the machine holds, and the command re-runs on the installed code when that sync changed it, so a pull that moved the lock never judges from stale code. When sync is the command, the hook leaves the work to it.

The receipts live here beside the hook. What a sync records at its end and what it reads at its start are one record.

Never fatal: on any failure the command proceeds and the failure is reported in the sync's own words. A task that cannot run without what is missing is still caught by its own gate.

Functions:

Name Description
receipt_path

Where root's sync receipt lives.

manifests_receipt_path

Where root's manifests receipt lives.

manifests_digest

A digest of the root pyproject.toml and every package's pyproject.toml.

record_receipt

Record uv.lock and the manifests as the venv's receipts; silent otherwise.

is_cli_process

Whether this process is a real runner invocation.

installed_distributions

Every *.dist-info name in the venv, to its entry points' digest.

current

Why root is not current, in a few words; empty when it is.

tools_current

Why the tool receipts do not match toolroom.lock; empty when they do.

apply

Sync root before task, the command's first; whether the sync did work.

Attributes:

Name Type Description
MOVED
SYNCED
INSTALLED
RELOCATED
RECEIPT_NAME
MANIFESTS_RECEIPT_NAME

MOVED module-attribute

MOVED = 'moved'

SYNCED module-attribute

SYNCED = 'synced'

INSTALLED module-attribute

INSTALLED = 'installed'

RELOCATED module-attribute

RELOCATED = 'relocated'

RECEIPT_NAME module-attribute

RECEIPT_NAME = '.workshop-sync-receipt'

MANIFESTS_RECEIPT_NAME module-attribute

MANIFESTS_RECEIPT_NAME = '.workshop-manifests-receipt'

receipt_path

receipt_path(root: Path) -> Path

Where root's sync receipt lives.

Source code in packages/workshop/src/livery/workshop/_reconcile.py
def receipt_path(root: Path) -> Path:
    """Where *root*'s sync receipt lives."""
    return root / ".venv" / RECEIPT_NAME

manifests_receipt_path

manifests_receipt_path(root: Path) -> Path

Where root's manifests receipt lives.

Source code in packages/workshop/src/livery/workshop/_reconcile.py
def manifests_receipt_path(root: Path) -> Path:
    """Where *root*'s manifests receipt lives."""
    return root / ".venv" / MANIFESTS_RECEIPT_NAME

manifests_digest

manifests_digest(root: Path) -> str

A digest of the root pyproject.toml and every package's pyproject.toml.

Path order, each path and its bytes, so a member added, removed, or edited changes the digest.

Source code in packages/workshop/src/livery/workshop/_reconcile.py
def manifests_digest(root: Path) -> str:
    """A digest of the root ``pyproject.toml`` and every package's ``pyproject.toml``.

    Path order, each path and its bytes, so a member added, removed,
    or edited changes the digest.
    """
    import hashlib

    from livery.workshop._packages import package_directories

    digest = hashlib.sha256()
    manifests = sorted(
        [
            root / "pyproject.toml",
            *(directory / "pyproject.toml" for directory in package_directories(root)),
        ]
    )
    for path in manifests:
        if path.is_file():
            digest.update(path.relative_to(root).as_posix().encode("utf-8"))
            digest.update(b"\0")
            digest.update(path.read_bytes())
            digest.update(b"\0")
    return digest.hexdigest()

record_receipt

record_receipt(root: Path) -> None

Record uv.lock and the manifests as the venv's receipts; silent otherwise.

Called after every successful sync so the next command's compare is a no-op instead of a second sync.

Source code in packages/workshop/src/livery/workshop/_reconcile.py
def record_receipt(root: Path) -> None:
    """Record ``uv.lock`` and the manifests as the venv's receipts; silent otherwise.

    Called after every successful sync so the next command's compare
    is a no-op instead of a second sync.
    """
    lock = root / "uv.lock"
    if lock.is_file() and (root / ".venv").is_dir():
        receipt_path(root).write_bytes(lock.read_bytes())
        manifests_receipt_path(root).write_text(manifests_digest(root), "utf-8")

is_cli_process

is_cli_process() -> bool

Whether this process is a real runner invocation.

The reconcile is opt-in from the runner's own console script, never opt-out by recognising footman's manifest-refresh child: that child is spawned as python -c ... and a test suite runs under pytest, so neither carries the runner's name in argv[0] and both leave the reconcile inert. The refresh child's contract is quick and quiet (no network, no prompts), and a test that shelled out to uv sync once per test would be slow and destructive.

Source code in packages/workshop/src/livery/workshop/_reconcile.py
def is_cli_process() -> bool:
    """Whether this process is a real runner invocation.

    The reconcile is opt-in from the runner's own console script,
    never opt-out by recognising footman's manifest-refresh child:
    that child is spawned as ``python -c ...`` and a test suite runs
    under pytest, so neither carries the runner's name in ``argv[0]``
    and both leave the reconcile inert. The refresh child's contract
    is quick and quiet (no network, no prompts), and a test that
    shelled out to ``uv sync`` once per test would be slow and
    destructive.
    """
    import livery.footman as footman

    if not sys.argv or not sys.argv[0]:
        return False
    return Path(sys.argv[0]).stem.lower() == footman.prog()

installed_distributions

installed_distributions(root: Path) -> dict[str, str]

Every *.dist-info name in the venv, to its entry points' digest.

Read across platform layouts. A name alone misses an editable member re-installed at the same version with new entry points: its directory keeps its name, and a process that mounted the old entry points would go on with them. The digest of each entry_points.txt (empty without one) makes that re-install a change.

Source code in packages/workshop/src/livery/workshop/_reconcile.py
def installed_distributions(root: Path) -> dict[str, str]:
    """Every ``*.dist-info`` name in the venv, to its entry points' digest.

    Read across platform layouts. A name alone misses an editable
    member re-installed at the same version with new entry points: its
    directory keeps its name, and a process that mounted the old entry
    points would go on with them. The digest of each
    ``entry_points.txt`` (empty without one) makes that re-install a
    change.
    """
    import hashlib

    found: dict[str, str] = {}
    for pattern in ("lib/python*/site-packages", "Lib/site-packages"):
        for site in (root / ".venv").glob(pattern):
            for entry in site.glob("*.dist-info"):
                try:
                    points = (entry / "entry_points.txt").read_bytes()
                except OSError:
                    points = b""
                found[entry.name] = hashlib.sha256(points).hexdigest() if points else ""
    return found

current

current(root: Path) -> str

Why root is not current, in a few words; empty when it is.

Four receipts, all local reads. The uv lock receipt and the manifests receipt against uv.lock and the manifests on disk; a venv synced before the manifests receipt existed adopts the manifests on disk as the ones installed, since the emitted setup.sh's fresh venv is that case, and the next move is seen. Then a receipt per tool toolroom.lock holds for this host, at the locked version and still in the store, with the stubs beside them; then the receipt a delivery leaves. A checkout with no lock or no venv has nothing to compare and is not current.

Source code in packages/workshop/src/livery/workshop/_reconcile.py
def current(root: Path) -> str:
    """Why *root* is not current, in a few words; empty when it is.

    Four receipts, all local reads. The uv lock receipt and the
    manifests receipt against ``uv.lock`` and the manifests on disk;
    a venv synced before the manifests receipt existed adopts the
    manifests on disk as the ones installed, since the emitted
    ``setup.sh``'s fresh venv is that case, and the next move is seen.
    Then a receipt per tool ``toolroom.lock`` holds for this host, at
    the locked version and still in the store, with the stubs beside
    them; then the receipt a delivery leaves. A checkout with no lock
    or no venv has nothing to compare and is not current.
    """
    lock = root / "uv.lock"
    if not lock.is_file():
        return "there is no uv.lock yet"
    if not (root / ".venv").is_dir():
        return "there is no environment yet"
    receipt = receipt_path(root)
    if not receipt.is_file() or receipt.read_bytes() != lock.read_bytes():
        return "uv.lock moved past the environment"
    digest = manifests_digest(root)
    manifests = manifests_receipt_path(root)
    if not manifests.is_file():
        manifests.write_text(digest, "utf-8")
    elif manifests.read_text("utf-8") != digest:
        return "a package manifest moved past the environment"
    why = tools_current(root)
    if why:
        return why
    from livery.workshop._fragment_engine import LOCAL_RECEIPT

    if not (root / LOCAL_RECEIPT).is_file():
        return "this checkout's own files were never delivered"
    return ""

tools_current

tools_current(root: Path) -> str

Why the tool receipts do not match toolroom.lock; empty when they do.

A receipt matches when it names the locked version and the directory it points into is still in the store; a receipt whose tool the store has lost reads as off, so a sync supplies it again. The stubs the checkers read stand beside the receipts: a checkout locked for this host with no typings/ is off too. A checkout with no toolroom.lock has nothing to match and is current here.

Source code in packages/workshop/src/livery/workshop/_reconcile.py
def tools_current(root: Path) -> str:
    """Why the tool receipts do not match ``toolroom.lock``; empty when they do.

    A receipt matches when it names the locked version and the
    directory it points into is still in the store; a receipt whose
    tool the store has lost reads as off, so a sync supplies it again.
    The stubs the checkers read stand beside the receipts: a checkout
    locked for this host with no ``typings/`` is off too. A checkout
    with no ``toolroom.lock`` has nothing to match and is current here.
    """
    import platform

    from livery.toolroom.store import LOCK_FILE, Lock, LockError, host_key
    from livery.workshop._tools import TYPINGS, tool_receipts

    if not (root / LOCK_FILE).is_file():
        return ""
    try:
        lock = Lock.load(root / LOCK_FILE)
        held = tool_receipts(root)
    except (LockError, ValueError, OSError):
        # An unreadable lock or receipt is the sync's to name, not
        # the hook's to judge: the sync reads both and refuses by name.
        return f"{LOCK_FILE} or a receipt could not be read"
    host = host_key(platform.system(), platform.machine())
    for name in lock.on_host(host):
        receipt = held.get(name)
        if receipt is None:
            return f"no receipt for {name}"
        if receipt.version != lock.tools[name].version:
            locked = lock.tools[name].version
            return f"{name} is at {receipt.version}, the lock holds {locked}"
        if receipt.tool_dir and not Path(receipt.tool_dir).is_dir():
            return f"the store no longer holds {name}"
    if lock.on_host(host) and not (root / TYPINGS).is_dir():
        return f"no stubs in {TYPINGS}/"
    return ""

apply

apply(root: Path, task: str, env: MutableMapping[str, str]) -> bool

Sync root before task, the command's first; whether the sync did work.

Nothing happens when task is sync, the verb itself, or inside a process the hook's own sync started, which env, the task's own environment, marks for the processes the sync starts. Otherwise the verb's work runs on root, frozen and offline, as a plain call (livery.workshop._sync.sync_checkout), its lines on stderr so a command whose stdout a shell evaluates stays clean. It reads the receipts first and does nothing, silently, for a current checkout; otherwise it says what is off and brings the checkout current, and the command re-runs on the installed code when that changed it. A sync that fails is said and the command runs on what is here: the sync is not a task of the run, so its failure adds no failed row, and the command's verdict is its own.

Returns:

Type Description
bool

Whether the sync did work. The caller entered the environment

bool

before it, from receipts the sync may have written since, so it

bool

enters again.

Source code in packages/workshop/src/livery/workshop/_reconcile.py
def apply(root: Path, task: str, env: MutableMapping[str, str]) -> bool:
    """Sync *root* before *task*, the command's first; whether the sync did work.

    Nothing happens when *task* is ``sync``, the verb itself, or inside
    a process the hook's own sync started, which *env*, the task's own
    environment, marks for the processes the sync starts. Otherwise the
    verb's work runs on *root*, frozen and offline, as a plain call
    ([livery.workshop._sync.sync_checkout][]), its lines on stderr so
    a command whose stdout a shell evaluates stays clean. It reads the
    receipts first and does nothing, silently, for a current checkout;
    otherwise it says what is off and brings the checkout current, and
    the command re-runs on the installed code when that changed it. A
    sync that fails is said and the command runs on what is here: the
    sync is not a task of the run, so its failure adds no failed row,
    and the command's verdict is its own.

    Returns:
        Whether the sync did work. The caller entered the environment
        before it, from receipts the sync may have written since, so it
        enters again.
    """
    import contextlib

    import livery.footman as footman

    if os.environ.get(_SYNCING) or env.get(_SYNCING) or task == "sync":
        return False
    prog = footman.prog()
    # Set in the task's own environment, which the sync's children see
    # and no sibling does, and removed after them.
    env[_SYNCING] = "1"
    try:
        from livery.workshop._sync import sync_and_compare

        with contextlib.redirect_stdout(sys.stderr):
            synced = sync_and_compare(root, frozen=True, offline=True)
    except Exception as error:  # the hook never stops the command it precedes
        _say(f"{prog}: the sync did not complete ({error}); running on what is here")
        return False
    finally:
        env.pop(_SYNCING, None)
    if synced.installs_changed:
        _reexec(root, SYNCED)
    return synced.ran