Store (revived.store) module documentation

This module implements the global state store, and the INIT action and action_creator. This is the entry point of the revived module.

Rationale behind the Store

revived.store.Store is the object that brings actions and reducers. The store has the following responsibilities:

• Holds application state;
• Allows access to state via revived.store.Store.get_state;
• Allows state to be updated via revived.store.Store.dispatch;
• Registers listeners via revived.store.Store.subscribe or revived.store.Store.subscriber decorator;
• Handles unregistering of listeners via the function returned by revived.store.Store.subscribe or via the property revived.store.Subscriber.unsubscribe of the revived.store.Subscriber instance.

It’s important to note that you’ll only have a single store in your application. When you want to split your data handling logic, you’ll use reducer composition instead of many stores.

Dispatch actions

To dispatch actions the revived.store.Store.dispatch method should be used, passing as parameter the result of an action_creator. See more in revived.action.action and revived.action.Action.

# create the store object
store = Store(root_reducer)

# register subscribers
# ...

# dispatch an action using the action_creator <an_action_creator>
store.dispatch(an_action_creator(a_parameter, another_parameter))

Subscribe and unsubscribe to state changes

There are two ways to subscribe and usubscribe to store changes: using the revived.store.Store.subscribe method or the revived.store.Store.subscriber decorator. Both approaches are equivalent and the choice should be just made based on your taste.

Subscribe using revived.store.Store.subscribe

# create the store object
store = Store(root_reducer)

# define the function
def a_subscriber():
    # do something!
    pass

# subscribe the function
unsubscribe = store.subscribe(a_subscriber)

# unsubscribe the function
unsubscribe()

Subscribe using revived.store.Store.subscriber

# create the store object
store = Store(root_reducer)

# define and subscribe the function
@store.subscriber
def a_subscriber():
    # do something!
    pass

# unsubscribe the function
a_subscriber.unsubscribe()

class revived.store.ActionType(*args, **kwargs)

Action types for the store module.

Basically the only type here is the INIT one. Reducers should wait for this action to create the initial state for the state subpath they are responsible of.

exception revived.store.DispatchInReducerError(*args, **kwargs)

Raised when revived.store.Store.dispatch is called in a reducer.

class revived.store.Store(reducer)

Container object for the global state.

This object is responsible of the global state. Its main responsibilities are:

• Keeping track of all the subscribers, and call them on state changes.
• Keeping reference to the reducer to be used and call it to properly handle state changes.

Creates the store, using the given function as reducer. At the beginning no callback is subscribed to store changes. It is possible to add subscribers later, while there is no way - at the moment - to replace the reducer.

Parameters:reducer (Union[Callable, Module]) – The root reducer. Return type:None

dispatch(action)

Dispatches an action.

This is the only piece of code responsible of dispatching actions. When an action is dispatched, the state is changed according to the defined root reducer and all the subscribers are called.

The calling order is not guaranteed.

Parameters:action (Action) – The action that should be dispatched. Raises:revived.store.DispatchInReducerError Return type:None

get_state()

Getter for the global state.

Return type:Any Returns:The global state contained into the store.

subscribe(callback)

Subscribes a callback to state changes.

Every time the state changes, the callback is called. No parameters are passed to the callback. It is responsibility of the callback to actually connect the store with the caller. The returned function can be called without arguments to unsubscribe the callback.

Parameters:callback (Callable) – The callback to be subscribed. Return type:Callable Returns:The unsubscribe function.

subscriber(callback)

Decorator function to subscribe a function to store changes.

The subscribed function will be called every time the internal state of the store changes.

NOTE: The decorator function will return the function itself. To unsubscribe the callback the user should use the revived.store.Subscriber.unsubscribe function attached into the callback.

Parameters:callback (Callable) – The callback to be subscribed. :returns: The callback itself. Return type:Subscriber Returns:The wrapping subscriber.

class revived.store.Subscriber(callback, unsubscribe)

Wrapper around a subscriber function with the unsubscribe property.

While creating a subscriber using the decorator it is not possible to return the unsubscribe function. So a revived.store.Subscriber is created wrapping the callback, that contains the revived.store.Subscriber.unsubscribe function to be used to properly unregister the subscriber.

Parameters:

• callback (Callable) – The callback to be wrapped into the subscriber.
• unsubscribe (Callable) – The unsubscribe function for the subscriber.

Return type:

None

unsubscribe

Property containing the unsubscribe function.

Returns:The unsubscribe function for the subscriber.

revived.store.init()

Action creator for the init action.