A dict subclass that observes a nested dict and listens for changes in its data structure. If a data change is registered, Dicta reacts with a callback or a data-export to a JSON file.
- Detect data changes in a nested dict
- Throw a callback, when the nested data structure changes
- Write data to a JSON file, when the nested data structure changes
- Easily import & export JSON files to/from a nested dict
- Behaves like a regular
dict
and supports alldict
,list
,tuple
andset
methods. - Supports nesting of all possible datatypes like
dict
,list
,tuple
,set
and other objects like custom classes. - Encodes non-serializable objects to a binary-string when writing data to a file (Optional / deactivated by default).
- Reading data from a file will decode a binary-string back to a non-serializable object (Optional / deactivated by default).
- Import/Insert additional data from json files.
- Export data to json files.
pip3 install dicta
import dicta
# Declare the 'Dicta' class.
dicta = dicta.Dicta()
# Activate binary serialization
dicta.setBinarySerializer(True)
# Set a synch file path.
dicta.synchFile("data.json")
# Define the callback method
def callback():
print("Data changed!")
print(dicta)
# Bind the callback method to dicta
dicta.bind(callback)
# Add data
dicta.importData({"key":"value"})
dicta.importData(key2=value2, key3=value3)
dicta["entities"] = {}
dicta["entities"]["persons"] = []
dicta["entities"]["persons"].append({"name":"john", "age":23})
dicta["entities"]["persons"].append({"name":"peter", "age":13})
# Update a key in a dict
dicta["entities"]["persons"][1]["age"] = 42
# Add another nested list to the dict
dicta["entities"]["animals"] = []
dicta["entities"]["animals"].append("lion")
dicta["entities"]["animals"].append("elephant")
# Slice item from list
del dicta["entities"]["animals"][0:1]
# Remove item from dict
dicta["entities"].pop("persons")
# and so forth…
# Should support all regular dict behaviours and
# list methods (pop(), append(), slice(), insert() …)
# Import additional data from another file.
# (New data will be added. Old data remains but will
# be overwritten if dict keys match.)
dicta.importFile("additional_data_file.json")
# Export the data to another file
dicta.exportFile("data_backup.json")
# Get string representation of the Dicta
dicta.stringify()
Dicta(*args, **kwargs)
Dicta(dict)
Dicta(key=value,key2=value)
A dict subclass.
- *args (Optional)
- **kwargs (Optional)
- Dicta Class
Dicta.bind(callback, response=False, *args, *kwargs)
Sets the callback method for the Dicta Class. If response=False
(default) the callback method only gets the *args, *kwargs
as parameters you define. If response=True
the callback method gets response from the Dicta Class. You should define your callback function with a *kwargs
parameter or with three positional parameters:
def my_callback(**kwargs)
or
def my_callback(modifed_object, modify_info, modify_trace)
- callback (method)
- default_response (bool) (optional / default = False)
- args as defined in setCallback (optional / default: None)
- kwargs as defined in setCallback (optional / default: None)
- modifed_object (object)
- modify_info (json_string): Contains info about the data mod
- modify_trace (list): Contains the dict-tree-path to the modified object as a list starting from root*
Dicta.syncFile(path, reset=False)
Sets the sync file to automatically store the data on data change. If reset=False
(default) old data will remain and will be updated with new data . If reset=True
the data wil be cleared when syncFile()
is called.
Data sync is monodirectional! Though the data is automatically synced to your syncfile data is not synced to your dicta instance if filedata changes. Use Dicta.sync() to pull data from file into your dict.
Sync will fail if your dict contains non-serializable objects and binary serialization is not activated. For security reasons this is deactivated by default. You can activate binary serialization manually with Dicta.useBinarySerializer(True)
.
If you activate the binary-serializer all non-serializable objects will be encoded to a binary string and packed into a dict
labeled with the key '<serialized-object>'
. See the reference for Dicta.useBinarySerializer()
.
- path (string)
- reset (bool) (optional / default = False)
Dicta.sync()
Pulls syncfile data into your Dicta instance.
Dicta.importFile(path)
Import data from a file. New data will be added to the DictObsercer, old data remains but will be overwritten if dict keys match.
- path (string)
Dicta.exportFile(path, reset=True)
Export data to a file. If reset=True
the data wil be cleared when exportFile()
(default) is called . If reset=False
the data will be updated.
This will fail if your dict contains non-serializable objects and binary serialization is not activated. For security reasons this is deactivated by default. You can activate binary serialization by calling Dicta.useBinarySerializer(True)
before.
If you activate the binary-serializer all non-serializable objects will be encoded to a binary string and packed into a dict
labeled with the key '<serialized-object>'
. See the reference for Dicta.useBinarySerializer()
.
- path (string)
- reset (bool) (optional / default = True)
Dicta.clearFile(path)
Clear a file.
- path (string)
Dicta.removeFile(path)
Remove a data file.
- path (string)
Dicta.importData(dict)
Dicta.importData(key=value,key2=value2…)
Import data as dict or key/value pairs.
Dicta.dictify()
Returns a plain dict representation of the data without Dicta functionality.
- None
- dict
Dicta.stringify(returnBinaries=False)
Returns a string representation of the data in Dicta.
This will fail if your dict contains non-serializable objects and binary serialization is not activated. For security reasons this is deactivated by default. You can activate binary serialization by calling Dicta.useBinarySerializer(True)
before.
If you activate the binary-serializer all non-serializable objects will be encoded to a binary string and packed into a dict
labeled with the key '<serialized-object>'
. See the reference for Dicta.useBinarySerializer()
.
For better readability serialized objects won´t be returned by default and are replaced by a the '<serialized-object>'
hook. If you want to return the binaries set the return_binaries
parameter to True
.
- return_binaries (bool) (default = False)
- string
Dicta.setBinarySerializer(binary_serializer=False, serializer_hook='<serialized-object>')
For security reasons binary serialization of non-serializable objects is deactivated by default. You can activate or deactivate binary serialization with this method (default=False).
If you activate the binary-serializer all non-serializable objects will be encoded to a binary string and packed into a dict labeled with the key '<serialized-object>'
. In case you need this key for your data structure, define a custom serializer-hook by using the serializer_hook
parameter (optional). If you don´t use the serializer_hook
parameter the default hook '<serialized-object>'
will be used.
- binary_serializer (bool) (default = False)
- serializer_hook (string) (optional / default = '<serialized-object>')
myDicta.setBinarySerializer(True)
myDicta.setBinarySerializer(True, '<my_serialzer_hook>')
Behaves like a regular nested dict and supports all data type methods. Adding, removing, modifiying and accessing of nested elements should work out of the box. For example:
NestedDict.update(*args, *kwargs)
NestedDict.clear()
NestedDict.pop(key)
NestedDict.popitem(key)
NestedDict.setdefault(key, default=None)
and so forth: keys(), iter() …
NestedList.append(item)
and so forth: pop()…
- os
- re
- json
- pickle