managedstate 5.0.0

State management inspired by Redux

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