Skip to content

livery.strongroom

livery.strongroom

Content-addressed storage: one address space, every tenant.

The store names bytes by their digest, keeps trees and versions as blobs in specified formats, moves refs by compare-and-swap with a record beside each, and hands a real path to a program that needs one. It knows no tool, no call and no dataset: a consumer composes the formats and owns its namespaces.

This release carries the formats: livery.strongroom.canonical for the one hashed encoding, livery.strongroom.Digest for names, livery.strongroom.Tree and livery.strongroom.Version for the two objects with structure, and livery.strongroom.RefRecord and livery.strongroom.Tombstone for the two records beside names. The standard they implement is the spec/ directory beside this package, with the golden vectors the tests run.

livery.strongroom.Store is the local store over those formats: objects landed by digest and verified, refs moved by compare-and-swap under a per-ref lock with a record beside each, and a mutation class per namespace. Its refusals are the classes under livery.strongroom.StoreError. A store opened with sources (livery.strongroom.FolderSource, livery.strongroom.HttpSource, livery.strongroom.OriginHint) fetches what it lacks through them, verified and in order, with livery.strongroom.Store.fetch, and builds a mirror with livery.strongroom.Store.fill. The lifecycle is the store's too: livery.strongroom.Store.publish_begin and livery.strongroom.Store.publish_commit for the fail-closed publish, livery.strongroom.Store.sweep for reachability, and livery.strongroom.Store.erase for the tombstone. The materialiser is livery.strongroom.Store.view, livery.strongroom.Store.collect and livery.strongroom.Store.drop_view: the only route from a digest to a path, by the cheapest safe rung, under a doctrine about what may be removed. livery.strongroom.testing runs the conformance scenarios under spec/conformance against any implementation of the same API; importing this package does not load it. The codec, livery.strongroom.cbor, is part of the public API, declared here and imported by its own path; importing this module does not load it either.

Modules:

Name Description
cbor

Deterministic CBOR: one value, one encoding, one name.

testing

The conformance kit: the scenarios under spec/conformance, run against a store.

Classes:

Name Description
FormatError

A value does not satisfy one of the store's formats.

Algorithm

One registry entry: how an algorithm names bytes.

Digest

A parsed digest string.

HashConstructor

A hashlib-style constructor: optional initial bytes, a hasher back.

Hasher

What a registry entry's constructor returns: hashlib's shape.

ErasedObject

The named object was erased; its tombstone says why.

GroupHalfApplied

A commit already applied part of the group; only a commit finishes it.

IntegrityError

Bytes do not match their name: a landing mismatch or a corrupt object.

LockTimeout

A live lock on the ref was not released within the timeout.

ManifestError

The root manifest is missing, malformed, or of another store.

MissingObject

The named object is not in the store.

NoSuchPending

The named pending publish does not exist: retired, committed, or never begun.

NotAGroup

The pending ref is a single publish's, not a group's.

NotFastForward

A monotone ref's new target does not descend from its current one.

RefConflict

A compare-and-swap lost: the ref does not name the expected previous digest.

RefProtected

The ref's mutation class does not allow dropping it.

RefTampered

A ref and its record disagree: an out-of-band edit or a torn update.

StoreError

The store refused an operation; the message says why.

UnknownNamespace

A ref names a namespace the store was not opened with.

WriteOnceRefused

A write-once ref already names a different digest.

Subject

A subject slot: a person, a call key, a receipt digest, or code.

Group

A group of moves that has begun and not yet committed.

Move

One ref move of a group.

Transaction

A group under a with: moves recorded as they come, the exit decides.

Pending

A publish that has begun and not yet committed.

SweepReport

What a sweep did.

RefRecord

What a ref update writes beside the ref.

Tombstone

What an erased object becomes, in every tier.

RungUnavailable

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

FolderSource

A folder in the store layout: a mirror, or a read-only share.

HttpSource

An HTTP base URL serving the store layout: nginx over a folder.

OriginHint

One URL that yields one named object: the ingress form.

Unreachable

A source did not answer for this object; the fetch skips it and reports.

Landed

What a landing produced.

Manifest

The root manifest: which layout and which algorithm this store speaks.

Namespace

A ref namespace and its mutation class.

ScrubReport

What a scrub found.

Store

A local store: objects/ by digest, refs/ by name.

Entry

A blob or a subtree inside a tree.

Link

A symlink inside a tree; the target string is its whole content.

Tree

A directory: its entries, sorted by name bytes.

Version

Provenance over a tree.

DropReport

What dropping a view removed and what it left.

ShedReport

What a shed did.

ViewEntry

One path a view created, and how.

ViewRecord

A view: local state in the index, and a root while its directory exists.

Functions:

Name Description
canonical

Encode value as RFC 8785 canonical JSON, UTF-8.

digest_of

Name data under algorithm.

digest_stream

Name the bytes read from stream to its end, without holding them.

check_timestamp

Return value when it is an RFC 3339 UTC instant, or refuse.

fetch_url

Open url for reading, or raise Unreachable naming why.

now

The current instant, RFC 3339 in UTC to the second.

silent

The default progress sink: report nothing.

check_name

Return name when it is portable, or refuse it.

check_target

Return a symlink target when it is portable, or refuse it.

Attributes:

Name Type Description
Value TypeAlias

A JSON value the store's formats may carry: no float, nested the same way.

ALGORITHMS Final[dict[str, Algorithm]]

The registry. Only cryptographic, full-length digests may name bytes.

SHA256 Final

The required algorithm, and the only one in the registry.

SubjectKind

Who or what may fill a subject slot.

PENDING

The namespace of publishes that have begun and not committed.

PINS

The namespace of explicit roots.

RUNGS tuple[Rung, ...]
MadeRung

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

Rung

The ladder, cheapest first.

FillPolicy

What a folder hit does: land a local copy, or answer into the folder.

Progress

Where a fetch reports a skipped or refused source; never prints on its own.

Source

Anything a store may consult for an object.

LAYOUT_VERSION

The layout this implementation speaks.

MANIFEST_NAME

The root manifest's file name.

MUTATION_CLASSES tuple[MutationClass, ...]
OWNED tuple[Namespace, ...]

The two namespaces the store declares itself; see spec/namespaces.md.

Clock

Returns the current instant as an RFC 3339 UTC string.

MutationClass

How a namespace's refs may move; see spec/namespaces.md.

ObjectState

The three states an object name can be in.

NAME_BUDGET

The most UTF-8 bytes one name may take.

EntryKind

What a digest-bearing entry names.

ENTRY_RUNGS tuple[EntryRung, ...]
PATH_BUDGET

The most UTF-8 bytes a path inside a view may take, separators included.

EntryRung

How one view entry was made: a ladder rung, a real symlink, or not at all.

__version__

TYPE_CHECKING module-attribute

TYPE_CHECKING = False

Value module-attribute

Value: TypeAlias = 'bool | int | str | list[Any] | dict[str, Any] | None'

A JSON value the store's formats may carry: no float, nested the same way.

ALGORITHMS module-attribute

ALGORITHMS: Final[dict[str, Algorithm]] = {SHA256.name: SHA256}

The registry. Only cryptographic, full-length digests may name bytes.

SHA256 module-attribute

SHA256: Final = Algorithm('sha256', re.compile('^[a-f0-9]{64}$'), hashlib.sha256)

The required algorithm, and the only one in the registry.

SubjectKind module-attribute

SubjectKind = Literal['person', 'call', 'receipt', 'code']

Who or what may fill a subject slot.

PENDING module-attribute

PENDING = 'pending'

The namespace of publishes that have begun and not committed.

PINS module-attribute

PINS = 'pins'

The namespace of explicit roots.

RUNGS module-attribute

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

MadeRung module-attribute

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

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

Rung module-attribute

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

The ladder, cheapest first.

FillPolicy module-attribute

FillPolicy = Literal['copy', 'reference']

What a folder hit does: land a local copy, or answer into the folder.

Progress module-attribute

Progress = Callable[[str], None]

Where a fetch reports a skipped or refused source; never prints on its own.

Source module-attribute

Anything a store may consult for an object.

LAYOUT_VERSION module-attribute

LAYOUT_VERSION = 1

The layout this implementation speaks.

MANIFEST_NAME module-attribute

MANIFEST_NAME = 'strongroom.json'

The root manifest's file name.

MUTATION_CLASSES module-attribute

MUTATION_CLASSES: tuple[MutationClass, ...] = ('write-once', 'monotone', 'volatile')

OWNED module-attribute

OWNED: tuple[Namespace, ...] = (Namespace('pins', 'volatile'), Namespace('pending', 'volatile'))

The two namespaces the store declares itself; see spec/namespaces.md.

Clock module-attribute

Clock = Callable[[], str]

Returns the current instant as an RFC 3339 UTC string.

MutationClass module-attribute

MutationClass = Literal['write-once', 'monotone', 'volatile']

How a namespace's refs may move; see spec/namespaces.md.

ObjectState module-attribute

ObjectState = Literal['present', 'absent', 'erased']

The three states an object name can be in.

NAME_BUDGET module-attribute

NAME_BUDGET = 255

The most UTF-8 bytes one name may take.

EntryKind module-attribute

EntryKind = Literal['blob', 'tree']

What a digest-bearing entry names.

ENTRY_RUNGS module-attribute

ENTRY_RUNGS: tuple[EntryRung, ...] = ('clone', 'hardlink', 'link', 'copy', 'symlink', 'parked')

PATH_BUDGET module-attribute

PATH_BUDGET = 1024

The most UTF-8 bytes a path inside a view may take, separators included.

EntryRung module-attribute

EntryRung = Literal['clone', 'hardlink', 'link', 'copy', 'symlink', 'parked']

How one view entry was made: a ladder rung, a real symlink, or not at all.

__all__ module-attribute

__all__ = ['ALGORITHMS', 'ENTRY_RUNGS', 'LAYOUT_VERSION', 'MANIFEST_NAME', 'MUTATION_CLASSES', 'NAME_BUDGET', 'OWNED', 'PATH_BUDGET', 'PENDING', 'PINS', 'RUNGS', 'SHA256', 'Algorithm', 'Clock', 'Digest', 'DropReport', 'Entry', 'EntryKind', 'EntryRung', 'ErasedObject', 'FillPolicy', 'FolderSource', 'FormatError', 'Group', 'GroupHalfApplied', 'HashConstructor', 'Hasher', 'HttpSource', 'IntegrityError', 'Landed', 'Link', 'LockTimeout', 'MadeRung', 'Manifest', 'ManifestError', 'MissingObject', 'Move', 'MutationClass', 'Namespace', 'NoSuchPending', 'NotAGroup', 'NotFastForward', 'ObjectState', 'OriginHint', 'Pending', 'Progress', 'RefConflict', 'RefProtected', 'RefRecord', 'RefTampered', 'Rung', 'RungUnavailable', 'ScrubReport', 'ShedReport', 'Source', 'Store', 'StoreError', 'Subject', 'SubjectKind', 'SweepReport', 'Tombstone', 'Transaction', 'Tree', 'UnknownNamespace', 'Unreachable', 'Value', 'Version', 'ViewEntry', 'ViewRecord', 'WriteOnceRefused', '__version__', 'canonical', 'cbor', 'check_name', 'check_target', 'check_timestamp', 'digest_of', 'digest_stream', 'fetch_url', 'now', 'silent', 'testing']

__version__ module-attribute

__version__ = '0.5.0'

FormatError

Bases: ValueError

A value does not satisfy one of the store's formats.

The message names the rule that refused it. Every format refusal raises this one class, so a caller validating a whole tree catches one thing.

Algorithm dataclass

Algorithm(name: str, encoded: Pattern[str], constructor: HashConstructor)

One registry entry: how an algorithm names bytes.

Attributes:

Name Type Description
name str

the algorithm's spelling in a digest string.

encoded Pattern[str]

the pattern the encoded part must match in full.

constructor HashConstructor

the hashlib constructor that computes it.

name instance-attribute

name: str

encoded instance-attribute

encoded: Pattern[str]

constructor instance-attribute

constructor: HashConstructor

Digest dataclass

Digest(algorithm: str, encoded: str)

A parsed digest string.

Attributes:

Name Type Description
algorithm str

the registry entry's name, sha256.

encoded str

the lowercase hex of the digest.

Methods:

Name Description
__str__
parse

Parse a digest string, refusing anything the registry lacks.

algorithm instance-attribute

algorithm: str

encoded instance-attribute

encoded: str

path_parts property

path_parts: tuple[str, str, str]

The object's path under objects/: algorithm, fan-out, rest.

__str__

__str__() -> str
Source code in packages/strongroom/src/livery/strongroom/_digest.py
def __str__(self) -> str:
    return f"{self.algorithm}:{self.encoded}"

parse classmethod

parse(text: str) -> Digest

Parse a digest string, refusing anything the registry lacks.

Parameters:

Name Type Description Default
text str

the <algorithm>:<encoded> spelling.

required

Returns:

Type Description
Digest

The digest.

Raises:

Type Description
FormatError

when the text is not in the OCI grammar, the algorithm is not registered, or the encoded part is not the full lowercase form the algorithm requires. A truncated or uppercase digest is refused so one object has one name.

Source code in packages/strongroom/src/livery/strongroom/_digest.py
@classmethod
def parse(cls, text: str) -> Digest:
    """Parse a digest string, refusing anything the registry lacks.

    Args:
        text: the `<algorithm>:<encoded>` spelling.

    Returns:
        The digest.

    Raises:
        FormatError: when the text is not in the OCI grammar, the
            algorithm is not registered, or the encoded part is
            not the full lowercase form the algorithm requires. A
            truncated or uppercase digest is refused so one object
            has one name.
    """
    match = _GRAMMAR.match(text)
    if match is None:
        raise FormatError(
            f"digest {text!r} is not '<algorithm>:<encoded>' in the OCI grammar"
        )
    algorithm = match["algorithm"]
    entry = ALGORITHMS.get(algorithm)
    if entry is None:
        known = ", ".join(sorted(ALGORITHMS))
        raise FormatError(
            f"digest algorithm {algorithm!r} is not in the registry"
            f" (registered: {known})"
        )
    encoded = match["encoded"]
    if entry.encoded.match(encoded) is None:
        raise FormatError(
            f"digest {text!r} is not a full lowercase {algorithm}"
            " digest; a truncated or re-cased digest is a second"
            " name for the same bytes"
        )
    return cls(algorithm, encoded)

HashConstructor

Bases: Protocol

A hashlib-style constructor: optional initial bytes, a hasher back.

Methods:

Name Description
__call__

__call__

__call__(data: bytes = b'') -> Hasher
Source code in packages/strongroom/src/livery/strongroom/_digest.py
def __call__(self, data: bytes = b"", /) -> Hasher: ...

Hasher

Bases: Protocol

What a registry entry's constructor returns: hashlib's shape.

Methods:

Name Description
update
hexdigest

update

update(data: bytes) -> None
Source code in packages/strongroom/src/livery/strongroom/_digest.py
def update(self, data: bytes, /) -> None: ...

hexdigest

hexdigest() -> str
Source code in packages/strongroom/src/livery/strongroom/_digest.py
def hexdigest(self) -> str: ...

ErasedObject

Bases: StoreError

The named object was erased; its tombstone says why.

GroupHalfApplied

Bases: StoreError

A commit already applied part of the group; only a commit finishes it.

IntegrityError

