Skip to content

livery.strongroom._version

livery.strongroom._version

The version: provenance over a tree, git's commit with a subject.

A version names a tree, its parents, what produced it, when, a message, the receipt of the call that produced it when there is one, and attachments: blobs a consumer hangs on the version without touching the tree. Its digest is the digest of its canonical JSON.

Reach for livery.strongroom.Version.

Classes:

Name Description
Version

Provenance over a tree.

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())