Observed structures that calls callback functions on changes.
Project description
observedstruct
Observed structures that calls your functions on changes.
Install
observedstruct
supports Python 3.7, 3.8, and 3.9.
pip install observedstruct
API
observedstruct.ObservedOperation
These are the operations tracked by the structures:
ObservedOperation.Access
ObservedOperation.Add
ObservedOperation.Update
ObservedOperation.Remove
These values are sent to the callbacks.
get_item_for_reference(struct, reference)
Find an item inside a structure based on a reference list.
observedstruct.ObservedDict
__init__(initial, *, pre_callbacks=None, post_callbacks=None)
ObservedDict
can be instantiated with another dict
, and it will recursively turn all nested dictionaries and lists into observed structs as well (by using ObservedDict
and ObservedList
). pre_callbacks
are functions to be called before an operation takes place, and post_callbacks
are functions to be called after an operation takes place.
from observedstruct import ObservedDict
def pre_callback(struct, operation, reference, old_value, new_value):
pass
def post_callback(struct, operation, reference, old_value, new_value):
pass
d = ObservedDict(
{'a': 1},
pre_callbacks=[pre_callback],
post_callbacks=[post_callback],
)
d['b'] = 2
Callbacks are called with:
struct
: The structure in which the event is taking place. You can find the affected object in the structure by navigating to the reference list inreference
starting from thestruct
.operation
: One ofObservedOperation
.reference
: A list of references inside the structure that can be used to find the affected object. If the structure is a list, it will be an integer, and if it's a dictionary, it will the object used as key. It can be something like['a', 0]
for a dictionary that contains keya
which is a list, and the operation takes place at the first position in the list. You can use the utility functionget_item_for_reference
to find the object the reference refers to from inside callback functions.old_value
: The value that will be removed from the structure.new_value
: The value that will be added to the structure.
This class supports all operations a regular dictionary supports.
observedstruct.ObservedList
Same as the ObservedDict
class, but you instantiate this class with a list
.
Limitations
An observed structure can only belong inside one other observed structure. To allow for the callback functions to be found and to be called with the correct references, each nested observed structure stores a reference to its parent and where it can be found in the parent. If an observed structure belongs to more than one parent, then it will have those attributes replaced and one of the parents won't be reachable from the child.
Callbacks registered in nested structures will not be called. Once a structure belongs in another structure, only the callbacks from the root structure in the hierarchy are called. Because of this, the multiplication of lists does not work in ObservedList
, since that would make several instances of a nested structure happen inside a list, and the reference would be wrong for at least one of the occurrences.
Development
Clone the source code from GitHub, have all supported Python interpreters in your PATH
(we recommend that you use pyenv
to manage different Python interpreters and environments) and create a new virtual environment with poetry install
.
Run the tests with:
./run all-tests
To run a specific test:
./run test <test-address>
To make sure your code complies with our quality standards, run:
./run quality
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.
Source Distribution
Built Distribution
Hashes for observedstruct-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3d08f58fc71f28e2dc44eff59cdd22e4103da57415778f2041ff0911c5c2f96f |
|
MD5 | ce62dbd2a86288323bfdae5155f343ae |
|
BLAKE2b-256 | e6255a98045272782d62af093e7d3e6308382ed8efb568119ee44f7f932ae7a3 |