Bases: StoreError

Bytes do not match their name: a landing mismatch or a corrupt object.

LockTimeout

Bases: StoreError

A live lock on the ref was not released within the timeout.

ManifestError

Bases: StoreError

The root manifest is missing, malformed, or of another store.

MissingObject

Bases: StoreError

The named object is not in the store.

NoSuchPending

Bases: StoreError

The named pending publish does not exist: retired, committed, or never begun.

NotAGroup

Bases: StoreError

The pending ref is a single publish's, not a group's.

NotFastForward

Bases: RefConflict

A monotone ref's new target does not descend from its current one.

RefConflict

Bases: StoreError

A compare-and-swap lost: the ref does not name the expected previous digest.

RefProtected

Bases: StoreError

The ref's mutation class does not allow dropping it.

RefTampered

Bases: StoreError

A ref and its record disagree: an out-of-band edit or a torn update.

StoreError

Bases: Exception

The store refused an operation; the message says why.

UnknownNamespace

Bases: StoreError

A ref names a namespace the store was not opened with.

WriteOnceRefused

Bases: RefConflict

A write-once ref already names a different digest.

Subject dataclass

Subject(kind: SubjectKind, value: str)

A subject slot: a person, a call key, a receipt digest, or code.

A version's producer, a ref record's writer and a tombstone's authority are subjects. The slot is shaped so that attested code fits it from the first persisted byte.

Attributes:

Name Type Description
kind SubjectKind

which of the four the subject is.

value str

the subject's identity, its spelling owned by the kind: a person's identifier, a call key, a receipt or code digest as a digest string.

Methods:

Name Description
to_json

The subject as a JSON object.

from_json

Decode a subject, refusing an unknown kind or an empty value.

kind instance-attribute

value instance-attribute

value: str

to_json

to_json() -> dict[str, Value]

The subject as a JSON object.

Source code in packages/strongroom/src/livery/strongroom/_fields.py
def to_json(self) -> dict[str, Value]:
    """The subject as a JSON object."""
    return {"kind": self.kind, "value": self.value}

from_json classmethod

from_json(value: Value, *, where: str) -> Subject

Decode a subject, refusing an unknown kind or an empty value.

Parameters:

Name Type Description Default
value Value

the JSON value to decode.

required
where str

the field being decoded, for the refusal's message.

required

Returns:

Type Description
Subject

The subject.

Raises:

Type Description
FormatError

when the shape or the kind is wrong.

Source code in packages/strongroom/src/livery/strongroom/_fields.py
@classmethod
def from_json(cls, value: Value, *, where: str) -> Subject:
    """Decode a subject, refusing an unknown kind or an empty value.

    Args:
        value: the JSON value to decode.
        where: the field being decoded, for the refusal's message.

    Returns:
        The subject.

    Raises:
        FormatError: when the shape or the kind is wrong.
    """
    fields = expect_object(value, ("kind", "value"), where=where)
    kind = expect_str(fields["kind"], where=f"{where}.kind")
    if kind not in SUBJECT_KINDS:
        known = ", ".join(SUBJECT_KINDS)
        raise FormatError(f"{where}.kind {kind!r} is not one of {known}")
    text = expect_str(fields["value"], where=f"{where}.value")
    if not text:
        raise FormatError(f"{where}.value is empty")
    if kind in ("receipt", "code"):
        Digest.parse(text)
    return cls(kind, text)

Group dataclass

Group(id: str, moves: tuple[Move, ...], applied: int, lease: int, manifest: Digest, record: RefRecord)

A group of moves that has begun and not yet committed.

Attributes:

Name Type Description
id str

the pending ref's name under pending/.

moves tuple[Move, ...]

the moves, in the order they apply.

applied int

how many of them a commit has already applied; more than zero only after a commit stopped part-way.

lease int

the seconds the group expected to take, from begin.

manifest Digest

the tree of every move's target the pending ref names.

record RefRecord

the pending ref's record, the journal in its meta.

id instance-attribute

id: str

moves instance-attribute

moves: tuple[Move, ...]

applied instance-attribute

applied: int

lease instance-attribute

lease: int

manifest instance-attribute

manifest: Digest

record instance-attribute

record: RefRecord

Move dataclass

Move(namespace: str, path: str, digest: Digest, previous: Digest | None, receipt: Digest | None = None, meta: dict[str, Value] = dict())

One ref move of a group.

Attributes:

Name Type Description
namespace str

a declared namespace.

path str

the ref's path.

digest Digest

what the ref names afterwards.

previous Digest | None

what the ref is expected to name now; None to create.

receipt Digest | None

the receipt of the moving call, if any.

meta dict[str, Value]

the consumer's own object for the ref's record.

Methods:

Name Description
to_json

The move as a JSON object, the journal's entry.

from_json

A move from a journal entry.

namespace instance-attribute

namespace: str

path instance-attribute

path: str

digest instance-attribute

digest: Digest

previous instance-attribute

previous: Digest | None

receipt class-attribute instance-attribute

receipt: Digest | None = None

meta class-attribute instance-attribute

meta: dict[str, Value] = field(default_factory=dict)

ref property

ref: str

<namespace>/<path>, the ref's name in a message.

to_json

to_json() -> dict[str, Value]

The move as a JSON object, the journal's entry.

Source code in packages/strongroom/src/livery/strongroom/_groups.py
def to_json(self) -> dict[str, Value]:
    """The move as a JSON object, the journal's entry."""
    return {
        "namespace": self.namespace,
        "path": self.path,
        "digest": str(self.digest),
        "previous": None if self.previous is None else str(self.previous),
        "receipt": None if self.receipt is None else str(self.receipt),
        "meta": dict(self.meta),
    }

from_json classmethod

from_json(value: Value, *, where: str) -> Move

A move from a journal entry.

Raises:

Type Description
FormatError

when the entry is not a move.

Source code in packages/strongroom/src/livery/strongroom/_groups.py
@classmethod
def from_json(cls, value: Value, *, where: str) -> Move:
    """A move from a journal entry.

    Raises:
        FormatError: when the entry is not a move.
    """
    data = expect_object(
        value,
        ("namespace", "path", "digest", "previous", "receipt", "meta"),
        where=where,
    )
    meta = data["meta"]
    if not isinstance(meta, dict):
        raise FormatError(f"{where} meta is not a JSON object")
    return cls(
        expect_str(data["namespace"], where=f"{where} namespace"),
        expect_str(data["path"], where=f"{where} path"),
        expect_digest(data["digest"], where=f"{where} digest"),
        expect_optional_digest(data["previous"], where=f"{where} previous"),
        expect_optional_digest(data["receipt"], where=f"{where} receipt"),
        dict(meta),
    )

Transaction

Transaction(store: Store, *, by: Subject, lease: float)

A group under a with: moves recorded as they come, the exit decides.

Entering begins the group. A clean exit commits it, every move or none, and records then holds the records written. An exception before the commit began retires the group, nothing moved. A commit refused on its checks retires the group too, since nothing moved, and the refusal is what the with raises. A commit that stopped between two applies re-raises and leaves the group for a later livery.strongroom.Store.commit on its id.

Attributes:

Name Type Description
id

the group's pending ref name, known after entry.

records tuple[RefRecord, ...]

the records the commit wrote, in move order; empty until the commit.

Methods:

Name Description
move

Record a move; the group's state after it.

Source code in packages/strongroom/src/livery/strongroom/_groups.py
def __init__(self, store: Store, *, by: Subject, lease: float) -> None:
    self._store = store
    self._by = by
    self._lease = lease
    self.id = ""
    self.records: tuple[RefRecord, ...] = ()

id instance-attribute

id = ''

records instance-attribute

records: tuple[RefRecord, ...] = ()

move

move(namespace: str, path: str, digest: Digest, *, previous: Digest | None, receipt: Digest | None = None, meta: dict[str, Value] | None = None) -> Group

Record a move; the group's state after it.

Source code in packages/strongroom/src/livery/strongroom/_groups.py
def move(
    self,
    namespace: str,
    path: str,
    digest: Digest,
    *,
    previous: Digest | None,
    receipt: Digest | None = None,
    meta: dict[str, Value] | None = None,
) -> Group:
    """Record a move; the group's state after it."""
    return add(
        self._store,
        self.id,
        namespace,
        path,
        digest,
        previous=previous,
        receipt=receipt,
        meta=meta,
    )

Pending dataclass

Pending(id: str, target: Digest, record: RefRecord)

A publish that has begun and not yet committed.

Attributes:

Name Type Description
id str

the pending ref's name under pending/.

target Digest

the tree or version the publish will name.

record RefRecord

the pending ref's record; its meta carries the lease in seconds under lease.

id instance-attribute

id: str

target instance-attribute

target: Digest

record instance-attribute

record: RefRecord

SweepReport dataclass

SweepReport(reached: tuple[Digest, ...] = tuple(), removed: tuple[Digest, ...] = tuple(), scratch_removed: tuple[Path, ...] = tuple(), pending: tuple[str, ...] = tuple())

What a sweep did.

Attributes:

Name Type Description
reached tuple[Digest, ...]

every object marking reached, present or not.

removed tuple[Digest, ...]

every object removed as unreached.

scratch_removed tuple[Path, ...]

every scratch file removed as older than the age bound.

pending tuple[str, ...]

the pending refs found by the re-scan immediately before deleting, every one a root.

reached class-attribute instance-attribute

reached: tuple[Digest, ...] = field(default_factory=tuple)

removed class-attribute instance-attribute

removed: tuple[Digest, ...] = field(default_factory=tuple)

scratch_removed class-attribute instance-attribute

scratch_removed: tuple[Path, ...] = field(default_factory=tuple)

pending class-attribute instance-attribute

pending: tuple[str, ...] = field(default_factory=tuple)

RefRecord dataclass

RefRecord(digest: Digest, previous: Digest | None, by: Subject, at: str, receipt: Digest | None = None, meta: dict[str, Value] = dict())

What a ref update writes beside the ref.

Attributes:

Name Type Description
digest Digest

what the ref names after the update.

previous Digest | None

what it named before, or None on creation.

by Subject

who moved it.

at str

when, as an RFC 3339 UTC instant.

receipt Digest | None

across a trust boundary, the signed receipt of the call that moved the ref; None under local custody.

meta dict[str, Value]

an opaque object a consumer may use, such as validators for a URL or a freshness window for a query. Strongroom stores it and never reads it.

Methods:

Name Description
__post_init__
to_json

The record as a JSON object.

from_json

Decode a record from its JSON value.

encode

The record's canonical JSON bytes.

decode

Decode a record from its stored bytes.

digest instance-attribute

digest: Digest

previous instance-attribute

previous: Digest | None

by instance-attribute

by: Subject

at instance-attribute

at: str

receipt class-attribute instance-attribute

receipt: Digest | None = None

meta class-attribute instance-attribute

meta: dict[str, Value] = field(default_factory=dict)

__post_init__

__post_init__() -> None
Source code in packages/strongroom/src/livery/strongroom/_records.py
def __post_init__(self) -> None:
    check_timestamp(self.at, where="record.at")

to_json

to_json() -> dict[str, Value]

The record as a JSON object.

Source code in packages/strongroom/src/livery/strongroom/_records.py
def to_json(self) -> dict[str, Value]:
    """The record as a JSON object."""
    return {
        "digest": str(self.digest),
        "previous": None if self.previous is None else str(self.previous),
        "by": self.by.to_json(),
        "at": self.at,
        "receipt": None if self.receipt is None else str(self.receipt),
        "meta": self.meta,
    }

from_json classmethod

from_json(value: Value) -> RefRecord

Decode a record from its JSON value.

Parameters:

Name Type Description Default
value Value

the JSON value.

required

Returns:

Type Description
RefRecord

The record.

Raises:

Type Description
FormatError

when the shape or a field is wrong.

Source code in packages/strongroom/src/livery/strongroom/_records.py
@classmethod
def from_json(cls, value: Value) -> RefRecord:
    """Decode a record from its JSON value.

    Args:
        value: the JSON value.

    Returns:
        The record.

    Raises:
        FormatError: when the shape or a field is wrong.
    """
    fields = expect_object(
        value, ("digest", "previous", "by", "at", "receipt", "meta"), where="record"
    )
    meta = fields["meta"]
    if not isinstance(meta, dict):
        raise FormatError("record.meta is not a JSON object")
    return cls(
        digest=expect_digest(fields["digest"], where="record.digest"),
        previous=expect_optional_digest(
            fields["previous"], where="record.previous"
        ),
        by=Subject.from_json(fields["by"], where="record.by"),
        at=expect_str(fields["at"], where="record.at"),
        receipt=expect_optional_digest(fields["receipt"], where="record.receipt"),
        meta=meta,
    )

encode

encode() -> bytes

The record's canonical JSON bytes.

Source code in packages/strongroom/src/livery/strongroom/_records.py
def encode(self) -> bytes:
    """The record's canonical JSON bytes."""
    return canonical(self.to_json())

decode classmethod

decode(data: bytes) -> RefRecord

Decode a record from its stored bytes.

Parameters:

Name Type Description Default
data bytes

the record file's bytes.

required

Returns:

Type Description
RefRecord

The record.

Raises:

Type Description
FormatError

when the bytes are not JSON, not a record, or not canonical.

Source code in packages/strongroom/src/livery/strongroom/_records.py
@classmethod
def decode(cls, data: bytes) -> RefRecord:
    """Decode a record from its stored bytes.

    Args:
        data: the record file's bytes.

    Returns:
        The record.

    Raises:
        FormatError: when the bytes are not JSON, not a record, or
            not canonical.
    """
    return cls.from_json(_loads(data, what="record"))

Tombstone dataclass

Tombstone(digest: Digest, at: str, authority: Subject, receipt: Digest | None, reason: str)

What an erased object becomes, in every tier.

Attributes:

Name Type Description
digest Digest

the erased object's name, which stays valid in every tree that names it.

at str

when, as an RFC 3339 UTC instant.

authority Subject

who erased it.

receipt Digest | None

the receipt of the erasing call, or None under local custody.

reason str

free text, shown to a reader whose view meets the erased entry.

Methods:

Name Description
__post_init__
to_json

The tombstone as a JSON object.

from_json

Decode a tombstone from its JSON value.

encode

The tombstone's canonical JSON bytes.

decode

Decode a tombstone from its stored bytes.

digest instance-attribute

digest: Digest

at instance-attribute

at: str

authority instance-attribute

authority: Subject

receipt instance-attribute

receipt: Digest | None

reason instance-attribute

reason: str

__post_init__

__post_init__() -> None
Source code in packages/strongroom/src/livery/strongroom/_records.py
def __post_init__(self) -> None:
    check_timestamp(self.at, where="tombstone.at")

to_json

to_json() -> dict[str, Value]

The tombstone as a JSON object.

Source code in packages/strongroom/src/livery/strongroom/_records.py
def to_json(self) -> dict[str, Value]:
    """The tombstone as a JSON object."""
    return {
        "digest": str(self.digest),
        "at": self.at,
        "authority": self.authority.to_json(),
        "receipt": None if self.receipt is None else str(self.receipt),
        "reason": self.reason,
    }

from_json classmethod

from_json(value: Value) -> Tombstone

Decode a tombstone from its JSON value.

Parameters:

Name Type Description Default
value Value

the JSON value.

required

Returns:

Type Description
Tombstone

The tombstone.

Raises:

Type Description
FormatError

