livery.strongroom._tree¶
livery.strongroom._tree ¶
The tree: a directory as a manifest, git's model with sizes.
An entry names a blob, a tree, or a symlink. Entries sort by their name's UTF-8 bytes, a tree's digest is the digest of its canonical JSON, and every name obeys the portable-name rules so a tree is refused where the producer can fix it, never discovered at checkout on the platform that cannot represent it.
Reach for livery.strongroom.Tree to build or decode one and livery.strongroom.check_name to validate a name on its own.
Classes:
| Name | Description |
|---|---|
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. |
Functions:
| Name | Description |
|---|---|
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 |
|---|---|---|
EntryKind |
What a digest-bearing entry names. |
|
NAME_BUDGET |
The most UTF-8 bytes one name may take. |
Entry
dataclass
¶
A blob or a subtree inside a tree.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
the portable name, one path component. |
kind |
EntryKind
|
|
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. |
__post_init__ ¶
Source code in packages/strongroom/src/livery/strongroom/_tree.py
to_json ¶
The entry as a JSON object.
Source code in packages/strongroom/src/livery/strongroom/_tree.py
Link
dataclass
¶
Tree
dataclass
¶
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. |
of
classmethod
¶
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
to_json ¶
from_json
classmethod
¶
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
decode
classmethod
¶
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
check_name ¶
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
check_target ¶
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. |