Welcome to SigmaEpsilon.DeepDict’s documentation!#

Version: 1.2.2

Useful links: User Guide | API Reference | Source Repository

This is a lightweight Python library to manage nested dictionaries with parent-child relationships. The self replicating default factory makes the creation of complex nested layouts effortless using the DeepDict class. The library also provides a collection of useful algoritms for parsing of nested dictionaries. This architecture of data is utilized in many SigmaEpsilon projects.

Below you can find a small set of examples to get your attention. If you are interested, take a look at the User Guide and the API Reference.

Installation#

You can install the project from PyPI with pip:

$ pip install sigmaepsilon.deepdict

Motivating examples#

Let say you have the following dictionary:

>>> d = {
...   "a" : {"aa" : 1},
...   "b" : 2,
...   "c" : {"cc" : {"ccc" : 3}},
... }

This is what happens when you iterate through the values of it:

>>> list(d.values())
[{'aa': 1}, 2, {'cc': {'ccc': 3}}]

Everything goes as expected, the values of the dictionary are put into a list. See what happens if you use a DeepDict instead:

>>> from sigmaepsilon.deepdict import DeepDict
>>> dd = DeepDict.wrap(d)
>>> list(dd.values(deep=True))
[1, 2, 3]

You see that by using the argument deep=True, the DeepDict instance goes into nested dictionaries and returns all the leafs. This way, the output [1, 2, 3] becomes independet from the layout of your dictionary. It could have as many nested levels as you want and still, it would always return only the leafs.

Another example for a possible use case is when you have to create a dictionary from dynamic content, possibly only being realized at runtime. Let say we have a function that accepts two arguments. The set of arguments for which the function have to be executed, is only known at runtime. Take this case for example:

>>> categories = ["A", "B", "C"]
>>> subcategories = ["1", "2", "3"]
...
>>> def foo(cat, subcat):
...     # this is where you do your business
...     return "-".join([cat, subcat])

If you wanted to store the results using standard dictionaries, this is what you would do (or something close to it):

>>> data = dict()
>>> for cat in category:
...     if cat not in data:
...         data[cat] = dict()
...     for subcat in subcategory:
...         if subcat not in data[cat]:
...             data[cat][subcat] = dict()
...         data[cat, subcat] = foo(cat, subcat)
>>> data["A"]["1"]
"A-1"

In contrast, if you use a DeepDict, you can utilize the adopted indexing mechanism, which makes using them feel like if they were arrays. Also, you don’t have to worry about KeyErrors here. De default factory handles everything for you.

>>> data = DeepDict()
>>> for cat in category:
...     for subcat in subcategory:
...         data[cat, subcat] = foo(cat, subcat)  # data[cat][subcat] would also work
>>> data["A", "1"]  # data["A"]["1"] would also work
"A-1"

In fact, you can assign values as deep as you want:

>>> data = DeepDict()
>>> data["a", 0, "b", 1, (5, 6)] = 10

Projects using DeepDict#

The following projects all build on the DeepDict class:

Note

If you are using this library and you want your stuff to be listed here, get in contact with one of the maintainers of the project.

Contents#

Indices and tables#