when the shape or a field is wrong.

Source code in packages/strongroom/src/livery/strongroom/_records.py
@classmethod
def from_json(cls, value: Value) -> Tombstone:
    """Decode a tombstone from its JSON value.

    Args:
        value: the JSON value.

    Returns:
        The tombstone.

    Raises:
        FormatError: when the shape or a field is wrong.
    """
    fields = expect_object(
        value, ("digest", "at", "authority", "receipt", "reason"), where="tombstone"
    )
    return cls(
        digest=expect_digest(fields["digest"], where="tombstone.digest"),
        at=expect_str(fields["at"], where="tombstone.at"),
        authority=Subject.from_json(
            fields["authority"], where="tombstone.authority"
        ),
        receipt=expect_optional_digest(
            fields["receipt"], where="tombstone.receipt"
        ),
        reason=expect_str(fields["reason"], where="tombstone.reason"),
    )

encode

encode() -> bytes

The tombstone's canonical JSON bytes.

Source code in packages/strongroom/src/livery/strongroom/_records.py
def encode(self) -> bytes:
    """The tombstone's canonical JSON bytes."""
    return canonical(self.to_json())

decode classmethod

decode(data: bytes) -> Tombstone

Decode a tombstone from its stored bytes.

Parameters:

Name Type Description Default
data bytes

the tombstone file's bytes.

required

Returns:

Type Description
Tombstone

The tombstone.

Raises:

Type Description
FormatError

when the bytes are not JSON, not a tombstone, or not canonical.

Source code in packages/strongroom/src/livery/strongroom/_records.py
@classmethod
def decode(cls, data: bytes) -> Tombstone:
    """Decode a tombstone from its stored bytes.

    Args:
        data: the tombstone file's bytes.

    Returns:
        The tombstone.

    Raises:
        FormatError: when the bytes are not JSON, not a tombstone,
            or not canonical.
    """
    return cls.from_json(_loads(data, what="tombstone"))

RungUnavailable

Bases: OSError

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

FolderSource dataclass

FolderSource(path: Path, fill: FillPolicy = 'copy')

A folder in the store layout: a mirror, or a read-only share.

Attributes:

Name Type Description
path Path

the folder's root, holding a manifest of the same layout and algorithm as the store that consults it.

fill FillPolicy

copy lands a hit into the local store; reference answers with a path into the folder and lands nothing, for a share where a local copy would be a second copy of everything.

Methods:

Name Description
__post_init__
describe

The source, for a report.

path instance-attribute

path: Path

fill class-attribute instance-attribute

fill: FillPolicy = 'copy'

__post_init__

__post_init__() -> None
Source code in packages/strongroom/src/livery/strongroom/_sources.py
def __post_init__(self) -> None:
    if self.fill not in ("copy", "reference"):
        raise ValueError(f"fill {self.fill!r} is not copy or reference")

describe

describe() -> str

The source, for a report.

Source code in packages/strongroom/src/livery/strongroom/_sources.py
def describe(self) -> str:
    """The source, for a report."""
    return f"folder {self.path} ({self.fill})"

HttpSource dataclass

HttpSource(base_url: str, connect_timeout: float = 3.0, transfer_timeout: float = 60.0)

An HTTP base URL serving the store layout: nginx over a folder.

Attributes:

Name Type Description
base_url str

the URL the layout hangs from; a trailing slash is ignored.

connect_timeout float

seconds to wait for the server to answer at all; an unanswered source is skipped and reported.

transfer_timeout float

seconds a stalled transfer may wait between bytes.

Methods:

Name Description
__post_init__
describe

The source, for a report.

url

The URL of relative, a path in the layout.

base_url instance-attribute

base_url: str

connect_timeout class-attribute instance-attribute

connect_timeout: float = 3.0

transfer_timeout class-attribute instance-attribute

transfer_timeout: float = 60.0

__post_init__

__post_init__() -> None
Source code in packages/strongroom/src/livery/strongroom/_sources.py
def __post_init__(self) -> None:
    _check_url(self.base_url)

describe

describe() -> str

The source, for a report.

Source code in packages/strongroom/src/livery/strongroom/_sources.py
def describe(self) -> str:
    """The source, for a report."""
    return f"http {self.base_url}"

url

url(relative: str) -> str

The URL of relative, a path in the layout.

Source code in packages/strongroom/src/livery/strongroom/_sources.py
def url(self, relative: str) -> str:
    """The URL of *relative*, a path in the layout."""
    return f"{self.base_url.rstrip('/')}/{relative}"

OriginHint dataclass

OriginHint(digest: Digest, url: str, connect_timeout: float = 3.0, transfer_timeout: float = 60.0)

One URL that yields one named object: the ingress form.

A tool spec's {url, sha256} per host is an origin hint, and so is a vendor download. Consulted only for its own digest, and never when the store is offline.

Attributes:

Name Type Description
digest Digest

the object the URL yields.

url str

where to get it.

connect_timeout float

seconds to wait for an answer.

transfer_timeout float

seconds a stalled transfer may wait.

Methods:

Name Description
__post_init__
describe

The source, for a report.

digest instance-attribute

digest: Digest

url instance-attribute

url: str

connect_timeout class-attribute instance-attribute

connect_timeout: float = 3.0

transfer_timeout class-attribute instance-attribute

transfer_timeout: float = 60.0

__post_init__

__post_init__() -> None
Source code in packages/strongroom/src/livery/strongroom/_sources.py
def __post_init__(self) -> None:
    _check_url(self.url)

describe

describe() -> str

The source, for a report.

Source code in packages/strongroom/src/livery/strongroom/_sources.py
def describe(self) -> str:
    """The source, for a report."""
    return f"origin {self.url}"

Unreachable

Unreachable(message: str, *, status: int | None = None)

Bases: Exception

A source did not answer for this object; the fetch skips it and reports.

Attributes:

Name Type Description
status

The HTTP status the source answered with, when the refusal is an answer (a 404, a 503) rather than a connection that failed or a chain that did not end; None otherwise. A caller deciding whether to try again reads it: a connection failure and a 5xx are worth another try, a 404 is not.

Source code in packages/strongroom/src/livery/strongroom/_sources.py
def __init__(self, message: str, *, status: int | None = None) -> None:
    super().__init__(message)
    self.status = status

status instance-attribute

status = status

Landed dataclass

Landed(digest: Digest, size: int, written: bool)

What a landing produced.

Attributes:

Name Type Description
digest Digest

the object's name.

size int

its byte count.

written bool

whether the bytes were written now; false when the object already existed, which is success without a write.

digest instance-attribute

digest: Digest

size instance-attribute

size: int

written instance-attribute

written: bool

Manifest dataclass

Manifest(layout: int, algorithm: str)

The root manifest: which layout and which algorithm this store speaks.

Attributes:

Name Type Description
layout int

the layout version.

algorithm str

the one algorithm of this address space.

Methods:

Name Description
encode

The manifest's canonical JSON bytes.

decode

Decode a manifest, refusing bytes that are not one.

layout instance-attribute

layout: int

algorithm instance-attribute

algorithm: str

encode

encode() -> bytes

The manifest's canonical JSON bytes.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def encode(self) -> bytes:
    """The manifest's canonical JSON bytes."""
    return canonical({"layout": self.layout, "algorithm": self.algorithm})

decode classmethod

decode(data: bytes) -> Manifest

Decode a manifest, refusing bytes that are not one.

Parameters:

Name Type Description Default
data bytes

the manifest file's bytes.

required

Returns:

Type Description
Manifest

The manifest.

Raises:

Type Description
ManifestError

when the bytes are not a manifest.

Source code in packages/strongroom/src/livery/strongroom/_store.py
@classmethod
def decode(cls, data: bytes) -> Manifest:
    """Decode a manifest, refusing bytes that are not one.

    Args:
        data: the manifest file's bytes.

    Returns:
        The manifest.

    Raises:
        ManifestError: when the bytes are not a manifest.
    """
    try:
        value: Value = json.loads(data)
        fields = expect_object(value, ("layout", "algorithm"), where="manifest")
        return cls(
            expect_int(fields["layout"], where="manifest.layout"),
            expect_str(fields["algorithm"], where="manifest.algorithm"),
        )
    except ValueError as error:
        raise ManifestError(f"{MANIFEST_NAME} is not a manifest: {error}") from None

Namespace dataclass

Namespace(name: str, mutation: MutationClass)

A ref namespace and its mutation class.

Attributes:

Name Type Description
name str

the namespace, lowercase letters, digits and dashes.

mutation MutationClass

how its refs may move.

Methods:

Name Description
__post_init__

name instance-attribute

name: str

mutation instance-attribute

mutation: MutationClass

__post_init__

__post_init__() -> None
Source code in packages/strongroom/src/livery/strongroom/_store.py
def __post_init__(self) -> None:
    if not self.name or self.name.strip("abcdefghijklmnopqrstuvwxyz0123456789-"):
        raise ValueError(
            f"namespace {self.name!r} is not lowercase letters, digits and dashes"
        )
    if self.mutation not in MUTATION_CLASSES:
        known = ", ".join(MUTATION_CLASSES)
        raise ValueError(
            f"namespace {self.name!r} mutation {self.mutation!r} is not"
            f" one of {known}"
        )

ScrubReport dataclass

ScrubReport(verified: tuple[Digest, ...] = tuple(), corrupt: tuple[Digest, ...] = tuple())

What a scrub found.

Attributes:

Name Type Description
verified tuple[Digest, ...]

every object whose bytes matched its name.

corrupt tuple[Digest, ...]

every object that did not; each is removed with its mark, so the next fill lands it again.

verified class-attribute instance-attribute

verified: tuple[Digest, ...] = field(default_factory=tuple)

corrupt class-attribute instance-attribute

corrupt: tuple[Digest, ...] = field(default_factory=tuple)

Store

Store(root: Path, algorithm: Algorithm, namespaces: Iterable[Namespace], *, clock: Clock, lock_stale: float, lock_timeout: float, sources: Iterable[Source], offline: bool, progress: Progress)

A local store: objects/ by digest, refs/ by name.

Open one with livery.strongroom.Store.create or livery.strongroom.Store.open. Every namespace a caller will write is declared at open with its mutation class; pins/ and pending/ are declared by the store.

Attributes:

Name Type Description
root Path

the store's directory.

algorithm Algorithm

the address space's algorithm.

namespaces dict[str, Namespace]

every declared namespace by name.

sources tuple[Source, ...]

the sources consulted in order for an object the local directory lacks.

offline bool

whether origin hints are never consulted.

Methods:

Name Description
create

Create a store at root and open it.

open

Open the store at root.

object_path

The path an object of digest lives at, present or not.

state

Whether digest is present, absent, or erased here.

land

Land bytes as an object, verifying them on the way in.

put

Land data and return its name.

path

A read-only path to the object, verified on first access.

read

The object's bytes, through livery.strongroom.Store.path.

verify

Hash the object in full and mark it verified.

verified_size

The size this store verified the object at, or None if never.

objects

Every object present here, in no particular order.

scrub

Hash every object and remove the ones that do not match.

fetch

A path to the object, consulting the sources when it is not here.

fill

Land digests into the folder tier at target.

tombstone

The tombstone under the object's path, or None when there is none.

write_tombstone

Write stone under its object's path, in this tier.

evict

Remove the object's bytes and its marks; the name is untouched.

clock

The current instant, from the clock the store was opened with.

publish_begin

Begin a publish: root target under pending/<id> first.

publish_commit

Commit a publish: move the real ref, then drop the pending one.

retire

Drop a pending ref deliberately, for a publish that will not commit.

pendings

Every pending publish's id, sorted; groups included.

begin

Open a group of ref moves: an empty journal under pending/<id>.

add

Append a move to the group; its manifest roots the target from now on.

commit

Apply the group's moves, every one or none, and drop the pending ref.

group

The group under pending/<group_id>.

groups

Every group that has begun and not committed, sorted by id.

transaction

A group under a with: record moves, and the exit commits or retires.

drop_ref

Remove a volatile ref and its record by compare-and-swap.

pin

Root digest under pins/<name>, replacing an earlier pin of that name.

unpin

Drop pins/<name> under the maintenance lease, never beside a sweep.

erase

Erase the object's bytes and keep the fact as a tombstone.

reachable

Every object reachable from digest, itself included.

roots

Every root: what every ref on disk names, and every live view's tree.

sweep

Remove every object no root reaches, and old scratch.

view

Fill at from the tree by the cheapest safe rung per entry.

views

Every recorded view, live or not, by id.

view_record

The record of one view, or None.

drop_view

Remove what the view's record lists, and nothing else.

collect

Read the declared paths under at back into a tree, landing every object.

prefetch

Fetch digest and everything it reaches, for offline use.

shed

Evict every local copy source holds, except what a live view needs.

head

Whether the HTTP source answers a HEAD for relative.

ref_path

The file a ref lives at, present or not.

ref

What the ref names, or None when it does not exist.

record

The record beside the ref, or None when there is none.

refs

Every ref path in the namespace, sorted.

set_ref

Move a ref by compare-and-swap, writing its record.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def __init__(
    self,
    root: Path,
    algorithm: Algorithm,
    namespaces: Iterable[Namespace],
    *,
    clock: Clock,
    lock_stale: float,
    lock_timeout: float,
    sources: Iterable[Source],
    offline: bool,
    progress: Progress,
) -> None:
    self.root = root
    self.algorithm = algorithm
    self.sources = tuple(sources)
    self.offline = offline
    self._progress = progress
    for source in self.sources:
        if isinstance(source, FolderSource):
            self._check_folder(source)
    self.namespaces = {owned.name: owned for owned in OWNED}
    for namespace in namespaces:
        declared = self.namespaces.get(namespace.name)
        if declared is not None and declared != namespace:
            raise ValueError(
                f"namespace {namespace.name!r} is already declared"
                f" {declared.mutation}, not {namespace.mutation}"
            )
        self.namespaces[namespace.name] = namespace
    self._clock = clock
    self._lock_stale = lock_stale
    self._lock_timeout = lock_timeout
    self._checked_http: set[str] = set()

root instance-attribute

root: Path = root

algorithm instance-attribute

algorithm: Algorithm = algorithm

namespaces instance-attribute

namespaces: dict[str, Namespace] = {owned.name: owned for owned in OWNED}

sources instance-attribute

sources: tuple[Source, ...] = tuple(sources)

offline instance-attribute

offline: bool = offline

create classmethod

create(root: Path, *, algorithm: str = 'sha256', namespaces: Iterable[Namespace] = (), clock: Clock = now, lock_stale: float = 600.0, lock_timeout: float = 30.0, sources: Iterable[Source] = (), offline: bool = False, progress: Progress = silent) -> Store

Create a store at root and open it.

Parameters:

Name Type Description Default
root Path

the directory; created when missing.

required
algorithm str

a registry entry's name.

'sha256'
namespaces Iterable[Namespace]

the caller's namespaces, each with its class.

()
clock Clock

the instant source for records.

now
lock_stale float

seconds after which a lock is broken even when its holder looks alive: the pid of a holder that died can belong to another process by then.

600.0
lock_timeout float

seconds to wait for a live lock.

30.0
sources Iterable[Source]

where to look for an object the store lacks, in order. A folder source is checked now; an HTTP source on first use.

()
offline bool

never consult an origin hint.

False
progress Progress

where a fetch reports a skipped or refused source; silent by default.

