livery.strongroom._views¶
livery.strongroom._views ¶
The materialiser: the only route from a digest to a path.
view fills a directory from a tree, choosing the cheapest safe rung
per entry and recording which one it used; collect reads declared
outputs back into a tree, learning each blob's executable bit from
the caller, the file mode, the view's record, or the platform, in
that order; drop_view removes only what the record lists. A view is
a root while it lives, and a link never leaves it: an entry whose
target escapes is parked, and a collected link that escapes is
refused. prefetch warms everything one digest reaches, and shed
evicts local copies a named source holds, except what a live view
depends on.
The functions here are the bodies of the livery.strongroom.Store methods of the same names; reach for the methods.
Classes:
| Name | Description |
|---|---|
ViewEntry |
One path a view created, and how. |
ViewRecord |
A view: local state in the index, and a root while its directory exists. |
DropReport |
What dropping a view removed and what it left. |
ShedReport |
What a shed did. |
Functions:
| Name | Description |
|---|---|
new_view_id |
A fresh view id; the seam tests fix for a known name. |
view |
Fill at from the tree, cheapest safe rung per entry, and record it. |
views |
Every recorded view, by id. |
view_record |
The record of view_id, or None. |
retire_record |
Forget a view: its record goes, its paths are not touched. |
drop_view |
Remove what the record lists and nothing else; then forget the view. |
live_roots |
Every live view's tree; a view whose directory is gone is retired. |
collect |
Read the declared paths under at back into a tree, landing every object. |
prefetch |
Fetch digest and everything it reaches; the objects fetched, in order. |
shed |
Evict every local copy source holds, except what a live view depends on. |
source_holds |
Whether source has the object, by existence and never by trust. |
Attributes:
| Name | Type | Description |
|---|---|---|
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. |
|
ENTRY_RUNGS |
tuple[EntryRung, ...]
|
|
PATH_BUDGET
module-attribute
¶
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.
ENTRY_RUNGS
module-attribute
¶
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; |
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
|
Methods:
| Name | Description |
|---|---|
to_json |
The entry as a JSON object. |
from_json |
Decode an entry, refusing a rung outside the ladder. |
to_json ¶
The entry as a JSON object.
Source code in packages/strongroom/src/livery/strongroom/_views.py
from_json
classmethod
¶
Decode an entry, refusing a rung outside the ladder.
Source code in packages/strongroom/src/livery/strongroom/_views.py
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 |
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. |
entries
class-attribute
instance-attribute
¶
directories
class-attribute
instance-attribute
¶
encode ¶
encode() -> bytes
The record's canonical JSON bytes.
Source code in packages/strongroom/src/livery/strongroom/_views.py
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
depends_on ¶
The objects this view reads through the store's own files.
Source code in packages/strongroom/src/livery/strongroom/_views.py
DropReport
dataclass
¶
ShedReport
dataclass
¶
view ¶
view(store: Store, tree_digest: Digest, at: Path, *, writable: bool, allow_hardlink: bool) -> ViewRecord
Fill at from the tree, cheapest safe rung per entry, and record it.
Source code in packages/strongroom/src/livery/strongroom/_views.py
views ¶
views(store: Store) -> list[ViewRecord]
Every recorded view, by id.
A record another process retires between the listing and the read is left out: that view is forgotten already.
Source code in packages/strongroom/src/livery/strongroom/_views.py
view_record ¶
view_record(store: Store, view_id: str) -> ViewRecord | None
retire_record ¶
Forget a view: its record goes, its paths are not touched.
drop_view ¶
drop_view(store: Store, view_id: str) -> DropReport
Remove what the record lists and nothing else; then forget the view.
Source code in packages/strongroom/src/livery/strongroom/_views.py
live_roots ¶
Every live view's tree; a view whose directory is gone is retired.
Source code in packages/strongroom/src/livery/strongroom/_views.py
collect ¶
Read the declared paths under at back into a tree, landing every object.
Source code in packages/strongroom/src/livery/strongroom/_views.py
prefetch ¶
Fetch digest and everything it reaches; the objects fetched, in order.
Source code in packages/strongroom/src/livery/strongroom/_views.py
shed ¶
shed(store: Store, source: Source) -> ShedReport
Evict every local copy source holds, except what a live view depends on.
Source code in packages/strongroom/src/livery/strongroom/_views.py
source_holds ¶
Whether source has the object, by existence and never by trust.