State¶

Use the state API to manipulate the state of the application.

class burr.core.state.State( initial_values: Dict[str, Any] | None = None, typing_system: TypingSystem[StateType] | None = None, )¶

An immutable state object. This is the only way to interact with state in Burr.

__init__( initial_values: Dict[str, Any] | None = None, typing_system: TypingSystem[StateType] | None = None, )¶

append(**updates: Any) → State[StateType]¶

Appends to the state with a set of key-value pairs. Each one must correspond to a list-like object, or an error will be raised.

This is an upsert operation, meaning that if the key does not exist, a new list will be created with the value in it.

state = State({"a": [1]})
state.append(a=2)  # State({"a": [1, 2]})

Parameters:: updates – updates to apply
Returns:: new state object

apply_operation( operation: StateDelta, ) → State[StateType]¶: Applies a given operation to the state, returning a new state

classmethod deserialize(json_dict: dict, **kwargs) → State[StateType]¶: Converts a dictionary representing a JSON object back into a state

extend(**updates: list[Any]) → State[StateType]¶

Extends the state with a set of key-value pairs. Each one must correspond to a list-like object, or an error will be raised.

This is an upsert operation, meaning that if the key does not exist, a new list will be created and extended with the values.

state = State({"a": [1]})
state.extend(a=[2, 3])  # State({"a": [1, 2, 3]})

Parameters:: updates – updates to apply
Returns:: new state object

get_all() → Dict[str, Any]¶: Returns the entire state, realize as a dictionary. This is a copy.

increment(**updates: int) → State[StateType]¶

Increments the state with a set of key-value pairs. Each one must correspond to an integer, or an error will be raised.

Parameters:: updates – updates to apply
Returns:: new state object

merge(other: State) → State[StateType]¶: Merges two states together, overwriting the values in self with those in other.

serialize(**kwargs) → dict¶: Converts the state to a JSON serializable object

subset( *keys: str, ignore_missing: bool = True, ) → State[StateType]¶: Returns a subset of the state, with only the given keys

update(**updates: Any) → State[StateType]¶

Updates the state with a set of key-value pairs Does an upsert operation (if the keys exist their value will be overwritten, otherwise they will be created)

state = State({"a": 1})
state.update(a=2, b=3)  # State({"a": 2, "b": 3})

Parameters:: updates – Updates to apply
Returns:: A new state with the updates applied

wipe(delete: list[str] | None = None, keep: list[str] | None = None)¶

Wipes the state, either by deleting the keys in delete and keeping everything else: or keeping the keys in keep. and deleting everything else. If you pass nothing in it will delete the whole thing.

Parameters:

delete – Keys to delete
keep – Keys to keep

Returns:

A new state object

with_typing_system( typing_system: TypingSystem[AssignedStateType], ) → State[AssignedStateType]¶: Copies state with a specific typing system

Custom field level serialization and deserialization¶

Use the following to register custom field level serialization and deserialization functions. Note: this registration is global for any state field with the same name.

burr.core.state.register_field_serde(field_name: str, serializer: Callable, deserializer: Callable)¶

Registers a custom serializer + deserializer for a field globally.

This is useful for really controlling how a field is serialized and deserialized for tracking / persistence.

def my_field_serializer(value: MyType, **kwargs) -> dict:
    serde_value = _do_something_to_serialize(value)
    return {"value": serde_value}

def my_field_deserializer(value: dict, **kwargs) -> MyType:
    serde_value = value["value"]
    return _do_something_to_deserialize(serde_value)

register_field_serde("my_field", my_field_serializer, my_field_deserializer)

Parameters:

field_name – The name of the field to register the serializer for.
serializer – A function that takes the field value and returns a JSON serializable object.
deserializer – A function that takes the JSON serializable object and returns the field value.