silent

Returns:

Type Description
Store

The open store.

Raises:

Type Description
ManifestError

when root already holds a manifest.

FormatError

when the algorithm is not registered.

Source code in packages/strongroom/src/livery/strongroom/_store.py
@classmethod
def create(
    cls,
    root: Path,
    *,
    algorithm: str = "sha256",
    namespaces: Iterable[Namespace] = (),
    clock: Clock = now,
    lock_stale: float = 600.0,
    lock_timeout: float = 30.0,
    sources: Iterable[Source] = (),
    offline: bool = False,
    progress: Progress = silent,
) -> Store:
    """Create a store at *root* and open it.

    Args:
        root: the directory; created when missing.
        algorithm: a registry entry's name.
        namespaces: the caller's namespaces, each with its class.
        clock: the instant source for records.
        lock_stale: seconds after which a lock is broken even when
            its holder looks alive: the pid of a holder that died
            can belong to another process by then.
        lock_timeout: seconds to wait for a live lock.
        sources: where to look for an object the store lacks, in
            order. A folder source is checked now; an HTTP source
            on first use.
        offline: never consult an origin hint.
        progress: where a fetch reports a skipped or refused
            source; silent by default.

    Returns:
        The open store.

    Raises:
        ManifestError: when *root* already holds a manifest.
        FormatError: when the algorithm is not registered.
    """
    entry = registered(algorithm)
    root.mkdir(parents=True, exist_ok=True)
    manifest = root / MANIFEST_NAME
    if manifest.exists():
        raise ManifestError(f"{root} is already a store: {MANIFEST_NAME} exists")
    _write_atomically(manifest, Manifest(LAYOUT_VERSION, entry.name).encode())
    for child in ("objects", "refs", "index"):
        (root / child).mkdir(exist_ok=True)
    return cls.open(
        root,
        namespaces=namespaces,
        clock=clock,
        lock_stale=lock_stale,
        lock_timeout=lock_timeout,
        sources=sources,
        offline=offline,
        progress=progress,
    )

open classmethod

open(root: Path, *, namespaces: Iterable[Namespace] = (), clock: Clock = now, lock_stale: float = 600.0, lock_timeout: float = 30.0, sources: Iterable[Source] = (), offline: bool = False, progress: Progress = silent) -> Store

Open the store at root.

Parameters:

Name Type Description Default
root Path

the store's directory.

required
namespaces Iterable[Namespace]

the caller's namespaces, each with its class.

()
clock Clock

the instant source for records.

now
lock_stale float

seconds after which a lock is broken even when its holder looks alive: the pid of a holder that died can belong to another process by then.

600.0
lock_timeout float

seconds to wait for a live lock.

30.0
sources Iterable[Source]

where to look for an object the store lacks, in order. A folder source is checked now; an HTTP source on first use.

()
offline bool

never consult an origin hint.

False
progress Progress

where a fetch reports a skipped or refused source; silent by default.

silent

Returns:

Type Description
Store

The store.

Raises:

Type Description
ManifestError

when the manifest is missing or malformed, or names a layout or an algorithm this implementation does not speak; or when a folder source's manifest is missing or of another store.

ValueError

when a namespace is declared twice with different classes.

Source code in packages/strongroom/src/livery/strongroom/_store.py
@classmethod
def open(
    cls,
    root: Path,
    *,
    namespaces: Iterable[Namespace] = (),
    clock: Clock = now,
    lock_stale: float = 600.0,
    lock_timeout: float = 30.0,
    sources: Iterable[Source] = (),
    offline: bool = False,
    progress: Progress = silent,
) -> Store:
    """Open the store at *root*.

    Args:
        root: the store's directory.
        namespaces: the caller's namespaces, each with its class.
        clock: the instant source for records.
        lock_stale: seconds after which a lock is broken even when
            its holder looks alive: the pid of a holder that died
            can belong to another process by then.
        lock_timeout: seconds to wait for a live lock.
        sources: where to look for an object the store lacks, in
            order. A folder source is checked now; an HTTP source
            on first use.
        offline: never consult an origin hint.
        progress: where a fetch reports a skipped or refused
            source; silent by default.

    Returns:
        The store.

    Raises:
        ManifestError: when the manifest is missing or malformed,
            or names a layout or an algorithm this implementation
            does not speak; or when a folder source's manifest is
            missing or of another store.
        ValueError: when a namespace is declared twice with
            different classes.
    """
    path = root / MANIFEST_NAME
    try:
        manifest = Manifest.decode(path.read_bytes())
    except FileNotFoundError:
        raise ManifestError(f"{root} is not a store: no {MANIFEST_NAME}") from None
    if manifest.layout != LAYOUT_VERSION:
        raise ManifestError(
            f"{root} is layout {manifest.layout}; this implementation"
            f" speaks layout {LAYOUT_VERSION}"
        )
    try:
        entry = registered(manifest.algorithm)
    except FormatError as error:
        raise ManifestError(f"{root}: {error}") from None
    return cls(
        root,
        entry,
        namespaces,
        clock=clock,
        lock_stale=lock_stale,
        lock_timeout=lock_timeout,
        sources=sources,
        offline=offline,
        progress=progress,
    )

object_path

object_path(digest: Digest) -> Path

The path an object of digest lives at, present or not.

Raises:

Type Description
IntegrityError

when the digest is of another algorithm than this store's; one address space, one algorithm.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def object_path(self, digest: Digest) -> Path:
    """The path an object of *digest* lives at, present or not.

    Raises:
        IntegrityError: when the digest is of another algorithm
            than this store's; one address space, one algorithm.
    """
    if digest.algorithm != self.algorithm.name:
        raise IntegrityError(
            f"{digest} is a {digest.algorithm} name; this store's"
            f" address space is {self.algorithm.name}"
        )
    algorithm, fanout, rest = digest.path_parts
    return self.root / "objects" / algorithm / fanout / rest

state

state(digest: Digest) -> ObjectState

Whether digest is present, absent, or erased here.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def state(self, digest: Digest) -> ObjectState:
    """Whether *digest* is present, absent, or erased here."""
    path = self.object_path(digest)
    if path.with_name(path.name + _TOMBSTONE).exists():
        return "erased"
    if path.exists():
        return "present"
    return "absent"

land

land(source: IO[bytes] | bytes, *, expected: Digest | None = None) -> Landed

Land bytes as an object, verifying them on the way in.

The bytes stream through the digest into a .part scratch file and are moved into place atomically. Landing is idempotent: an object that already exists is success without a write. Two writers of the same digest land identical bytes, so no lock is taken.

Parameters:

Name Type Description Default
source IO[bytes] | bytes

the bytes, or a binary stream read to its end.

required
expected Digest | None

the digest the bytes must have, when known. A mismatch removes the scratch and raises.

None

Returns:

Type Description
Landed

The landing.

Raises:

Type Description
IntegrityError

when expected is given and the bytes do not match it.

ErasedObject

when the object was erased here; its tombstone stands until a sweep decides otherwise.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def land(
    self, source: IO[bytes] | bytes, *, expected: Digest | None = None
) -> Landed:
    """Land bytes as an object, verifying them on the way in.

    The bytes stream through the digest into a `.part` scratch file
    and are moved into place atomically. Landing is idempotent: an
    object that already exists is success without a write. Two
    writers of the same digest land identical bytes, so no lock is
    taken.

    Args:
        source: the bytes, or a binary stream read to its end.
        expected: the digest the bytes must have, when known. A
            mismatch removes the scratch and raises.

    Returns:
        The landing.

    Raises:
        IntegrityError: when *expected* is given and the bytes do
            not match it.
        ErasedObject: when the object was erased here; its
            tombstone stands until a sweep decides otherwise.
    """
    stream = BytesIO(source) if isinstance(source, bytes) else source
    if expected is not None:
        destination = self.object_path(expected)
        scratch = _scratch_beside(destination)
    else:
        scratch = _scratch_beside(
            self.root / "objects" / self.algorithm.name / "incoming"
        )
    scratch.parent.mkdir(parents=True, exist_ok=True)
    hasher = self.algorithm.constructor(b"")
    size = 0
    with scratch.open("wb") as handle:
        while chunk := stream.read(_CHUNK):
            hasher.update(chunk)
            size += len(chunk)
            handle.write(chunk)
    digest = Digest(self.algorithm.name, hasher.hexdigest())
    if expected is not None and digest != expected:
        scratch.unlink()
        raise IntegrityError(
            f"landing expected {expected} and the bytes are {digest};"
            " nothing was kept"
        )
    destination = self.object_path(digest)
    state = self.state(digest)
    if state == "erased":
        scratch.unlink()
        raise self._erased(digest)
    if state == "present":
        scratch.unlink()
        return Landed(digest, size, written=False)
    destination.parent.mkdir(parents=True, exist_ok=True)
    try:
        _replace(scratch, destination)
    except PermissionError:
        # Another process holds the destination (Windows): a reader,
        # or the twin landing the same bytes, still placing them.
        # The bytes are the same by name, so the landing succeeded
        # once the destination verifies; the wait is for the twin
        # to finish, and a destination that never verifies keeps
        # the refusal.
        scratch.unlink()
        if not _settled(
            lambda: destination.exists() and self._hash_file(destination) == digest
        ):
            raise
        self._write_mark(digest, size)
        return Landed(digest, size, written=False)
    self._write_mark(digest, size)
    return Landed(digest, size, written=True)

put

put(data: bytes) -> Digest

Land data and return its name.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def put(self, data: bytes) -> Digest:
    """Land *data* and return its name."""
    return self.land(data).digest

path

path(digest: Digest) -> Path

A read-only path to the object, verified on first access.

Size is checked against the verified mark on every access; an object without a mark (landed by copy, not by this store) is hashed in full and marked.

Raises:

Type Description
MissingObject

when the object is absent.

ErasedObject

when the object was erased.

IntegrityError

when the bytes do not match the name; the object and its mark are removed so a fill lands it again.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def path(self, digest: Digest) -> Path:
    """A read-only path to the object, verified on first access.

    Size is checked against the verified mark on every access; an
    object without a mark (landed by copy, not by this store) is
    hashed in full and marked.

    Raises:
        MissingObject: when the object is absent.
        ErasedObject: when the object was erased.
        IntegrityError: when the bytes do not match the name; the
            object and its mark are removed so a fill lands it
            again.
    """
    state = self.state(digest)
    path = self.object_path(digest)
    if state == "erased":
        raise self._erased(digest)
    if state == "absent":
        raise MissingObject(f"{digest} is not in the store at {self.root}")
    size = self.verified_size(digest)
    if size is None:
        self.verify(digest)
    else:
        actual = path.stat().st_size
        if actual != size:
            self.evict(digest)
            raise IntegrityError(
                f"{digest} is {actual} bytes on disk and was verified at"
                f" {size}; the object is removed"
            )
    return path

read

read(digest: Digest) -> bytes

The object's bytes, through livery.strongroom.Store.path.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def read(self, digest: Digest) -> bytes:
    """The object's bytes, through [livery.strongroom.Store.path][]."""
    return self.path(digest).read_bytes()

verify

verify(digest: Digest) -> int

Hash the object in full and mark it verified.

Returns:

Type Description
int

The object's size.

Raises:

Type Description
MissingObject

when the object is absent.

IntegrityError

when the bytes do not match; the object and its mark are removed.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def verify(self, digest: Digest) -> int:
    """Hash the object in full and mark it verified.

    Returns:
        The object's size.

    Raises:
        MissingObject: when the object is absent.
        IntegrityError: when the bytes do not match; the object and
            its mark are removed.
    """
    path = self.object_path(digest)
    if not path.exists():
        raise MissingObject(f"{digest} is not in the store at {self.root}")
    actual = self._hash_file(path)
    if actual != digest:
        self.evict(digest)
        raise IntegrityError(
            f"{digest} holds bytes named {actual}; the object is removed"
        )
    size = path.stat().st_size
    self._write_mark(digest, size)
    return size

verified_size

verified_size(digest: Digest) -> int | None

The size this store verified the object at, or None if never.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def verified_size(self, digest: Digest) -> int | None:
    """The size this store verified the object at, or None if never."""
    try:
        return int(self._mark(digest).read_text("ascii"))
    except FileNotFoundError:
        return None

objects

objects() -> Iterator[Digest]

Every object present here, in no particular order.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def objects(self) -> Iterator[Digest]:
    """Every object present here, in no particular order."""
    objects = self.root / "objects" / self.algorithm.name
    for fanout in sorted(objects.glob("??")):
        for path in sorted(fanout.iterdir()):
            if path.name.endswith(_RESERVED_SUFFIXES):
                continue
            yield Digest(self.algorithm.name, fanout.name + path.name)

scrub

scrub() -> ScrubReport

Hash every object and remove the ones that do not match.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def scrub(self) -> ScrubReport:
    """Hash every object and remove the ones that do not match."""
    verified: list[Digest] = []
    corrupt: list[Digest] = []
    for digest in list(self.objects()):
        try:
            self.verify(digest)
        except IntegrityError:
            corrupt.append(digest)
        else:
            verified.append(digest)
    return ScrubReport(tuple(verified), tuple(corrupt))

fetch

fetch(digest: Digest) -> Path

A path to the object, consulting the sources when it is not here.

Sources are consulted in order. A hit is verified on arrival: a copy-policy folder, an HTTP tier and an origin hint land the bytes here; a reference-policy folder answers with a path into the folder and lands nothing. An unreachable source is skipped and reported; a source serving wrong bytes is refused and reported, and the next one consulted. An origin hint is consulted only for its own digest and never when offline.

Returns:

Type Description
Path

A read-only path: this store's object, or the folder's

Path

under a reference policy.

Raises:

Type Description
MissingObject

when no source has it. The message names the digest, and when an origin hint was passed over because the store is offline, the URL that would have satisfied it.

ErasedObject

when the object was erased here.

ManifestError

when an HTTP source's manifest is of another store.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def fetch(self, digest: Digest) -> Path:
    """A path to the object, consulting the sources when it is not here.

    Sources are consulted in order. A hit is verified on arrival:
    a copy-policy folder, an HTTP tier and an origin hint land the
    bytes here; a reference-policy folder answers with a path into
    the folder and lands nothing. An unreachable source is skipped
    and reported; a source serving wrong bytes is refused and
    reported, and the next one consulted. An origin hint is
    consulted only for its own digest and never when offline.

    Returns:
        A read-only path: this store's object, or the folder's
        under a reference policy.

    Raises:
        MissingObject: when no source has it. The message names
            the digest, and when an origin hint was passed over
            because the store is offline, the URL that would have
            satisfied it.
        ErasedObject: when the object was erased here.
        ManifestError: when an HTTP source's manifest is of
            another store.
    """
    state = self.state(digest)
    if state == "erased":
        raise self._erased(digest)
    if state == "present":
        return self.path(digest)
    passed_over: OriginHint | None = None
    for source in self.sources:
        if isinstance(source, OriginHint):
            if source.digest != digest:
                continue
            if self.offline:
                passed_over = source
                continue
        try:
            found = self._fetch_from(source, digest)
        except Unreachable as error:
            self._progress(f"skipped {source.describe()}: {error}")
            continue
        except IntegrityError as error:
            self._progress(f"refused {source.describe()}: {error}")
            continue
        if found is not None:
            return found
    offline = (
        ""
        if passed_over is None
        else (
            f"; the store is offline and {passed_over.url} would have satisfied it"
        )
    )
    raise MissingObject(
        f"{digest} is not in the store at {self.root} nor at any of its"
        f" {len(self.sources)} source(s){offline}"
    )

