an.library.ids

Asset ids, version labels and library references — the library’s persisted names.

Three grammars, each a persisted identifier (ADR 0005 decisions 3 and 4, plan §1 decision 7), so each is checked here once and never re-parsed by hand elsewhere:

• an asset id is <kind>.<slug> — flat, readable, filename-safe (character.alice-reiniger). The kind prefix keeps two kinds from colliding on one slug and makes find(kind=…) cheap;

• a version label is v001, v002, … — the studio convention, for people. The version’s manifest_sha256 is its identity for machines;

• a library reference is [<namespace>:]<asset_id>[@<version>], where <version> is a label, latest (floating; resolved once at check-out and pinned) or sha256:<prefix> (exact content). The namespace names the library an id resolves in when several are federated (cutan:character.alice@v003).

Because these strings become file names (records/<asset_id>.json, versions/<asset_id>/<vNNN>.json), the grammars are also the path-traversal guard: nothing that parses here can contain /, .. or a drive letter.

>>> ref = parse_ref("cutan:character.alice-reiniger@v003")
>>> (ref.namespace, ref.asset_id, ref.version, ref.kind)
('cutan', 'character.alice-reiniger', 'v003', 'character')
>>> str(ref)
'cutan:character.alice-reiniger@v003'
>>> version_label(12)
'v012'

Module Attributes

LATEST	the record's head, resolved once and then pinned.
SHA256_PREFIX	The prefix of a content-addressed version selector (sha256:<hex prefix>).

Functions

asset_kind(asset_id)	The kind an asset id declares by its prefix.
check_asset_id(asset_id)	Return asset_id if it is <kind>.<slug>, else raise AssetIdError.
check_namespace(name)	Return name if it can name a library (a package name), else raise.
check_version_label(label)	Return label if it is vNNN, else raise AssetIdError.
parse_ref(text, *[, require_version, ...])	Parse a library reference.
version_label(number)	The label of the number-th version (1-based).
version_number(label)	The number of a version label.

Classes

LibraryRef(asset_id[, version, namespace])

A parsed [<namespace>:]<asset_id>[@<version>].

Exceptions

AssetIdError

An asset id, version label or library reference that does not parse.

exception an.library.ids.AssetIdError

Bases: ValueError

An asset id, version label or library reference that does not parse.

an.library.ids.LATEST: str = 'latest'

the record’s head, resolved once and then pinned.

Type:

The floating version

class an.library.ids.LibraryRef(asset_id, version=None, namespace=None)

Bases: object

A parsed [<namespace>:]<asset_id>[@<version>].

version is None when the reference gave none (read as latest by readers; refused where a pin is required, e.g. AssetRef.library).

property is_pinned: bool

Whether this names one immutable version (a label or a content hash).

property kind: str

The asset kind, from the id’s prefix.

with_namespace(namespace)

The same asset and version, qualified by another library name.

Return type:

LibraryRef

with_version(version)

The same asset, another version.

Return type:

LibraryRef

an.library.ids.SHA256_PREFIX: str = 'sha256:'

The prefix of a content-addressed version selector (sha256:<hex prefix>).

an.library.ids.asset_kind(asset_id)

The kind an asset id declares by its prefix.

Return type:

str

>>> asset_kind("environment.palace-hall")
'environment'

an.library.ids.check_asset_id(asset_id)

Return asset_id if it is <kind>.<slug>, else raise AssetIdError.

Return type:

str

>>> check_asset_id("prop.teacup-victorian")
'prop.teacup-victorian'
>>> check_asset_id("Alice")
Traceback (most recent call last):
AssetIdError: ...

an.library.ids.check_namespace(name)

Return name if it can name a library (a package name), else raise.

Return type:

str

an.library.ids.check_version_label(label)

Return label if it is vNNN, else raise AssetIdError.

Return type:

str

an.library.ids.parse_ref(text, *, require_version=False, require_pin=False)

Parse a library reference.

require_version=True refuses a reference with no @<version>; require_pin=True also refuses @latest — the grammar of AssetRef.library, where a floating reference would make a render depend on whatever the library’s head is that day.

Return type:

LibraryRef

>>> parse_ref("character.alice")
LibraryRef(asset_id='character.alice', version=None, namespace=None)
>>> parse_ref("character.alice@sha256:0a1b2c3d").version
'sha256:0a1b2c3d'
>>> parse_ref("character.alice", require_version=True)
Traceback (most recent call last):
AssetIdError: ...

an.library.ids.version_label(number)

The label of the number-th version (1-based).

Return type:

str

>>> version_label(1), version_label(1000)
('v001', 'v1000')

an.library.ids.version_number(label)

The number of a version label.

Return type:

int

>>> version_number("v012")
12