livery.strongroom._groups¶
livery.strongroom._groups ¶
Groups of ref moves that land as a whole or not at all.
A group is one pending ref, pending/<id>, naming a manifest tree
whose entries are every move's target, so the sweep keeps them all
from the first move to the commit. The record's meta carries the
journal: the lease, the moves in order, and how many have been
applied. begin opens a group, add appends a move, commit checks
every move under the maintenance lease and the refs' locks, refuses
the whole group with nothing moved on the first refusal, then applies
the moves and drops the pending ref. A crash between two applies
leaves the journal with its count, and commit on the same id
replays it. retire abandons a group nothing of which has moved.
The single publish, livery.strongroom.Store.publish_begin and livery.strongroom.Store.publish_commit, shares the pending namespace and the move code but names its ref at commit, so its pending ref names the target itself and carries no journal.
The functions here are the bodies of the livery.strongroom.Store methods of the same names; reach for the methods, and for livery.strongroom.Store.transaction in everyday code.
Classes:
| Name | Description |
|---|---|
Move |
One ref move of a group. |
Group |
A group of moves that has begun and not yet committed. |
Transaction |
A group under a |
Functions:
| Name | Description |
|---|---|
is_group |
Whether a pending ref's record carries a group's journal. |
read_group |
The group under |
groups |
Every group that has begun and not committed, sorted by id. |
begin |
Open an empty group: a pending ref naming an empty manifest. |
add |
Append a move to the group, re-rooting its manifest. |
commit |
Apply every move, or none: check them all, then move them all. |
refuse_half_applied |
Refuse retiring a group a commit has already applied part of. |
transaction |
The body of livery.strongroom.Store.transaction. |
Attributes:
| Name | Type | Description |
|---|---|---|
after_apply |
Callable[[int], None]
|
Runs after each move of a commit is applied and journaled. |
after_apply
module-attribute
¶
Runs after each move of a commit is applied and journaled.
A variable, not a function, so the conformance harness can make a commit stop part-way, as a crash would, and put it back afterwards.
Move
dataclass
¶
Move(namespace: str, path: str, digest: Digest, previous: Digest | None, receipt: Digest | None = None, meta: dict[str, Value] = dict())
One ref move of a group.
Attributes:
| Name | Type | Description |
|---|---|---|
namespace |
str
|
a declared namespace. |
path |
str
|
the ref's path. |
digest |
Digest
|
what the ref names afterwards. |
previous |
Digest | None
|
what the ref is expected to name now; None to create. |
receipt |
Digest | None
|
the receipt of the moving call, if any. |
meta |
dict[str, Value]
|
the consumer's own object for the ref's record. |
Methods:
| Name | Description |
|---|---|
to_json |
The move as a JSON object, the journal's entry. |
from_json |
A move from a journal entry. |
to_json ¶
The move as a JSON object, the journal's entry.
Source code in packages/strongroom/src/livery/strongroom/_groups.py
from_json
classmethod
¶
A move from a journal entry.
Raises:
| Type | Description |
|---|---|
FormatError
|
when the entry is not a move. |
Source code in packages/strongroom/src/livery/strongroom/_groups.py
Group
dataclass
¶
Group(id: str, moves: tuple[Move, ...], applied: int, lease: int, manifest: Digest, record: RefRecord)
A group of moves that has begun and not yet committed.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
str
|
the pending ref's name under |
moves |
tuple[Move, ...]
|
the moves, in the order they apply. |
applied |
int
|
how many of them a commit has already applied; more than zero only after a commit stopped part-way. |
lease |
int
|
the seconds the group expected to take, from |
manifest |
Digest
|
the tree of every move's target the pending ref names. |
record |
RefRecord
|
the pending ref's record, the journal in its |
Transaction ¶
A group under a with: moves recorded as they come, the exit decides.
Entering begins the group. A clean exit commits it, every move or
none, and records then holds the records written. An exception
before the commit began retires the group, nothing moved. A
commit refused on its checks retires the group too, since nothing
moved, and the refusal is what the with raises. A commit that
stopped between two applies re-raises and leaves the group for a
later livery.strongroom.Store.commit on its id.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
the group's pending ref name, known after entry. |
|
records |
tuple[RefRecord, ...]
|
the records the commit wrote, in move order; empty until the commit. |
Methods:
| Name | Description |
|---|---|
move |
Record a move; the group's state after it. |
Source code in packages/strongroom/src/livery/strongroom/_groups.py
move ¶
move(namespace: str, path: str, digest: Digest, *, previous: Digest | None, receipt: Digest | None = None, meta: dict[str, Value] | None = None) -> Group
Record a move; the group's state after it.
Source code in packages/strongroom/src/livery/strongroom/_groups.py
is_group ¶
read_group ¶
The group under pending/<group_id>.
Raises:
| Type | Description |
|---|---|
NoSuchPending
|
when the pending ref does not exist. |
NotAGroup
|
when it is a single publish's. |
Source code in packages/strongroom/src/livery/strongroom/_groups.py
groups ¶
Every group that has begun and not committed, sorted by id.
Source code in packages/strongroom/src/livery/strongroom/_groups.py
begin ¶
Open an empty group: a pending ref naming an empty manifest.
Source code in packages/strongroom/src/livery/strongroom/_groups.py
add ¶
add(store: Store, group_id: str, namespace: str, path: str, digest: Digest, *, previous: Digest | None, receipt: Digest | None, meta: dict[str, Value] | None) -> Group
Append a move to the group, re-rooting its manifest.
Raises:
| Type | Description |
|---|---|
NoSuchPending
|
when the group does not exist. |
NotAGroup
|
when the pending ref is a single publish's. |
GroupHalfApplied
|
when a commit already applied part of it. |
MissingObject
|
when digest is not present here. |
RefConflict
|
when the group already moves that ref. |
UnknownNamespace
|
when the namespace was not declared. |
Source code in packages/strongroom/src/livery/strongroom/_groups.py
commit ¶
Apply every move, or none: check them all, then move them all.
Under the maintenance lease, so no sweep runs beside it, and the moved refs' locks in sorted order. Every move is checked first, the compare-and-swap and the namespace's class; the first refusal stops the group with nothing moved. Then each move applies in order and the journal's count advances, so a crash between two applies is replayed by the next commit: a ref that already names its digest is skipped. The pending ref is dropped last.
Returns:
| Type | Description |
|---|---|
RefRecord
|
One record per move, in order; the existing record where a |
...
|
move was already applied. |
Raises:
| Type | Description |
|---|---|
NoSuchPending
|
when the group does not exist. |
NotAGroup
|
when the pending ref is a single publish's. |
RefConflict
|
when a ref does not name its expected previous, or its class refuses the move; nothing has moved. |
LockTimeout
|
when a lease or a lock outlasts the timeout. |
Source code in packages/strongroom/src/livery/strongroom/_groups.py
refuse_half_applied ¶
Refuse retiring a group a commit has already applied part of.
Raises:
| Type | Description |
|---|---|
GroupHalfApplied
|
naming the moves applied; the group is finished by another commit, never dropped. |
Source code in packages/strongroom/src/livery/strongroom/_groups.py
transaction ¶
transaction(store: Store, *, by: Subject, lease: float) -> Generator[Transaction]
The body of livery.strongroom.Store.transaction.