fill

fill(target: Path, digests: Iterable[Digest]) -> list[Landed]

Land digests into the folder tier at target.

The folder becomes a store of this store's algorithm when it is not one already, and afterwards opens as a livery.strongroom.FolderSource that serves every filled digest. Each object is fetched through this store's sources.

Parameters:

Name Type Description Default
target Path

the folder; created when missing.

required
digests Iterable[Digest]

the objects to land there.

required

Returns:

Type Description
list[Landed]

One landing per digest, in order.

Raises:

Type Description
ManifestError

when target is a store of another layout or algorithm.

MissingObject

when a digest is not obtainable.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def fill(self, target: Path, digests: Iterable[Digest]) -> list[Landed]:
    """Land *digests* into the folder tier at *target*.

    The folder becomes a store of this store's algorithm when it is
    not one already, and afterwards opens as a
    [livery.strongroom.FolderSource][] that serves every filled
    digest. Each object is fetched through this store's sources.

    Args:
        target: the folder; created when missing.
        digests: the objects to land there.

    Returns:
        One landing per digest, in order.

    Raises:
        ManifestError: when *target* is a store of another layout
            or algorithm.
        MissingObject: when a digest is not obtainable.
    """
    if (target / MANIFEST_NAME).exists():
        mirror = Store.open(target)
    else:
        mirror = Store.create(target, algorithm=self.algorithm.name)
    if mirror.algorithm != self.algorithm:
        raise ManifestError(
            f"{target} is a {mirror.algorithm.name} store; this store is"
            f" {self.algorithm.name}"
        )
    landed: list[Landed] = []
    for digest in digests:
        with self.fetch(digest).open("rb") as handle:
            landed.append(mirror.land(handle, expected=digest))
    return landed

tombstone

tombstone(digest: Digest) -> Tombstone | None

The tombstone under the object's path, or None when there is none.

Raises:

Type Description
IntegrityError

when the file under the tombstone's name is not a tombstone.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def tombstone(self, digest: Digest) -> Tombstone | None:
    """The tombstone under the object's path, or None when there is none.

    Raises:
        IntegrityError: when the file under the tombstone's name is
            not a tombstone.
    """
    path = self.object_path(digest)
    try:
        data = path.with_name(path.name + _TOMBSTONE).read_bytes()
    except FileNotFoundError:
        return None
    try:
        return Tombstone.decode(data)
    except FormatError as error:
        raise IntegrityError(f"tombstone of {digest}: {error}") from None

write_tombstone

write_tombstone(stone: Tombstone) -> None

Write stone under its object's path, in this tier.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def write_tombstone(self, stone: Tombstone) -> None:
    """Write *stone* under its object's path, in this tier."""
    path = self.object_path(stone.digest)
    path.parent.mkdir(parents=True, exist_ok=True)
    _write_atomically(path.with_name(path.name + _TOMBSTONE), stone.encode())

evict

evict(digest: Digest) -> None

Remove the object's bytes and its marks; the name is untouched.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def evict(self, digest: Digest) -> None:
    """Remove the object's bytes and its marks; the name is untouched."""
    rungs.remove(self.object_path(digest))
    self._mark(digest).unlink(missing_ok=True)
    self._reference_mark(digest).unlink(missing_ok=True)

clock

clock() -> str

The current instant, from the clock the store was opened with.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def clock(self) -> str:
    """The current instant, from the clock the store was opened with."""
    return self._clock()

publish_begin

publish_begin(target: Digest, *, by: Subject, lease: float = 3600.0) -> Pending

Begin a publish: root target under pending/<id> first.

The pending ref is a root while it exists, so a sweep during the publish keeps every object the target names. Nothing removes a pending ref on a clock; a crashed publish is retired deliberately with livery.strongroom.Store.retire.

Parameters:

Name Type Description Default
target Digest

the tree or version to publish; present here.

required
by Subject

who publishes.

required
lease float

seconds the publish expects to take; recorded in the pending ref's record for whoever retires it.

3600.0

Returns:

Type Description
Pending

The pending publish.

Raises:

Type Description
MissingObject

when target is not present here.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def publish_begin(
    self, target: Digest, *, by: Subject, lease: float = 3600.0
) -> Pending:
    """Begin a publish: root *target* under `pending/<id>` first.

    The pending ref is a root while it exists, so a sweep during the
    publish keeps every object the target names. Nothing removes a
    pending ref on a clock; a crashed publish is retired
    deliberately with [livery.strongroom.Store.retire][].

    Args:
        target: the tree or version to publish; present here.
        by: who publishes.
        lease: seconds the publish expects to take; recorded in the
            pending ref's record for whoever retires it.

    Returns:
        The pending publish.

    Raises:
        MissingObject: when *target* is not present here.
    """
    return publish_begin(self, target, by=by, lease=lease)

publish_commit

publish_commit(pending_id: str, namespace: str, path: str, *, previous: Digest | None, by: Subject, receipt: Digest | None = None, meta: dict[str, Value] | None = None) -> RefRecord

Commit a publish: move the real ref, then drop the pending one.

The move obeys the namespace's mutation class exactly as livery.strongroom.Store.set_ref does.

Raises:

Type Description
NoSuchPending

when pending/<pending_id> does not exist.

RefConflict

when the real ref does not name previous, or its class refuses the move.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def publish_commit(
    self,
    pending_id: str,
    namespace: str,
    path: str,
    *,
    previous: Digest | None,
    by: Subject,
    receipt: Digest | None = None,
    meta: dict[str, Value] | None = None,
) -> RefRecord:
    """Commit a publish: move the real ref, then drop the pending one.

    The move obeys the namespace's mutation class exactly as
    [livery.strongroom.Store.set_ref][] does.

    Raises:
        NoSuchPending: when `pending/<pending_id>` does not exist.
        RefConflict: when the real ref does not name *previous*, or
            its class refuses the move.
    """
    return publish_commit(
        self,
        pending_id,
        namespace,
        path,
        previous=previous,
        by=by,
        receipt=receipt,
        meta=meta,
    )

retire

retire(pending_id: str) -> Digest

Drop a pending ref deliberately, for a publish that will not commit.

Returns:

Type Description
Digest

What the pending ref named.

Raises:

Type Description
NoSuchPending

when it does not exist.

GroupHalfApplied

when it is a group a commit already applied part of; only a commit finishes it.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def retire(self, pending_id: str) -> Digest:
    """Drop a pending ref deliberately, for a publish that will not commit.

    Returns:
        What the pending ref named.

    Raises:
        NoSuchPending: when it does not exist.
        GroupHalfApplied: when it is a group a commit already
            applied part of; only a commit finishes it.
    """
    record = self.record(PENDING, pending_id)
    if record is not None:
        groups.refuse_half_applied(self, pending_id, record)
    return retire(self, pending_id)

pendings

pendings() -> list[str]

Every pending publish's id, sorted; groups included.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def pendings(self) -> list[str]:
    """Every pending publish's id, sorted; groups included."""
    return self.refs(PENDING)

begin

begin(*, by: Subject, lease: float = 3600.0) -> Group

Open a group of ref moves: an empty journal under pending/<id>.

Parameters:

Name Type Description Default
by Subject

who moves the refs.

required
lease float

seconds the group expects to take; recorded for whoever retires it.

3600.0
Source code in packages/strongroom/src/livery/strongroom/_store.py
def begin(self, *, by: Subject, lease: float = 3600.0) -> Group:
    """Open a group of ref moves: an empty journal under `pending/<id>`.

    Args:
        by: who moves the refs.
        lease: seconds the group expects to take; recorded for
            whoever retires it.
    """
    return groups.begin(self, by=by, lease=lease)

add

add(group_id: str, namespace: str, path: str, digest: Digest, *, previous: Digest | None, receipt: Digest | None = None, meta: dict[str, Value] | None = None) -> Group

Append a move to the group; its manifest roots the target from now on.

The arguments are livery.strongroom.Store.set_ref's. The move is checked at commit, not here; only the target's presence is required now.

Raises:

Type Description
NoSuchPending

when the group does not exist.

NotAGroup

when pending/<group_id> is a single publish's.

GroupHalfApplied

when a commit already applied part of it.

MissingObject

when digest is not present here.

RefConflict

when the group already moves that ref.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def add(
    self,
    group_id: str,
    namespace: str,
    path: str,
    digest: Digest,
    *,
    previous: Digest | None,
    receipt: Digest | None = None,
    meta: dict[str, Value] | None = None,
) -> Group:
    """Append a move to the group; its manifest roots the target from now on.

    The arguments are [livery.strongroom.Store.set_ref][]'s. The
    move is checked at commit, not here; only the target's
    presence is required now.

    Raises:
        NoSuchPending: when the group does not exist.
        NotAGroup: when `pending/<group_id>` is a single publish's.
        GroupHalfApplied: when a commit already applied part of it.
        MissingObject: when *digest* is not present here.
        RefConflict: when the group already moves that ref.
    """
    return groups.add(
        self,
        group_id,
        namespace,
        path,
        digest,
        previous=previous,
        receipt=receipt,
        meta=meta,
    )

commit

commit(group_id: str, *, by: Subject) -> tuple[RefRecord, ...]

Apply the group's moves, every one or none, and drop the pending ref.

Holds the maintenance lease and the moved refs' locks for the checks and the moves only. A commit that stopped between two applies is finished by calling this again with the same id.

Returns:

Type Description
tuple[RefRecord, ...]

One record per move, in order.

Raises:

Type Description
NoSuchPending

when the group does not exist.

NotAGroup

when pending/<group_id> is a single publish's.

RefConflict

when a ref does not name its expected previous or its class refuses the move; nothing moved.

LockTimeout

when the lease or a lock outlasts the timeout.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def commit(self, group_id: str, *, by: Subject) -> tuple[RefRecord, ...]:
    """Apply the group's moves, every one or none, and drop the pending ref.

    Holds the maintenance lease and the moved refs' locks for the
    checks and the moves only. A commit that stopped between two
    applies is finished by calling this again with the same id.

    Returns:
        One record per move, in order.

    Raises:
        NoSuchPending: when the group does not exist.
        NotAGroup: when `pending/<group_id>` is a single publish's.
        RefConflict: when a ref does not name its expected
            previous or its class refuses the move; nothing moved.
        LockTimeout: when the lease or a lock outlasts the timeout.
    """
    return groups.commit(self, group_id, by=by)

group

group(group_id: str) -> Group

The group under pending/<group_id>.

Raises:

Type Description
NoSuchPending

when it does not exist.

NotAGroup

when it is a single publish's.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def group(self, group_id: str) -> Group:
    """The group under `pending/<group_id>`.

    Raises:
        NoSuchPending: when it does not exist.
        NotAGroup: when it is a single publish's.
    """
    return groups.read_group(self, group_id)

groups

groups() -> list[Group]

Every group that has begun and not committed, sorted by id.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def groups(self) -> list[Group]:
    """Every group that has begun and not committed, sorted by id."""
    return groups.groups(self)

transaction

transaction(*, by: Subject, lease: float = 3600.0) -> AbstractContextManager[Transaction]

A group under a with: record moves, and the exit commits or retires.

with store.transaction(by=me) as tx:
    tx.move("tools", "bun@1.3", tree, previous=None)
    tx.move("datasets", "corpus/main", version, previous=v1)
records = tx.records

See livery.strongroom.Transaction for what each exit does.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def transaction(
    self, *, by: Subject, lease: float = 3600.0
) -> contextlib.AbstractContextManager[Transaction]:
    """A group under a `with`: record moves, and the exit commits or retires.

    ```python
    with store.transaction(by=me) as tx:
        tx.move("tools", "bun@1.3", tree, previous=None)
        tx.move("datasets", "corpus/main", version, previous=v1)
    records = tx.records
    ```

    See [livery.strongroom.Transaction][] for what each exit does.
    """
    return groups.transaction(self, by=by, lease=lease)

drop_ref

drop_ref(namespace: str, path: str, *, previous: Digest) -> None

Remove a volatile ref and its record by compare-and-swap.

Raises:

Type Description
RefProtected

when the namespace is write-once or monotone.

RefConflict

when the ref does not name previous.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def drop_ref(self, namespace: str, path: str, *, previous: Digest) -> None:
    """Remove a volatile ref and its record by compare-and-swap.

    Raises:
        RefProtected: when the namespace is write-once or monotone.
        RefConflict: when the ref does not name *previous*.
    """
    drop_ref(self, namespace, path, previous=previous)

pin

pin(name: str, digest: Digest, *, by: Subject) -> RefRecord

Root digest under pins/<name>, replacing an earlier pin of that name.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def pin(self, name: str, digest: Digest, *, by: Subject) -> RefRecord:
    """Root *digest* under `pins/<name>`, replacing an earlier pin of that name."""
    return pin(self, name, digest, by=by)

unpin

unpin(name: str) -> Digest

Drop pins/<name> under the maintenance lease, never beside a sweep.

Returns:

Type Description
Digest

What the pin named.

Raises:

Type Description
RefConflict

when the pin does not exist.

LockTimeout

when a sweep holds the lease past the timeout.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def unpin(self, name: str) -> Digest:
    """Drop `pins/<name>` under the maintenance lease, never beside a sweep.

    Returns:
        What the pin named.

    Raises:
        RefConflict: when the pin does not exist.
        LockTimeout: when a sweep holds the lease past the timeout.
    """
    return unpin(self, name)

erase

erase(digest: Digest, *, by: Subject, reason: str, receipt: Digest | None = None) -> Tombstone

Erase the object's bytes and keep the fact as a tombstone.

The name stays valid in every tree that carries it; a path to the object raises naming this tombstone's reason; landing the bytes again is refused while the tombstone stands. An absent object may be erased too, which refuses its future landing.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def erase(
    self, digest: Digest, *, by: Subject, reason: str, receipt: Digest | None = None
) -> Tombstone:
    """Erase the object's bytes and keep the fact as a tombstone.

    The name stays valid in every tree that carries it; a path to
    the object raises naming this tombstone's reason; landing the
    bytes again is refused while the tombstone stands. An absent
    object may be erased too, which refuses its future landing.
    """
    return erase(self, digest, by=by, reason=reason, receipt=receipt)

reachable

reachable(digest: Digest) -> Iterator[Digest]

Every object reachable from digest, itself included.

Structured formats are read by shape, never by namespace: a version yields its tree, parents, receipt and attachments, a tree its entries, anything else nothing. An absent or erased digest is yielded and not walked.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def reachable(self, digest: Digest) -> Iterator[Digest]:
    """Every object reachable from *digest*, itself included.

    Structured formats are read by shape, never by namespace: a
    version yields its tree, parents, receipt and attachments, a
    tree its entries, anything else nothing. An absent or erased
    digest is yielded and not walked.
    """
    return reachable_from(self, digest)

roots

roots() -> list[Digest]

Every root: what every ref on disk names, and every live view's tree.

