State
rn_forge.commons.fs.state
Locked, atomically written, JSON-backed state storage.
StateStore(path, *, entry_type, schema_version='1', metadata=None)
A locked, atomically-written, JSON-backed key -> entry store.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
The state file. |
required |
entry_type
|
type[E]
|
A :class: |
required |
schema_version
|
str
|
Written to the file and checked on load. |
'1'
|
metadata
|
Mapping[str, JsonValue] | None
|
Envelope fields written beside |
None
|
metadata
property
The envelope metadata on disk, or the configured metadata if absent.
When the state file exists, this returns the last writer's metadata.
Raises:
| Type | Description |
|---|---|
AppException
|
The file is unreadable or is not the expected shape. |
get(key)
Return the entry for key, or None if it does not exist.
load()
Load and validate every entry, returning {} when the file is absent.
Raises:
| Type | Description |
|---|---|
AppException
|
The file is unreadable, is not the expected shape,
carries an unexpected |
locked()
Serialize read-modify-write cycles against other processes.
If flock is unavailable, the update proceeds without a lock.
record(key, entry)
Record a single entry. One read-modify-write cycle; see :meth:record_many.
record_many(entries)
Record several entries in a single read-modify-write cycle.
remove(key)
Remove key's entry, if present.
render(payload)
staticmethod
Serialise payload with sorted keys, two-space indent, and one newline.
replace_all(entries)
Replace the whole entry set with entries in one write.
stale_keys(exists=lambda key: Path(key).exists())
Return recorded keys for which exists returns False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
exists
|
Callable[[str], bool]
|
A predicate deciding whether a key still refers to something real. Defaults to treating keys as filesystem paths; pass a different predicate when keys are something else (e.g. artifact ids). |
lambda key: exists()
|