3. Package reference

For greater convenience, the modules remain hidden inside the package. These modules are exposed for development purposes only.

3.1. Exceptions

This module provides specific exception classes for nested dictionaries. These exceptions extend the standard Exception, KeyError and AttributeError classes for future developments.

exception ndict_tools.exception.StackedAttributeError: This exception is raised when a key is not compatible with stacked dictionary attributes.

exception ndict_tools.exception.StackedDictionaryError(message: str | None = None, error: int = 0)

Exception raised when a stacked dictionary is invalid.

StackedDictionaryError exception class.

Parameters:

message (str) – a message describing the error.
error (int) – an integer describing the error.

Raises:

None

exception ndict_tools.exception.StackedKeyError: Exception raised when a key is not compatible with a stacked dictionary.

exception ndict_tools.exception.NestedDictionaryException(message: str | None = None, error: int = 0)

Raised when a nested dictionary is invalid.

StackedDictionaryError exception class.

Parameters:

message (str) – a message describing the error.
error (int) – an integer describing the error.

Raises:

None

3.2. Tools

This module provides an intermediate technical class and tools for manipulating nested dictionaries.

Although this module is hidden from the package’s external view, its contents are important. The _StackedDict object class orchestrates the basic attributes, functions and methods required to initialize and manage nested dictionaries.

This class could have been eliminated in favor of building all methods and tools into the main module containing the NestedDictionary object class. However, this choice will enable us to build stacks of different dictionaries in the future, without necessarily using the properties specific to these dictionaries.

ndict_tools.tools.unpack_items()

This functions de-stacks items from a nested dictionary

Parameters:: dictionary (dict)
Returns:: generator that yields items from a nested dictionary
Return type:: Generator

ndict_tools.tools.from_dict()

This recursive function is used to transform a dictionary into a stacked dictionary.

This function enhances and replaces the previous from_dict() function in core module of this package. It allows you to create an object subclasses of a _StackedDict with initialization options if requested and attributes to be set.

Parameters:

dictionary (dict) – dictionary to transform
class_name (object) – name of the class to return
class_options (dict) –
options to pass to the class or attributes of the class to be set
- init : parameters to initialize instances of the class, this should be from __init__ function of the class
- attributes : attributes to set the class attributes

Returns:

stacked dictionary or of subclasses of _StackedDict

Return type:

_StackedDict

Raises:

StackedKeyError – if attribute called is not an attribute of the hierarchy of classes

class ndict_tools.tools._StackedDict(*args, **kwargs)

This class is an internal class for stacking nested dictionaries. This class is technical and is used to manage the processing of nested dictionaries. It inherits from defaultdict.

At instantiation, it has two mandatory parameters for its creation:

indent, which is used to format the object’s display.

default, which initializes the default_factory attribute of its parent class defaultdict.

These parameters are passed using the kwargs dictionary.

Parameters:

args (iterator)
kwargs (dict)

indent: int = 0: indent is used to print the dictionary with json indentation

default_factory: Factory for default value called by __missing__().

__str__()

Override __str__ to converts a nested dictionary to a string in json like format

Parameters:: padding (int) – whitespace indentation of dictionary content
Returns:: a string in json like format
Return type:: str

__copy__()

Override __copy__ to create a shallow copy of a stacked dictionary.

Returns:: a shallow copy of a stacked dictionary
Return type:: _StackedDict or a subclass of _StackedDict

__deepcopy__()

Override __deepcopy__ to create a complete copy of a stacked dictionary.

Returns:: a complete copy of a stacked dictionary
Return type:: _StackedDict or a subclass of _StackedDict

__setitem__()

Override __setitem__ to handle hierarchical keys.

Parameters:

key (object) – key to set
value (object) – value to set

Returns:

None

Return type:

None

Raises:

TypeError – if a nested list is found within the key

__getitem__()

Override __getitem__ to handle hierarchical keys.

Parameters:: key (object) – key to set
Returns:: value
Return type:: object
Raises:: TypeError – if a nested list is found within the key

__delitem__()

Override __delitem__ to handle hierarchical keys.

Parameters:: key (object) – key to set
Returns:: None
Return type:: None

unpacked_items()

This method de-stacks items from a nested dictionary. It calls internal unpack_items() function.

Returns:: generator that yields items from a nested dictionary
Return type:: Generator

unpacked_keys()

This method de-stacks keys from a nested dictionary and return them as keys. It calls internal unpack_items() function.

Returns:: generator that yields keys from a nested dictionary
Return type:: Generator

unpacked_values()

This method de-stacks values from a nested dictionary and return them as values. It calls internal unpack_items() function.

Returns:: generator that yields values from a nested dictionary
Return type:: Generator

to_dict()

This method converts a nested dictionary to a classical dictionary

Returns:: a dictionary
Return type:: dict

update()

Updates a stacked dictionary with key/value pairs.

Parameters:

kwargs (dict) – key/value pairs where values are _StackedDict instances.

Returns:

None

Raises:

StackedKeyError – if any of the key/value pairs cannot be updated:
KeyError – if key/value are missing or invalid.

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

3.3. Core

This module provides tools and class for creating nested dictionaries, since standard python does not have nested dictionaries.

class ndict_tools.core.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)])

__str__()

Override __str__ to converts a nested dictionary to a string in json like format

Parameters:: padding (int) – whitespace indentation of dictionary content
Returns:: a string in json like format
Return type:: str

update()

Updates a stacked dictionary with key/value pairs.

Parameters:: dictionary (dict) – a simple dict.
Returns:: None