Namespaces are read from disk, not from the declaration at open, so a consumer's refs root its objects whoever opened the store. A ref file that is not a digest roots nothing. A view whose directory is gone is retired here rather than rooted.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def roots(self) -> list[Digest]:
    """Every root: what every ref on disk names, and every live view's tree.

    Namespaces are read from disk, not from the declaration at
    open, so a consumer's refs root its objects whoever opened the
    store. A ref file that is not a digest roots nothing. A view
    whose directory is gone is retired here rather than rooted.
    """
    found: list[Digest] = live_roots(self)
    base = self.root / "refs"
    for path in sorted(base.rglob("*")):
        if not path.is_file() or path.name.endswith(_RESERVED_SUFFIXES):
            continue
        try:
            found.append(Digest.parse(path.read_text("ascii").strip()))
        except (FormatError, UnicodeDecodeError):
            continue
    return found

sweep

sweep(*, scratch_age: float = 86400.0) -> SweepReport

Remove every object no root reaches, and old scratch.

Runs under the maintenance lease. Pending refs are read again immediately before deleting, so a publish that began during the sweep roots its objects. Tombstones are never removed.

Parameters:

Name Type Description Default
scratch_age float

seconds after which an orphaned .part file is removed; the one age rule.

86400.0

Returns:

Type Description
SweepReport

The report.

Raises:

Type Description
LockTimeout

when another maintenance holds the lease past the timeout.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def sweep(self, *, scratch_age: float = 86400.0) -> SweepReport:
    """Remove every object no root reaches, and old scratch.

    Runs under the maintenance lease. Pending refs are read again
    immediately before deleting, so a publish that began during the
    sweep roots its objects. Tombstones are never removed.

    Args:
        scratch_age: seconds after which an orphaned `.part` file
            is removed; the one age rule.

    Returns:
        The report.

    Raises:
        LockTimeout: when another maintenance holds the lease past
            the timeout.
    """
    return sweep(self, scratch_age=scratch_age, hook=lifecycle.after_mark)

view

view(tree: Digest, at: Path, *, writable: bool = False, allow_hardlink: bool = False) -> ViewRecord

Fill at from the tree by the cheapest safe rung per entry.

The ladder is clone, hardlink, link, copy; a rung that refuses once is not tried again for this view. A hardlink is refused into a writable view unless allow_hardlink says the view's consumers never write in place; a link is refused from a writable view. An executable entry never shares an inode or a target's mode. A symlink entry becomes a real symlink where the platform allows, the within-view target's content as a marked copy where it does not, and a parked refusal when the target escapes the view. Blobs are fetched through the sources.

Parameters:

Name Type Description Default
tree Digest

the tree to present; fetched if absent here.

required
at Path

the directory to fill; missing or empty.

required
writable bool

whether the caller will write in the view.

False
allow_hardlink bool

allow hardlinks into a writable view.

False

Returns:

Type Description
ViewRecord

The record, listing every path and its rung. The view is a

ViewRecord

root while its directory exists.

Raises:

Type Description
FileExistsError

when at exists and is not an empty directory.

MissingObject

when a blob is obtainable from no source, naming the entry's path.

ErasedObject

when a blob was erased, naming the entry's path and the tombstone's reason.

FormatError

when a path in the tree is over the budget.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def view(
    self,
    tree: Digest,
    at: Path,
    *,
    writable: bool = False,
    allow_hardlink: bool = False,
) -> ViewRecord:
    """Fill *at* from the tree by the cheapest safe rung per entry.

    The ladder is clone, hardlink, link, copy; a rung that refuses
    once is not tried again for this view. A hardlink is refused
    into a writable view unless *allow_hardlink* says the view's
    consumers never write in place; a link is refused from a
    writable view. An executable entry never shares an inode or a
    target's mode. A symlink entry becomes a real symlink where the
    platform allows, the within-view target's content as a marked
    copy where it does not, and a parked refusal when the target
    escapes the view. Blobs are fetched through the sources.

    Args:
        tree: the tree to present; fetched if absent here.
        at: the directory to fill; missing or empty.
        writable: whether the caller will write in the view.
        allow_hardlink: allow hardlinks into a writable view.

    Returns:
        The record, listing every path and its rung. The view is a
        root while its directory exists.

    Raises:
        FileExistsError: when *at* exists and is not an empty
            directory.
        MissingObject: when a blob is obtainable from no source,
            naming the entry's path.
        ErasedObject: when a blob was erased, naming the entry's
            path and the tombstone's reason.
        FormatError: when a path in the tree is over the budget.
    """
    return view(self, tree, at, writable=writable, allow_hardlink=allow_hardlink)

views

views() -> list[ViewRecord]

Every recorded view, live or not, by id.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def views(self) -> list[ViewRecord]:
    """Every recorded view, live or not, by id."""
    return views(self)

view_record

view_record(view_id: str) -> ViewRecord | None

The record of one view, or None.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def view_record(self, view_id: str) -> ViewRecord | None:
    """The record of one view, or None."""
    return view_record(self, view_id)

drop_view

drop_view(view_id: str) -> DropReport

Remove what the view's record lists, and nothing else.

A path inside the view that the record does not list is left and named; so is a directory that then stays non-empty, the view's root included. A view whose directory is already gone is retired with nothing removed. The record goes either way.

Raises:

Type Description
FileNotFoundError

when no such view is recorded.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def drop_view(self, view_id: str) -> DropReport:
    """Remove what the view's record lists, and nothing else.

    A path inside the view that the record does not list is left
    and named; so is a directory that then stays non-empty, the
    view's root included. A view whose directory is already gone
    is retired with nothing removed. The record goes either way.

    Raises:
        FileNotFoundError: when no such view is recorded.
    """
    return drop_view(self, view_id)

collect

collect(at: Path, declared: Iterable[str], *, executable: Iterable[str] = ()) -> Tree

Read the declared paths under at back into a tree, landing every object.

A declared directory is collected whole; an undeclared path is not read. Names must be portable and paths within the budget.

A blob's executable bit comes from a ladder: a path named in executable is executable on every platform, so one call lands one tree everywhere; otherwise the file mode where it carries the bit; where it does not, the record of the view that made the path, then the platform's reading of a new file, the extension on Windows; otherwise false.

A symlink whose target stays inside at is content, an absolute target recorded as the relative path from the link's directory. One that leaves at is the link rung's own symlink into this store, read through as the blob it presents, when the view's record says so or the target lands under this store's root; any other is refused.

Parameters:

Name Type Description Default
at Path

the directory to read.

required
declared Iterable[str]

the paths to collect, relative and forward-slashed.

required
executable Iterable[str]

the paths that are executable, spelled the same.

()

Returns:

Type Description
Tree

The root tree, landed here with every subtree.

Raises:

Type Description
FileNotFoundError

when a declared path, or a declared executable, is absent.

FormatError

when a name or a symlink target breaks a rule, a symlink escapes at, or a path is over the budget.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def collect(
    self, at: Path, declared: Iterable[str], *, executable: Iterable[str] = ()
) -> Tree:
    """Read the declared paths under *at* back into a tree, landing every object.

    A declared directory is collected whole; an undeclared path is
    not read. Names must be portable and paths within the budget.

    A blob's executable bit comes from a ladder: a path named in
    *executable* is executable on every platform, so one call lands
    one tree everywhere; otherwise the file mode where it carries
    the bit; where it does not, the record of the view that made
    the path, then the platform's reading of a new file, the
    extension on Windows; otherwise false.

    A symlink whose target stays inside *at* is content, an
    absolute target recorded as the relative path from the link's
    directory. One that leaves *at* is the link rung's own symlink
    into this store, read through as the blob it presents, when
    the view's record says so or the target lands under this
    store's root; any other is refused.

    Args:
        at: the directory to read.
        declared: the paths to collect, relative and forward-slashed.
        executable: the paths that are executable, spelled the same.

    Returns:
        The root tree, landed here with every subtree.

    Raises:
        FileNotFoundError: when a declared path, or a declared
            executable, is absent.
        FormatError: when a name or a symlink target breaks a rule,
            a symlink escapes *at*, or a path is over the budget.
    """
    return collect(self, at, declared, executable)

prefetch

prefetch(digest: Digest) -> list[Digest]

Fetch digest and everything it reaches, for offline use.

Returns:

Type Description
list[Digest]

Every object fetched, the root first.

Raises:

Type Description
MissingObject

naming the first digest no source answered.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def prefetch(self, digest: Digest) -> list[Digest]:
    """Fetch *digest* and everything it reaches, for offline use.

    Returns:
        Every object fetched, the root first.

    Raises:
        MissingObject: naming the first digest no source answered.
    """
    return prefetch(self, digest)

shed

shed(source: Source) -> ShedReport

Evict every local copy source holds, except what a live view needs.

Holding is checked by existence in a folder, a HEAD on an HTTP source, or the digest an origin hint names; never by trust. The next fetch verifies on arrival, so a lying source costs a named miss and never a wrong byte. Objects a live view reaches through a hardlink or a link are kept.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def shed(self, source: Source) -> ShedReport:
    """Evict every local copy *source* holds, except what a live view needs.

    Holding is checked by existence in a folder, a HEAD on an HTTP
    source, or the digest an origin hint names; never by trust.
    The next fetch verifies on arrival, so a lying source costs a
    named miss and never a wrong byte. Objects a live view reaches
    through a hardlink or a link are kept.
    """
    return shed(self, source)

head

head(source: HttpSource, relative: str) -> bool

Whether the HTTP source answers a HEAD for relative.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def head(self, source: HttpSource, relative: str) -> bool:
    """Whether the HTTP source answers a HEAD for *relative*."""
    try:
        with fetch_url(
            source.url(relative),
            connect_timeout=source.connect_timeout,
            transfer_timeout=source.transfer_timeout,
            method="HEAD",
        ):
            return True
    except Unreachable:
        return False

ref_path

ref_path(namespace: str, path: str) -> Path

The file a ref lives at, present or not.

Parameters:

Name Type Description Default
namespace str

a declared namespace.

required
path str

the ref's path within it, forward-slashed; each component is a portable name and none ends in a reserved suffix.

required

Raises:

Type Description
UnknownNamespace

when the namespace was not declared.

FormatError

when a path component breaks a rule.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def ref_path(self, namespace: str, path: str) -> Path:
    """The file a ref lives at, present or not.

    Args:
        namespace: a declared namespace.
        path: the ref's path within it, forward-slashed; each
            component is a portable name and none ends in a
            reserved suffix.

    Raises:
        UnknownNamespace: when the namespace was not declared.
        FormatError: when a path component breaks a rule.
    """
    self._namespace(namespace)
    parts = path.split("/")
    for part in parts:
        check_name(part)
        if part.endswith(_RESERVED_SUFFIXES):
            raise FormatError(
                f"ref path component {part!r} ends in a reserved suffix"
            )
    return self.root.joinpath("refs", namespace, *parts)

ref

ref(namespace: str, path: str) -> Digest | None

What the ref names, or None when it does not exist.

Raises:

Type Description
RefTampered

when the ref and its record disagree, or the record is missing or malformed.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def ref(self, namespace: str, path: str) -> Digest | None:
    """What the ref names, or None when it does not exist.

    Raises:
        RefTampered: when the ref and its record disagree, or the
            record is missing or malformed.
    """
    found = self._read_ref(namespace, path)
    return None if found is None else found[0]

record

record(namespace: str, path: str) -> RefRecord | None

The record beside the ref, or None when there is none.

Raises:

Type Description
RefTampered

when the record's bytes are not a record.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def record(self, namespace: str, path: str) -> RefRecord | None:
    """The record beside the ref, or None when there is none.

    Raises:
        RefTampered: when the record's bytes are not a record.
    """
    target = self.ref_path(namespace, path)
    try:
        data = target.with_name(target.name + _RECORD).read_bytes()
    except FileNotFoundError:
        return None
    try:
        return RefRecord.decode(data)
    except FormatError as error:
        raise RefTampered(f"record of {namespace}/{path}: {error}") from None

refs

refs(namespace: str) -> list[str]

Every ref path in the namespace, sorted.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def refs(self, namespace: str) -> list[str]:
    """Every ref path in the namespace, sorted."""
    self._namespace(namespace)
    base = self.root / "refs" / namespace
    found: list[str] = []
    for path in base.rglob("*"):
        if path.is_file() and not path.name.endswith(_RESERVED_SUFFIXES):
            found.append(path.relative_to(base).as_posix())
    return sorted(found)

set_ref

set_ref(namespace: str, path: str, digest: Digest, *, previous: Digest | None, by: Subject, receipt: Digest | None = None, meta: dict[str, Value] | None = None) -> RefRecord

Move a ref by compare-and-swap, writing its record.

The move happens under the ref's lock. The namespace's mutation class is enforced: write-once refuses a second digest and treats the same digest as done; monotone requires the new target to be a version present here whose parents include the current target; volatile needs only the compare-and-swap.

Parameters:

Name Type Description Default
namespace str

a declared namespace.

required
path str

the ref's path.

required
digest Digest

what the ref names afterwards.

required
previous Digest | None

what the caller believes it names now; None to create.

required
by Subject

who moves it.

required
receipt Digest | None

the receipt of the moving call, if any.

None
meta dict[str, Value] | None

the consumer's own object for the record.

None

Returns:

Type Description
RefRecord

The record written, or the existing record when a

RefRecord

write-once ref already names digest.

Raises:

Type Description
RefConflict

when the ref does not name previous.

WriteOnceRefused

on a write-once ref that names another digest.

NotFastForward

on a monotone ref whose new target does not descend from the current one, or is not a version here.

LockTimeout

when a live lock outlasts the timeout.

RefTampered

when the ref and its record disagree.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def set_ref(
    self,
    namespace: str,
    path: str,
    digest: Digest,
    *,
    previous: Digest | None,
    by: Subject,
    receipt: Digest | None = None,
    meta: dict[str, Value] | None = None,
) -> RefRecord:
    """Move a ref by compare-and-swap, writing its record.

    The move happens under the ref's lock. The namespace's
    mutation class is enforced: write-once refuses a second digest
    and treats the same digest as done; monotone requires the new
    target to be a version present here whose parents include the
    current target; volatile needs only the compare-and-swap.

    Args:
        namespace: a declared namespace.
        path: the ref's path.
        digest: what the ref names afterwards.
        previous: what the caller believes it names now; None to
            create.
        by: who moves it.
        receipt: the receipt of the moving call, if any.
        meta: the consumer's own object for the record.

    Returns:
        The record written, or the existing record when a
        write-once ref already names *digest*.

    Raises:
        RefConflict: when the ref does not name *previous*.
        WriteOnceRefused: on a write-once ref that names another digest.
        NotFastForward: on a monotone ref whose new target does not
            descend from the current one, or is not a version here.
        LockTimeout: when a live lock outlasts the timeout.
        RefTampered: when the ref and its record disagree.
    """
    with self._locked(self.ref_path(namespace, path)):
        return self._move_locked(
            namespace,
            path,
            digest,
            previous=previous,
            by=by,
            receipt=receipt,
            meta=meta,
        )

Entry dataclass

Entry(name: str, kind: EntryKind, digest: Digest, size: int, executable: bool = False)

A blob or a subtree inside a tree.

Attributes:

Name Type Description
name str

the portable name, one path component.

kind EntryKind

blob or tree.

digest Digest

the object the entry names.

size int

the blob's byte count, or the subtree's canonical JSON byte count, so a materialiser plans a view without opening a blob.

executable bool

whether a blob is marked executable. Always false for a tree.

Methods:

Name Description
__post_init__
to_json

The entry as a JSON object.

name instance-attribute

name: str

kind instance-attribute

kind: EntryKind

digest instance-attribute

