2. Usage

2.1. Principle

The principle is quite simple, just as a dictionary can be the value of a dictionary key. If it is a dictionary, a NestedDictionary is necessarily the value of the key of a NestedDictionary, and so on.

However, unlike a conventional dictionary, nested keys will be exposed as tuples. Even so, they can still be used as conventional keys.

$ a = NestedDictionary({'first': 1,
                        'second': {'1': "2:1", '2': "2:2", '3': "3:2"},
                        'third': 3,
                        'fourth': 4})

a's keys are :
[('first',), ('second', '1'), ('second', '2'), ('second', '3'), ('third',), ('fourth',)]

$ a['second']['1'] = "2:1"

2.2. Behavior

Nested dictionaries inherit from defaultdict. The default_factory attribute characterizes the behavior of this class:

If the nested dictionary is to behave strictly like a dictionary, then the default_factory attribute is set to None. If you request the value of a key that doesn’t exist, you’ll get a KeyError. The configuration parameter is strict=True

>>> from ndict_tools import NestedDictionary
>>> nd = NestedDictionary({'first': 1,
                           'second': {'1': "2:1", '2': "2:2", '3': "3:2"},
                           'third': 3,
                           'fourth': 4},
                           strict=True)
nd.default_factory

>>> nd['fifth']
Traceback (most recent call last):
  File "/snap/pycharm-professional/401/plugins/python/helpers/pydev/pydevconsole.py", line 364, in runcode
    coro = func()
  File "<input>", line 1, in <module>
KeyError: 'fifth'

If the nested dictionary is to have flexible behavior, then the default_factory attribute is set to NestedDictionary. If you request a key that doesn’t exist, a NestedDictionary instance will be created accordingly and returned. The configuration parameter is strict=False or no parameter

>>> from ndict_tools import NestedDictionary
>>> nd = NestedDictionary({'first': 1,
                           'second': {'1': "2:1", '2': "2:2", '3': "3:2"},
                           'third': 3,
                           'fourth': 4},
                           strict=False)
>>> nd.default_factory
<class 'ndict_tools.core.NestedDictionary'>
>>> nd['fifth']
NestedDictionary(<class 'ndict_tools.core.NestedDictionary'>, {})

And with no parameter

>>> from ndict_tools import NestedDictionary
>>> nd = NestedDictionary({'first': 1,
                           'second': {'1': "2:1", '2': "2:2", '3': "3:2"},
                           'third': 3,
                           'fourth': 4})
>>> nd.default_factory
<class 'ndict_tools.core.NestedDictionary'>
>>> nd['fifth']
NestedDictionary(<class 'ndict_tools.core.NestedDictionary'>, {})

2.3. Examples

$ a = NestedDictionary({'first': 1,
                        'second': {'1': "2:1", '2': "2:2", '3': "3:2"},
                        'third': 3,
                        'fourth': 4})
$ b = NestedDictionary(zip(['first', 'second', 'third', 'fourth'],
                           [1, {'1': "2:1", '2': "2:2", '3': "3:2"}, 3, 4]))
$ c = NestedDictionary([('first', 1),
                        ('second', {'1': "2:1", '2': "2:2", '3': "3:2"}),
                        ('third', 3),
                        ('fourth', 4)])
$ d = NestedDictionary([('third', 3),
                        ('first', 1),
                        ('second', {'1': "2:1", '2': "2:2", '3': "3:2"}),
                        ('fourth', 4)])
$ e = NestedDictionary([('first', 1), ('fourth', 4)],
                       third = 3,
                       second = {'1': "2:1", '2': "2:2", '3': "3:2"})

a == b == c == d == e

2.4. Class attributes and methods

class ndict_tools.NestedDictionary(*args, **kwargs)

Nested dictionary class.

This class is designed as a stacked dictionary. It represents a nest of dictionaries, that is to say that each key is a value or a nested dictionary. And so on…

This function initializes a nested dictionary.

Parameters:
  • args (Iterable) – the first one of the list must be a dictionary to instantiate an object.

  • kwargs (dict) –

    enrichments settings and

    • indent : indentation of the printable nested dictionary (used by json.dumps() function)

    • strict : strict mode (False by default) define default answer to unknown key

Example

NestedDictionary({'first': 1,'second': {'1': "2:1", '2': "2:2", '3': "3:2"}, 'third': 3, 'fourth': 4})

NestedDictionary(zip(['first','second', 'third', 'fourth'], [1, {'1': "2:1", '2': "2:2", '3': "3:2"}, 3, 4]))

NestedDictionary([('first', 1), ('second', {'1': "2:1", '2': "2:2", '3': "3:2"}), ('third', 3), ('fourth', 4)])

indent: int = 0

indent is used to print the dictionary with json indentation

default_factory

Factory for default value called by __missing__().

update()

Updates a stacked dictionary with key/value pairs.

Parameters:

dictionary (dict) – a simple dict.

Returns:

None

occurrences()

Returns the Number of occurrences of a key in a stacked dictionary including 0 if the key is not a keys in a stacked dictionary.

Parameters:

key (Any) – A possible key in a stacked dictionary.

Returns:

Number of occurrences or 0

Return type:

int

is_key()

Checks if a key is stacked or not.

Parameters:

key (Any) – A possible key in a stacked dictionary.

Returns:

True if key is a stacked key, False otherwise

Return type:

bool

key_list()

returns the list of unpacked keys containing the key from the stacked dictionary. If the key is not in the dictionary, it raises StackedKeyError (not a key).

Parameters:

key (Any) – a possible key in a stacked dictionary.

Returns:

A list of unpacked keys containing the key from the stacked dictionary.

Return type:

list

Raises:

StackedKeyError – if a key is not in a stacked dictionary.

items_list()

returns the list of unpacked items associated to the key from the stacked dictionary. If the key is not in the dictionary, it raises StackedKeyError (not a key).

Parameters:

key (Any) – a possible key in a stacked dictionary.

Returns:

A list of unpacked items associated the key from the stacked dictionary.

Return type:

list

Raises:

StackedKeyError – if a key is not in a stacked dictionary.

to_dict()

This method converts a nested dictionary to a classical dictionary

Returns:

a dictionary

Return type:

dict