TurnState Class
One state scope for a single turn.
Behaves like a dict but adds two things the loader relies on:
Dirty tracking — the loader compares the current contents to the loaded snapshot, so nested mutations are persisted without dirtying reads.
Sealing — at the end of a turn the scope is sealed; any later access raises TurnStateSealedError.
Values must be JSON-serializable. Each scope is encoded with
json.dumps when it is saved, so store only JSON-native types (str,
int, float, bool, None, list, dict). A non-serializable
value (e.g. a datetime or a custom object) is accepted on assignment but
raises TypeError later, when the turn is saved.
Constructor
TurnState(data: Mapping[str, Any] | None = None)Parameters
| Name | Description |
|---|---|
|
data
|
Default value: None
|
Methods
| mark_clean |
Mark the current contents as clean after a successful save. |
| seal |
Seal the scope; subsequent access raises TurnStateSealedError. |
| to_dict |
Return a shallow copy of the raw contents (used for serialization). Intentionally does not check the seal: the loader serializes a scope just before sealing it, and callers should not reach for this directly. |
mark_clean
Mark the current contents as clean after a successful save.
mark_clean() -> Noneseal
Seal the scope; subsequent access raises TurnStateSealedError.
seal() -> Noneto_dict
Return a shallow copy of the raw contents (used for serialization).
Intentionally does not check the seal: the loader serializes a scope just before sealing it, and callers should not reach for this directly.
to_dict() -> Dict[str, Any]Attributes
is_dirty
Whether the scope has been mutated since it was loaded.
is_empty
Whether the scope currently holds no keys.
is_sealed
Whether the scope has been sealed for the turn.