digest: Digest

size instance-attribute

size: int

executable class-attribute instance-attribute

executable: bool = False

__post_init__

__post_init__() -> None
Source code in packages/strongroom/src/livery/strongroom/_tree.py
def __post_init__(self) -> None:
    check_name(self.name)
    if self.kind not in ("blob", "tree"):
        raise FormatError(
            f"entry {self.name!r} kind {self.kind!r} is not blob or tree"
        )
    expect_int(self.size, where=f"entry {self.name!r} size")
    if self.kind == "tree" and self.executable:
        raise FormatError(f"entry {self.name!r} is a tree and cannot be executable")

to_json

to_json() -> dict[str, Value]

The entry as a JSON object.

Source code in packages/strongroom/src/livery/strongroom/_tree.py
def to_json(self) -> dict[str, Value]:
    """The entry as a JSON object."""
    return {
        "name": self.name,
        "kind": self.kind,
        "digest": str(self.digest),
        "size": self.size,
        "executable": self.executable,
    }
Link(name: str, target: str)

A symlink inside a tree; the target string is its whole content.

Attributes:

Name Type Description
name str

the portable name, one path component.

target str

the link's target, relative and forward-slashed.

Methods:

Name Description
__post_init__
to_json

The link as a JSON object.

name instance-attribute

name: str

target instance-attribute

target: str

__post_init__

__post_init__() -> None
Source code in packages/strongroom/src/livery/strongroom/_tree.py
def __post_init__(self) -> None:
    check_name(self.name)
    check_target(self.target)

to_json

to_json() -> dict[str, Value]

The link as a JSON object.

Source code in packages/strongroom/src/livery/strongroom/_tree.py
def to_json(self) -> dict[str, Value]:
    """The link as a JSON object."""
    return {"name": self.name, "kind": "symlink", "target": self.target}

Tree dataclass

Tree(entries: tuple[Entry | Link, ...])

A directory: its entries, sorted by name bytes.

Build one with livery.strongroom.Tree.of, which sorts and validates; decode one with livery.strongroom.Tree.decode, which refuses a tree whose bytes are not already canonical.

Attributes:

Name Type Description
entries tuple[Entry | Link, ...]

the entries in name-byte order.

Methods:

Name Description
of

Build a tree from entries, sorting them and refusing clashes.

to_json

The tree as a JSON object.

from_json

Decode a tree from its JSON value.

encode

The tree's canonical JSON bytes, which its digest names.

decode

Decode a tree from its stored bytes.

digest

The tree's name: the digest of its canonical JSON.

entries instance-attribute

entries: tuple[Entry | Link, ...]

of classmethod

of(entries: Iterable[Entry | Link]) -> Tree

Build a tree from entries, sorting them and refusing clashes.

Parameters:

Name Type Description Default
entries Iterable[Entry | Link]

the directory's entries, in any order.

required

Returns:

Type Description
Tree

The tree.

Raises:

Type Description
FormatError

when two entries share a name, or two names are equal when case is ignored.

Source code in packages/strongroom/src/livery/strongroom/_tree.py
@classmethod
def of(cls, entries: Iterable[Entry | Link]) -> Tree:
    """Build a tree from *entries*, sorting them and refusing clashes.

    Args:
        entries: the directory's entries, in any order.

    Returns:
        The tree.

    Raises:
        FormatError: when two entries share a name, or two names are
            equal when case is ignored.
    """
    ordered = tuple(sorted(entries, key=lambda entry: entry.name.encode("utf-8")))
    seen: dict[str, str] = {}
    for entry in ordered:
        folded = entry.name.casefold()
        other = seen.get(folded)
        if other is not None:
            raise FormatError(
                f"entries {other!r} and {entry.name!r} are the same name"
                " when case is ignored"
            )
        seen[folded] = entry.name
    return cls(ordered)

to_json

to_json() -> dict[str, Value]

The tree as a JSON object.

Source code in packages/strongroom/src/livery/strongroom/_tree.py
def to_json(self) -> dict[str, Value]:
    """The tree as a JSON object."""
    return {"entries": [entry.to_json() for entry in self.entries]}

from_json classmethod

from_json(value: Value) -> Tree

Decode a tree from its JSON value.

Parameters:

Name Type Description Default
value Value

the JSON value.

required

Returns:

Type Description
Tree

The tree.

Raises:

Type Description
FormatError

when the shape is wrong, an entry breaks a rule, or the entries are not in name-byte order.

Source code in packages/strongroom/src/livery/strongroom/_tree.py
@classmethod
def from_json(cls, value: Value) -> Tree:
    """Decode a tree from its JSON value.

    Args:
        value: the JSON value.

    Returns:
        The tree.

    Raises:
        FormatError: when the shape is wrong, an entry breaks a
            rule, or the entries are not in name-byte order.
    """
    fields = expect_object(value, ("entries",), where="tree")
    items = expect_list(fields["entries"], where="tree.entries")
    entries = [_entry_from_json(item, index) for index, item in enumerate(items)]
    names = [entry.name.encode("utf-8") for entry in entries]
    if names != sorted(names):
        raise FormatError("tree.entries are not sorted by name bytes")
    return cls.of(entries)

encode

encode() -> bytes

The tree's canonical JSON bytes, which its digest names.

Source code in packages/strongroom/src/livery/strongroom/_tree.py
def encode(self) -> bytes:
    """The tree's canonical JSON bytes, which its digest names."""
    return canonical(self.to_json())

decode classmethod

decode(data: bytes) -> Tree

Decode a tree from its stored bytes.

Parameters:

Name Type Description Default
data bytes

the object's bytes.

required

Returns:

Type Description
Tree

The tree.

Raises:

Type Description
FormatError

when the bytes are not JSON, not a tree, or not the canonical encoding of the tree they describe. A non-canonical tree would have a second name for the same content.

Source code in packages/strongroom/src/livery/strongroom/_tree.py
@classmethod
def decode(cls, data: bytes) -> Tree:
    """Decode a tree from its stored bytes.

    Args:
        data: the object's bytes.

    Returns:
        The tree.

    Raises:
        FormatError: when the bytes are not JSON, not a tree, or not
            the canonical encoding of the tree they describe. A
            non-canonical tree would have a second name for the
            same content.
    """
    import json

    try:
        value = json.loads(data)
    except ValueError as error:
        raise FormatError(f"tree bytes are not JSON: {error}") from None
    tree = cls.from_json(value)
    if tree.encode() != data:
        raise FormatError("tree bytes are not canonical JSON")
    return tree

digest

digest() -> Digest

The tree's name: the digest of its canonical JSON.

Source code in packages/strongroom/src/livery/strongroom/_tree.py
def digest(self) -> Digest:
    """The tree's name: the digest of its canonical JSON."""
    return digest_of(self.encode())

Version dataclass

Version(tree: Digest, parents: tuple[Digest, ...], producer: Subject, created: str, message: str, receipt: Digest | None = None, attachments: Mapping[str, Digest] = dict())

Provenance over a tree.

Attributes:

Name Type Description
tree Digest

the content.

parents tuple[Digest, ...]

the versions this one continues, in order.

producer Subject

who or what produced it.

created str

when, as an RFC 3339 UTC instant.

message str

free text.

receipt Digest | None

the receipt of the producing call, or None.

attachments Mapping[str, Digest]

name to blob digest, for a consumer's own metadata. Names obey the portable-name rules.

Methods:

Name Description
__post_init__
to_json

The version as a JSON object.

from_json

Decode a version from its JSON value.

encode

The version's canonical JSON bytes, which its digest names.

decode

Decode a version from its stored bytes.

digest

The version's name: the digest of its canonical JSON.

tree instance-attribute

tree: Digest

parents instance-attribute

parents: tuple[Digest, ...]

producer instance-attribute

producer: Subject

created instance-attribute

created: str

message instance-attribute

message: str

receipt class-attribute instance-attribute

receipt: Digest | None = None

attachments class-attribute instance-attribute

attachments: Mapping[str, Digest] = field(default_factory=dict)

__post_init__

__post_init__() -> None
Source code in packages/strongroom/src/livery/strongroom/_version.py
def __post_init__(self) -> None:
    check_timestamp(self.created, where="version.created")
    for name in self.attachments:
        check_name(name)

to_json

to_json() -> dict[str, Value]

The version as a JSON object.

Source code in packages/strongroom/src/livery/strongroom/_version.py
def to_json(self) -> dict[str, Value]:
    """The version as a JSON object."""
    return {
        "tree": str(self.tree),
        "parents": [str(parent) for parent in self.parents],
        "producer": self.producer.to_json(),
        "created": self.created,
        "message": self.message,
        "receipt": None if self.receipt is None else str(self.receipt),
        "attachments": {
            name: str(digest) for name, digest in self.attachments.items()
        },
    }

from_json classmethod

from_json(value: Value) -> Version

Decode a version from its JSON value.

Parameters:

Name Type Description Default
value Value

the JSON value.

required

Returns:

Type Description
Version

The version.

Raises:

Type Description
FormatError

when the shape or a field is wrong.

Source code in packages/strongroom/src/livery/strongroom/_version.py
@classmethod
def from_json(cls, value: Value) -> Version:
    """Decode a version from its JSON value.

    Args:
        value: the JSON value.

    Returns:
        The version.

    Raises:
        FormatError: when the shape or a field is wrong.
    """
    fields = expect_object(
        value,
        (
            "tree",
            "parents",
            "producer",
            "created",
            "message",
            "receipt",
            "attachments",
        ),
        where="version",
    )
    parents = expect_list(fields["parents"], where="version.parents")
    attachments = fields["attachments"]
    if not isinstance(attachments, dict):
        raise FormatError("version.attachments is not a JSON object")
    return cls(
        tree=expect_digest(fields["tree"], where="version.tree"),
        parents=tuple(
            expect_digest(parent, where=f"version.parents[{index}]")
            for index, parent in enumerate(parents)
        ),
        producer=Subject.from_json(fields["producer"], where="version.producer"),
        created=expect_str(fields["created"], where="version.created"),
        message=expect_str(fields["message"], where="version.message"),
        receipt=expect_optional_digest(fields["receipt"], where="version.receipt"),
        attachments={
            expect_str(name, where="version.attachments key"): expect_digest(
                digest, where=f"version.attachments[{name!r}]"
            )
            for name, digest in attachments.items()
        },
    )

encode

encode() -> bytes

The version's canonical JSON bytes, which its digest names.

Source code in packages/strongroom/src/livery/strongroom/_version.py
def encode(self) -> bytes:
    """The version's canonical JSON bytes, which its digest names."""
    return canonical(self.to_json())

decode classmethod

decode(data: bytes) -> Version

Decode a version from its stored bytes.

Parameters:

Name Type Description Default
data bytes

the object's bytes.

required

Returns:

Type Description
Version

The version.

Raises:

Type Description
FormatError

when the bytes are not JSON, not a version, or not canonical.

Source code in packages/strongroom/src/livery/strongroom/_version.py
@classmethod
def decode(cls, data: bytes) -> Version:
    """Decode a version from its stored bytes.

    Args:
        data: the object's bytes.

    Returns:
        The version.

    Raises:
        FormatError: when the bytes are not JSON, not a version, or
            not canonical.
    """
    try:
        value = json.loads(data)
    except ValueError as error:
        raise FormatError(f"version bytes are not JSON: {error}") from None
    version = cls.from_json(value)
    if version.encode() != data:
        raise FormatError("version bytes are not canonical JSON")
    return version

digest

digest() -> Digest

The version's name: the digest of its canonical JSON.

Source code in packages/strongroom/src/livery/strongroom/_version.py
def digest(self) -> Digest:
    """The version's name: the digest of its canonical JSON."""
    return digest_of(self.encode())

DropReport dataclass

DropReport(removed: tuple[str, ...] = tuple(), left: tuple[str, ...] = tuple())

What dropping a view removed and what it left.

Attributes:

Name Type Description
removed tuple[str, ...]

every path removed, files first, then directories deepest first, then the root as ..

left tuple[str, ...]

every path found that the record did not list, with the reason; never touched.

removed class-attribute instance-attribute

removed: tuple[str, ...] = field(default_factory=tuple)

left class-attribute instance-attribute

left: tuple[str, ...] = field(default_factory=tuple)

ShedReport dataclass

ShedReport(source: str, shed: tuple[Digest, ...] = tuple(), kept: tuple[Digest, ...] = tuple())

What a shed did.

Attributes:

Name Type Description
source str

the source relied on, described.

shed tuple[Digest, ...]

every local copy evicted because the source holds it.

kept tuple[Digest, ...]

every object kept because a live view depends on it.

source instance-attribute

source: str

shed class-attribute instance-attribute

shed: tuple[Digest, ...] = field(default_factory=tuple)

kept class-attribute instance-attribute

kept: tuple[Digest, ...] = field(default_factory=tuple)

ViewEntry dataclass

ViewEntry(path: str, rung: EntryRung, digest: Digest | None = None, note: str = '', executable: bool = False)

One path a view created, and how.

Attributes:

Name Type Description
path str

relative to the view's root, forward-slashed.

rung EntryRung

how it was made; parked means it was refused and the note says why.

digest Digest | None

the blob it presents, or None for a symlink entry.

note str

why a symlink became a copy or was parked; empty otherwise.

executable bool

whether the tree marked the blob executable; what collect answers for this path where the file mode cannot.

Methods:

Name Description
to_json

The entry as a JSON object.

from_json

Decode an entry, refusing a rung outside the ladder.

path instance-attribute

path: str

rung instance-attribute

rung: EntryRung

digest class-attribute instance-attribute

digest: Digest | None = None

note class-attribute instance-attribute

note: str = ''

executable class-attribute instance-attribute

executable: bool = False

to_json

to_json() -> dict[str, Value]

The entry as a JSON object.

Source code in packages/strongroom/src/livery/strongroom/_views.py
def to_json(self) -> dict[str, Value]:
    """The entry as a JSON object."""
    return {
        "path": self.path,
        "rung": self.rung,
        "digest": None if self.digest is None else str(self.digest),
        "note": self.note,
        "executable": self.executable,
    }

from_json classmethod

from_json(value: Value) -> ViewEntry

Decode an entry, refusing a rung outside the ladder.

Source code in packages/strongroom/src/livery/strongroom/_views.py
@classmethod
def from_json(cls, value: Value) -> ViewEntry:
    """Decode an entry, refusing a rung outside the ladder."""
    fields = expect_object(
        value, ("path", "rung", "digest", "note", "executable"), where="entry"
    )
    digest = fields["digest"]
    return cls(
        expect_str(fields["path"], where="entry.path"),
        _entry_rung(expect_str(fields["rung"], where="entry.rung")),
        None
        if digest is None
        else Digest.parse(expect_str(digest, where="entry.digest")),
        expect_str(fields["note"], where="entry.note"),
        expect_bool(fields["executable"], where="entry.executable"),
    )

ViewRecord dataclass

ViewRecord(id: str, tree: Digest, at: str, writable: bool, created: str, entries: tuple[ViewEntry, ...] = tuple(), directories: tuple[str, ...] = tuple())

A view: local state in the index, and a root while its directory exists.

Attributes:

Name Type Description
id str

the record's name under index/views/.

tree Digest

the tree the view presents.

at str

the view's root directory.

writable bool

whether the caller said it would write.

created str

when, an instant.

entries tuple[ViewEntry, ...]

every path created, in creation order.

