State

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

class burr.core.state.State(initial_values: Dict[str, Any] = None)

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

__init__(initial_values: Dict[str, Any] = None)

append(**updates: Any) → State

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

Applies a given operation to the state, returning a new state

classmethod deserialize(json_dict: dict, **kwargs) → State

Converts a dictionary representing a JSON object back into a state

get_all() → Dict[str, Any]

Returns the entire state, realize as a dictionary. This is a copy.

increment(**updates: int) → State

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

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

Returns a subset of the state, with only the given keys

update(**updates: Any) → State

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, keep: list[str] = 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

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.