Skip to content

livery.strongroom._rungs

livery.strongroom._rungs

The materialiser's rungs: how one object becomes one path.

Cheapest first: clone (copy-on-write), hardlink, link, copy. Each rung is one function with the same shape, and the platform-specific ones sit behind seams so a test forces every fallback without the filesystem's cooperation. The reference rung is livery.strongroom.Store.path: a path into the tier itself, with nothing created.

Which rung a view reaches on a platform is not conformance material; the rules that decide eligibility are, and they live in _views.

remove and remove_tree are the rungs' inverse: they take a path a rung made back off the disk whatever mode the rung left on it.

Classes:

Name Description
RungUnavailable

The rung cannot produce this path here; try the next one.

Functions:

Name Description
clone_darwin

APFS copy-on-write through libc's clonefile.

clone_linux

Copy-on-write through the FICLONE ioctl: btrfs, XFS, bcachefs.

clone_unavailable

No copy-on-write here: ReFS block cloning is not wired, nothing else has it.

hardlink

A second name for the object's inode; the mode is shared.

copy

The last rung: bytes copied, always available.

remove

Remove a file or link a rung made, whatever its mode; a missing path is done.

remove_tree

Remove a directory a rung copied, whatever the modes inside it.

Attributes:

Name Type Description
Rung

The ladder, cheapest first.

MadeRung

The rungs that create a path inside a view: every rung but reference.

RUNGS tuple[Rung, ...]
CLONE Callable[[Path, Path], None]

This platform's clone, chosen once at import.

Symlink

The shape of the symlink seam: target, destination, and directory by keyword.

symlink Symlink

A symlink to the target, relative when given so; a junction's place on Windows.

Rung module-attribute

Rung = Literal['reference', 'clone', 'hardlink', 'link', 'copy']

The ladder, cheapest first.

MadeRung module-attribute

MadeRung = Literal['clone', 'hardlink', 'link', 'copy']

The rungs that create a path inside a view: every rung but reference.

RUNGS module-attribute

RUNGS: tuple[Rung, ...] = ('reference', 'clone', 'hardlink', 'link', 'copy')

CLONE module-attribute

CLONE: Callable[[Path, Path], None] = {'darwin': clone_darwin, 'linux': clone_linux}.get(sys.platform, clone_unavailable)

This platform's clone, chosen once at import.

Symlink = Callable[..., None]

The shape of the symlink seam: target, destination, and directory by keyword.

symlink: Symlink = _symlink

A symlink to the target, relative when given so; a junction's place on Windows.

A variable, not a function, so the conformance harness can stand a refusing platform in its place and put it back.

RungUnavailable

Bases: OSError

The rung cannot produce this path here; try the next one.

clone_darwin

clone_darwin(source: Path, destination: Path) -> None

APFS copy-on-write through libc's clonefile.

Source code in packages/strongroom/src/livery/strongroom/_rungs.py
def clone_darwin(source: Path, destination: Path) -> None:
    """APFS copy-on-write through libc's clonefile."""
    libc = ctypes.CDLL(ctypes.util.find_library("c"), use_errno=True)
    result = libc.clonefile(
        os.fsencode(source), os.fsencode(destination), ctypes.c_int(0)
    )
    if result != 0:
        errno = ctypes.get_errno()
        raise RungUnavailable(errno, f"clonefile: {os.strerror(errno)}")

clone_linux

clone_linux(source: Path, destination: Path) -> None

Copy-on-write through the FICLONE ioctl: btrfs, XFS, bcachefs.

Source code in packages/strongroom/src/livery/strongroom/_rungs.py
def clone_linux(source: Path, destination: Path) -> None:
    """Copy-on-write through the FICLONE ioctl: btrfs, XFS, bcachefs."""
    import fcntl

    # Looked up by name: the stubs define ioctl only off Windows, and
    # this function is never called there.
    ioctl: Callable[[int, int, int], int] = getattr(fcntl, "ioctl")  # noqa: B009
    with source.open("rb") as src, destination.open("wb") as dst:
        try:
            ioctl(dst.fileno(), _FICLONE, src.fileno())
        except OSError as error:
            dst.close()
            destination.unlink(missing_ok=True)
            raise RungUnavailable(error.errno, f"FICLONE: {error.strerror}") from None

clone_unavailable

clone_unavailable(source: Path, destination: Path) -> None

No copy-on-write here: ReFS block cloning is not wired, nothing else has it.

Source code in packages/strongroom/src/livery/strongroom/_rungs.py
def clone_unavailable(source: Path, destination: Path) -> None:
    """No copy-on-write here: ReFS block cloning is not wired, nothing else has it."""
    raise RungUnavailable(0, f"no clone rung on {sys.platform}")
hardlink(source: Path, destination: Path) -> None

A second name for the object's inode; the mode is shared.

Source code in packages/strongroom/src/livery/strongroom/_rungs.py
def hardlink(source: Path, destination: Path) -> None:
    """A second name for the object's inode; the mode is shared."""
    try:
        os.link(source, destination)
    except OSError as error:
        raise RungUnavailable(error.errno, f"link: {error.strerror}") from None

copy

copy(source: Path, destination: Path) -> None

The last rung: bytes copied, always available.

Source code in packages/strongroom/src/livery/strongroom/_rungs.py
def copy(source: Path, destination: Path) -> None:
    """The last rung: bytes copied, always available."""
    shutil.copyfile(source, destination)

remove

remove(path: Path) -> None

Remove a file or link a rung made, whatever its mode; a missing path is done.

A refusal on a read-only file clears the read-only attribute and unlinks again. A hardlink shares that attribute with the store's object, which is left writable afterwards, the state the store keeps its objects in.

Source code in packages/strongroom/src/livery/strongroom/_rungs.py
def remove(path: Path) -> None:
    """Remove a file or link a rung made, whatever its mode; a missing path is done.

    A refusal on a read-only file clears the read-only attribute and
    unlinks again. A hardlink shares that attribute with the store's
    object, which is left writable afterwards, the state the store
    keeps its objects in.
    """
    try:
        _unlink(path)
    except FileNotFoundError:
        return
    except PermissionError:
        _writable(path)
        _unlink(path)

remove_tree

remove_tree(path: Path) -> None

Remove a directory a rung copied, whatever the modes inside it.

A refusal makes every directory and file under path writable and removes again.

Source code in packages/strongroom/src/livery/strongroom/_rungs.py
def remove_tree(path: Path) -> None:
    """Remove a directory a rung copied, whatever the modes inside it.

    A refusal makes every directory and file under *path* writable
    and removes again.
    """
    try:
        _rmtree(path)
    except PermissionError:
        for parent, directories, files in os.walk(path):
            for name in [*directories, *files]:
                _writable(Path(parent) / name)
        _writable(path)
        _rmtree(path)