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