Skip to content

livery.strongroom._digest

livery.strongroom._digest

Digest strings: the name of every object.

A name is <algorithm>:<encoded> in the OCI digest grammar, and the registry says which algorithms may name bytes. sha256 is required and is the only entry; the registry exists so a successor is an entry and never a migration. One address space uses one algorithm, recorded in its root manifest.

Reach for livery.strongroom.Digest to parse a name and livery.strongroom.digest_of to name bytes.

Classes:

Name Description
Hasher

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

HashConstructor

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

Algorithm

One registry entry: how an algorithm names bytes.

Digest

A parsed digest string.

Functions:

Name Description
digest_of

Name data under algorithm.

digest_stream

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

registered

The registry entry for algorithm, or a refusal naming the registry.

Attributes:

Name Type Description
SHA256 Final

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

ALGORITHMS Final[dict[str, Algorithm]]

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.

ALGORITHMS module-attribute

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

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

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: ...

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: ...

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)

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

registered

registered(algorithm: str) -> Algorithm

The registry entry for algorithm, or a refusal naming the registry.

Source code in packages/strongroom/src/livery/strongroom/_digest.py
def registered(algorithm: str) -> Algorithm:
    """The registry entry for *algorithm*, or a refusal naming the registry."""
    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})"
        )
    return entry