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
orrevived.store.Store.subscriber
decorator; - Handles unregistering of listeners via the function returned by
revived.store.Store.subscribe
or via the propertyrevived.store.Subscriber.unsubscribe
of therevived.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)[source]¶ 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)[source]¶ Raised when
revived.store.Store.dispatch
is called in a reducer.
-
class
revived.store.
Store
(reducer)[source]¶ 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
[[Any
,Action
],Any
],Module
]) – The root reducer.-
dispatch
(action)[source]¶ 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
) – Theaction
that should be dispatched.Raises: revived.store.DispatchInReducerError
Return type: None
-
get_state
()[source]¶ Getter for the global state.
Return type: Any
Returns: The global state contained into the store.
-
subscribe
(callback)[source]¶ 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
[[],None
]) – The callback to be subscribed.Return type: Callable
[[],None
]Returns: The unsubscribe function.
-
subscriber
(callback)[source]¶ 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
[[],None
]) – The callback to be subscribed. :returns: The callback itself.Return type: Subscriber
Returns: The wrapping subscriber.
-
class
revived.store.
Subscriber
(callback, unsubscribe)[source]¶ 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 arevived.store.Subscriber
is created wrapping the callback, that contains therevived.store.Subscriber.unsubscribe
function to be used to properly unregister the subscriber.Parameters: - callback (
Callable
[[],None
]) – The callback to be wrapped into the subscriber. - unsubscribe (
Callable
[[],None
]) – The unsubscribe function for the subscriber.
-
unsubscribe
¶ Property containing the
unsubscribe
function.Return type: Callable
[[],None
]Returns: The unsubscribe
function for the subscriber.
- callback (