Skip to content

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:~rn_forge.commons.lang.dataclasses.DataclassMixin subclass used to serialize and validate entries.

required
schema_version str

Written to the file and checked on load.

'1'
metadata Mapping[str, JsonValue] | None

Envelope fields written beside schema_version and entries — the generator's own version, a config hash, anything a consumer needs to decide whether the file is still current. Kept out of the entries so a metadata change never looks like drift in an artifact. Read back with :attr:metadata.

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 schema_version, or an entry fails entry_type.from_dict validation.

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()