State management inspired by Redux
Project description
managedstate
State management inspired by Redux
Quickstart
Setup
from managedstate import State
initial_state = {
"first_key": [
{
"id": 1,
"second_key": True
},
{
"id": 2,
"second_key": False
}
]
}
state = State(initial_state=initial_state)
Getting the state
- The full state object
>>> state.get()
{'first_key': [{'id': 1, 'second_key': True}, {'id': 2, 'second_key': False}]}
- A sub-state object
>>> state.get(["first_key", 0, "second_key"], defaults=[[], {}, False])
True
- A sub-state object, using a query function
def id_is_1_query(first_key_list):
for index, obj in enumerate(first_key_list):
if obj["id"] == 1:
return index
>>> state.get(["first_key", KeyQuery(id_is_1_query), "second_key"], defaults=[[], {}, False])
True
Setting the state
- The full state object
>>> state.set({'first_key': [{'id': 3, 'second_key': True}, {'id': 4, 'second_key': False}]})
>>> state.get()
{'first_key': [{'id': 3, 'second_key': True}, {'id': 4, 'second_key': False}]}
- A sub-state object, using a query function
def get_id_key_query(target_id): # This will dynamically create the query we need, when we need it
def id_query(substate):
for index, obj in enumerate(substate):
if obj["id"] == target_id:
return index
return KeyQuery(id_query)
>>> state.set(False, ['first_key', get_id_key_query(3), 'second_key'], defaults=[[], {}])
>>> state.get()
{'first_key': [{'id': 3, 'second_key': False}, {'id': 4, 'second_key': False}]}
Functionality
Dependencies
The State class and the extensions in this package implement Extendable and Extension respectively, from objectextensions.
As such, applying extensions is done by calling the class method State.with_extensions()
and passing in the extension classes to be applied.
Example code:
from managedstate import State
from managedstate.extensions import Registrar
state = State.with_extensions(Registrar)()
Extensions
extensions.Registrar
Allows specific get and set operations to be registered under a shorthand label for ease of use later.
extensions.Listeners
Provides an easy way to attach observer methods that will be called immediately after set()
and/or get()
.
Data Classes
AttributeName(self, attribute_name: str)
An instance of this class should be provided as a path key when getting or setting the state,
to indicate that the next nesting level of the state should be accessed via an object attribute.
Note: As this class is used indirectly to determine the method of access into the state,
it should never be stored directly as a key within that state.
KeyQuery(self, path_key_getter: Callable[[Any], Any])
Instances of this class can be provided as path keys when getting or setting the state,
to indicate that the next nesting level of the state should be accessed via the path key returned
from its stored function.
The function will receive a copy of the state object at the current level of nesting
in order to determine what key to return.
extensions.PartialQuery(self, path_key_getter: Callable[[Any], Any])
Instances of this class can be provided as path keys only in Registrar.register_path()
.
When registered_get()
/registered_set()
is called with the relevant path label, the function provided below
will be called and passed one value from the custom query args list;
a valid path key or KeyQuery should be returned.
Properties
extensions.Registrar.registered_paths
Returns a copy of the current path registry.
Methods
State.get(self, path_keys: Iterable[Any] = (), defaults: Iterable[Any] = ())
Drills into the state object using the provided path keys in sequence.
Any time progressing further into the state object fails, a copy of the default value at the relevant index
of defaults is substituted in.
Returns a copy of the drilled-down state object.
The defaults
param may be provided any number of default values, and they will only be used as necessary.
State.set(self, value: Any, path_keys: Iterable[Any] = (), defaults: Iterable[Any] = ())
Drills into the state object using the provided path keys in sequence.
Any time progressing further into the state object fails, a copy of the default value at the relevant index
of defaults is substituted in.
The final path key is used as the index to store a copy of the provided value at
inside the drilled-down state object.
The defaults
param may be provided any number of default values, and they will only be used as necessary.
extensions.Registrar.register_path(self, registered_path_label: str, path_keys: Iterable[Any], defaults: Iterable[Any] = ())
Saves the provided path keys and defaults under the provided label, so that a custom get or set can be
carried out at later times simply by providing the label again in a call to registered_get()
or registered_set()
.
extensions.Registrar.get_shape(self, initial_state: Any = None)
Generates a default shape for the state, using the current registered paths.
Any registered paths containing PartialQuery objects are truncated for this purpose, as it is not possible
to determine what kind of value a PartialQuery object would provide to drill further into the state.
extensions.Registrar.registered_get(self, registered_path_label: str, custom_query_args: Iterable[Any] = ())
Calls get()
, passing in the path keys and defaults previously provided in register()
.
If any of these path keys are instances of PartialQuery, each will be called and passed one value from
the custom query args list and is expected to return a valid path key or KeyQuery.
extensions.Registrar.registered_set(self, value: Any, registered_path_label: str, custom_query_args: Iterable[Any] = ())
Calls set()
, passing in the path keys and defaults previously provided in register()
.
If any of these path keys are instances of PartialQuery, each will be called and passed one value from
the custom query args list and is expected to return a valid path key or KeyQuery.
extensions.Listeners.add_listener(self, method_name: str, listener: Callable[[dict], None])
Adds the provided listener to a set of callbacks for the specified method.
These callbacks will receive copies of the method return value and its arguments
in the form result, self, *args, **kwargs
.
extensions.Listeners.remove_listener(self, method_name: str, listener: Callable[[dict], None])
Removes the provided listener from the set of callbacks for the specified method.
Additional Info
- KeyQuery instances provided as path keys can return any valid path key, except another KeyQuery or a PartialQuery
- Similarly, PartialQuery instances can return any valid path key except for another PartialQuery (they can however return a KeyQuery)
- The data classes provided in this package are not designed to be stored inside the state object themselves. Doing so may result in unintended behaviour
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.