directories tuple[str, ...]

every directory created, shallowest first.

Methods:

Name Description
encode

The record's canonical JSON bytes.

decode

Decode a record.

depends_on

The objects this view reads through the store's own files.

id instance-attribute

id: str

tree instance-attribute

tree: Digest

at instance-attribute

at: str

writable instance-attribute

writable: bool

created instance-attribute

created: str

entries class-attribute instance-attribute

entries: tuple[ViewEntry, ...] = field(default_factory=tuple)

directories class-attribute instance-attribute

directories: tuple[str, ...] = field(default_factory=tuple)

root property

root: Path

The view's root as a path.

encode

encode() -> bytes

The record's canonical JSON bytes.

Source code in packages/strongroom/src/livery/strongroom/_views.py
def encode(self) -> bytes:
    """The record's canonical JSON bytes."""
    return canonical(
        {
            "id": self.id,
            "tree": str(self.tree),
            "at": self.at,
            "writable": self.writable,
            "created": self.created,
            "entries": [entry.to_json() for entry in self.entries],
            "directories": list(self.directories),
        }
    )

decode classmethod

decode(data: bytes) -> ViewRecord

Decode a record.

Raises:

Type Description
FormatError

when the bytes are not a record.

Source code in packages/strongroom/src/livery/strongroom/_views.py
@classmethod
def decode(cls, data: bytes) -> ViewRecord:
    """Decode a record.

    Raises:
        FormatError: when the bytes are not a record.
    """
    try:
        value: Value = json.loads(data)
    except ValueError as error:
        raise FormatError(f"view record bytes are not JSON: {error}") from None
    fields = expect_object(
        value,
        ("id", "tree", "at", "writable", "created", "entries", "directories"),
        where="view",
    )
    return cls(
        expect_str(fields["id"], where="view.id"),
        Digest.parse(expect_str(fields["tree"], where="view.tree")),
        expect_str(fields["at"], where="view.at"),
        expect_bool(fields["writable"], where="view.writable"),
        expect_str(fields["created"], where="view.created"),
        tuple(
            ViewEntry.from_json(item)
            for item in expect_list(fields["entries"], where="view.entries")
        ),
        tuple(
            expect_str(item, where="view.directories[]")
            for item in expect_list(fields["directories"], where="view.directories")
        ),
    )

depends_on

depends_on() -> set[Digest]

The objects this view reads through the store's own files.

Source code in packages/strongroom/src/livery/strongroom/_views.py
def depends_on(self) -> set[Digest]:
    """The objects this view reads through the store's own files."""
    return {
        entry.digest
        for entry in self.entries
        if entry.rung in ("hardlink", "link") and entry.digest is not None
    }

canonical

canonical(value: Value) -> bytes

Encode value as RFC 8785 canonical JSON, UTF-8.

Object keys sort by their UTF-16 code units, which differs from code-point order above the Basic Multilingual Plane. Strings keep every character above U+001F literal.

Parameters:

Name Type Description Default
value Value

the value to encode. Nested values are encoded the same way.

required

Returns:

Type Description
bytes

The canonical bytes. Two equal values encode to equal bytes.

Raises:

Type Description
FormatError

on a float, an integer past 2^53 in magnitude, a non-string key, or a value of a type no format carries.

Source code in packages/strongroom/src/livery/strongroom/_canonical.py
def canonical(value: Value) -> bytes:
    """Encode *value* as RFC 8785 canonical JSON, UTF-8.

    Object keys sort by their UTF-16 code units, which differs from
    code-point order above the Basic Multilingual Plane. Strings keep
    every character above U+001F literal.

    Args:
        value: the value to encode. Nested values are encoded the same
            way.

    Returns:
        The canonical bytes. Two equal values encode to equal bytes.

    Raises:
        FormatError: on a float, an integer past 2^53 in magnitude, a
            non-string key, or a value of a type no format carries.
    """
    parts: list[str] = []
    _write(value, parts)
    return "".join(parts).encode("utf-8")

digest_of

digest_of(data: bytes, *, algorithm: str = name) -> Digest

Name data under algorithm.

Parameters:

Name Type Description Default
data bytes

the bytes to name.

required
algorithm str

a registry entry's name; sha256 by default.

name

Returns:

Type Description
Digest

The digest.

Raises:

Type Description
FormatError

when the algorithm is not registered.

Source code in packages/strongroom/src/livery/strongroom/_digest.py
def digest_of(data: bytes, *, algorithm: str = SHA256.name) -> Digest:
    """Name *data* under *algorithm*.

    Args:
        data: the bytes to name.
        algorithm: a registry entry's name; `sha256` by default.

    Returns:
        The digest.

    Raises:
        FormatError: when the algorithm is not registered.
    """
    entry = registered(algorithm)
    return Digest(entry.name, entry.constructor(data).hexdigest())

digest_stream

digest_stream(stream: IO[bytes], *, algorithm: str = name) -> Digest

Name the bytes read from stream to its end, without holding them.

Parameters:

Name Type Description Default
stream IO[bytes]

an open binary stream, read in chunks until empty.

required
algorithm str

a registry entry's name; sha256 by default.

name

Returns:

Type Description
Digest

The digest.

Raises:

Type Description
FormatError

when the algorithm is not registered.

Source code in packages/strongroom/src/livery/strongroom/_digest.py
def digest_stream(stream: IO[bytes], *, algorithm: str = SHA256.name) -> Digest:
    """Name the bytes read from *stream* to its end, without holding them.

    Args:
        stream: an open binary stream, read in chunks until empty.
        algorithm: a registry entry's name; `sha256` by default.

    Returns:
        The digest.

    Raises:
        FormatError: when the algorithm is not registered.
    """
    entry = registered(algorithm)
    hasher = entry.constructor(b"")
    while chunk := stream.read(_STREAM_CHUNK):
        hasher.update(chunk)
    return Digest(entry.name, hasher.hexdigest())

check_timestamp

check_timestamp(value: str, *, where: str) -> str

Return value when it is an RFC 3339 UTC instant, or refuse.

The form is YYYY-MM-DDTHH:MM:SS[.fraction]Z: seconds required, up to nine fractional digits, the Z designator and no offset, so one instant has one spelling.

Source code in packages/strongroom/src/livery/strongroom/_fields.py
def check_timestamp(value: str, *, where: str) -> str:
    """Return *value* when it is an RFC 3339 UTC instant, or refuse.

    The form is `YYYY-MM-DDTHH:MM:SS[.fraction]Z`: seconds required,
    up to nine fractional digits, the `Z` designator and no offset, so
    one instant has one spelling.
    """
    if _TIMESTAMP.match(value) is None:
        raise FormatError(
            f"{where} {value!r} is not an RFC 3339 UTC instant of the form"
            " YYYY-MM-DDTHH:MM:SS[.fraction]Z"
        )
    try:
        datetime.fromisoformat(value[:19])
    except ValueError as error:
        raise FormatError(f"{where} {value!r} is not a real instant: {error}") from None
    return value

fetch_url

fetch_url(url: str, *, connect_timeout: float, transfer_timeout: float, method: str = 'GET', headers: Mapping[str, str] | None = None) -> Generator[HTTPResponse]

Open url for reading, or raise Unreachable naming why.

The one seam every network read goes through, so tests fake it and a fetch never needs a server. The connect timeout bounds establishing the connection; the transfer timeout then bounds each wait for bytes, headers included. method is GET, or HEAD to learn whether a source holds an object without reading it. headers are sent with the request to url's host and port, and to a redirect on that same host and port; a redirect anywhere else gets none of them, so a credential meant for an API never reaches the storage host the API redirects a download to.

A redirect (301, 302, 303, 307, 308) is followed to its Location, resolved against the URL that answered it, with the same method and both timeouts per hop, up to REDIRECTS hops: a forge serves a release asset from a storage host it redirects to, and the bytes are the same bytes. A chain longer than that, or a redirect naming no location, is refused naming the chain.

Yields:

Type Description
Generator[HTTPResponse]

The response, status 200, positioned at its first byte.

Raises:

Type Description
Unreachable

on a connection error, a timeout, a redirect chain that does not end, or any final status other than 200. A 404 is the source saying it does not have the object, which for the fetch is the same thing.

Source code in packages/strongroom/src/livery/strongroom/_sources.py
@contextlib.contextmanager
def fetch_url(
    url: str,
    *,
    connect_timeout: float,
    transfer_timeout: float,
    method: str = "GET",
    headers: Mapping[str, str] | None = None,
) -> Generator[http.client.HTTPResponse]:
    """Open *url* for reading, or raise Unreachable naming why.

    The one seam every network read goes through, so tests fake it and
    a fetch never needs a server. The connect timeout bounds
    establishing the connection; the transfer timeout then bounds
    each wait for bytes, headers included. `method` is `GET`, or
    `HEAD` to learn whether a source holds an object without reading it.
    *headers* are sent with the request to *url*'s host and port, and
    to a redirect on that same host and port; a redirect anywhere else
    gets none of them, so a credential meant for an API never reaches
    the storage host the API redirects a download to.

    A redirect (301, 302, 303, 307, 308) is followed to its `Location`,
    resolved against the URL that answered it, with the same method
    and both timeouts per hop, up to `REDIRECTS` hops: a forge serves
    a release asset from a storage host it redirects to, and the bytes
    are the same bytes. A chain longer than that, or a redirect naming
    no location, is refused naming the chain.

    Yields:
        The response, status 200, positioned at its first byte.

    Raises:
        Unreachable: on a connection error, a timeout, a redirect chain
            that does not end, or any final status other than 200. A
            404 is the source saying it does not have the object, which
            for the fetch is the same thing.
    """
    chain = [url]
    first = urlsplit(url)
    first_host = (first.hostname, first.port)
    while True:
        parts = urlsplit(chain[-1])
        connection = _CONNECTIONS[parts.scheme](
            cast(str, parts.hostname), parts.port, timeout=connect_timeout
        )
        try:
            target = parts.path or "/"
            if parts.query:
                target = f"{target}?{parts.query}"
            # Connecting is bounded by the connect timeout; once the socket
            # exists, every later wait is bounded by the transfer timeout.
            connection.connect()
            cast(socket.socket, connection.sock).settimeout(transfer_timeout)
            same = (parts.hostname, parts.port) == first_host
            sent = dict(headers or {}) if same else {}
            connection.request(method, target, headers=sent)
            response = connection.getresponse()
            if response.status in _REDIRECT_STATUSES:
                location = response.getheader("Location")
                if not location:
                    raise Unreachable(
                        f"{chain[-1]}: HTTP {response.status} names no location"
                        f" (after {' -> '.join(chain)})"
                    )
                if len(chain) > REDIRECTS:
                    raise Unreachable(
                        f"{url}: more than {REDIRECTS} redirects"
                        f" ({' -> '.join([*chain, location])})"
                    )
                chain.append(urljoin(chain[-1], location))
                _check_url(chain[-1])
                continue
            if response.status != 200:
                raise Unreachable(
                    f"{chain[-1]}: HTTP {response.status}", status=response.status
                )
            yield response
            return
        except (OSError, http.client.HTTPException) as error:
            raise Unreachable(f"{chain[-1]}: {error}") from None
        except ValueError as error:
            raise Unreachable(f"{chain[-1]}: {error}") from None
        finally:
            connection.close()

now

now() -> str

The current instant, RFC 3339 in UTC to the second.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def now() -> str:
    """The current instant, RFC 3339 in UTC to the second."""
    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")

silent

silent(message: str) -> None

The default progress sink: report nothing.

Source code in packages/strongroom/src/livery/strongroom/_store.py
def silent(message: str) -> None:
    """The default progress sink: report nothing."""

check_name

check_name(name: str) -> str

Return name when it is portable, or refuse it.

The rules: non-empty, not . or .., Unicode NFC, at most livery.strongroom.NAME_BUDGET UTF-8 bytes, no separator, no control character, none of <>:"|?*, no trailing dot or space, and not a Windows-reserved stem such as CON or LPT1 in any case, with or without an extension.

Parameters:

Name Type Description Default
name str

one path component.

required

Returns:

Type Description
str

The name, unchanged.

Raises:

Type Description
FormatError

naming the rule the name breaks.

Source code in packages/strongroom/src/livery/strongroom/_tree.py
def check_name(name: str) -> str:
    """Return *name* when it is portable, or refuse it.

    The rules: non-empty, not `.` or `..`, Unicode NFC, at most
    [livery.strongroom.NAME_BUDGET][] UTF-8 bytes, no separator, no
    control character, none of `<>:"|?*`, no trailing dot or space,
    and not a Windows-reserved stem such as `CON` or `LPT1` in any
    case, with or without an extension.

    Args:
        name: one path component.

    Returns:
        The name, unchanged.

    Raises:
        FormatError: naming the rule the name breaks.
    """
    where = f"entry name {name!r}"
    if not name:
        raise FormatError("entry name is empty")
    if name in (".", ".."):
        raise FormatError(f"{where} is a relative directory marker")
    nfc(name, where=where)
    if len(name.encode("utf-8")) > NAME_BUDGET:
        raise FormatError(f"{where} is longer than {NAME_BUDGET} UTF-8 bytes")
    if _FORBIDDEN.search(name) is not None:
        raise FormatError(
            f'{where} contains a separator, a control character, or one of <>:"|?*'
        )
    if name[-1] in ". ":
        raise FormatError(f"{where} ends in a dot or a space")
    stem = name.split(".", 1)[0]
    if stem.upper() in _RESERVED_STEMS:
        raise FormatError(f"{where} is a Windows-reserved name")
    return name

check_target

check_target(target: str) -> str

Return a symlink target when it is portable, or refuse it.

A target is content: UTF-8 in NFC, forward slashes only, relative always. Whether it may escape its view is the view's policy.

Parameters:

Name Type Description Default
target str

the link's target string.

required

Returns:

Type Description
str

The target, unchanged.

Raises:

Type Description
FormatError

naming the rule the target breaks.

Source code in packages/strongroom/src/livery/strongroom/_tree.py
def check_target(target: str) -> str:
    """Return a symlink *target* when it is portable, or refuse it.

    A target is content: UTF-8 in NFC, forward slashes only, relative
    always. Whether it may escape its view is the view's policy.

    Args:
        target: the link's target string.

    Returns:
        The target, unchanged.

    Raises:
        FormatError: naming the rule the target breaks.
    """
    where = f"symlink target {target!r}"
    if not target:
        raise FormatError("symlink target is empty")
    nfc(target, where=where)
    if "\\" in target or "\x00" in target:
        raise FormatError(f"{where} contains a backslash or NUL; use forward slashes")
    if _ABSOLUTE_TARGET.match(target) is not None:
        raise FormatError(f"{where} is absolute; a target names a path inside a view")
    return target

__getattr__

__getattr__(name: str) -> object

Serve a public name from its module on first use, then keep it.

Source code in packages/strongroom/src/livery/strongroom/__init__.py
def __getattr__(name: str) -> object:
    """Serve a public name from its module on first use, then keep it."""
    import importlib

    if name in _PACKAGES:
        value: object = importlib.import_module(f"livery.strongroom.{name}")
    else:
        found = _EXPORTS.get(name)
        if found is None:
            raise AttributeError(
                f"module 'livery.strongroom' has no attribute {name!r}"
            )
        module, attribute = found
        value = getattr(importlib.import_module(module), attribute)
    globals()[name] = value
    return value