:py:mod:`sovabids.dicts`
========================

.. py:module:: sovabids.dicts

.. autoapi-nested-parse::

   Module with dictionary utilities.



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   sovabids.dicts.deep_get
   sovabids.dicts.deep_merge_N
   sovabids.dicts.deep_merge
   sovabids.dicts.flatten
   sovabids.dicts.nested_notation_to_tree



.. py:function:: deep_get(dictionary, keys, default=None, sep='.')

   Safe nested dictionary getter.

   :param dictionary: The dictionary from which to get the value.
   :type dictionary: dict
   :param keys: The nested keys using sep as separator.
                Ie: 'person.name.lastname' if `sep`='.'
   :type keys: str
   :param default: The default value to return if the key is not found
   :type default: object
   :param sep: The separator to indicate nesting/branching/hierarchy.
   :type sep: str, optional

   :returns: The value of the required key. `default` if the key is not found.
   :rtype: object

   .. rubric:: Notes

   Taken from https://stackoverflow.com/a/46890853/14068216


.. py:function:: deep_merge_N(l)

   Merge the list of dictionaries, such that the latest one has the greater precedence.

   :param l: List containing the dictionaries to be merged, having precedence on the last ones.
   :type l: list of dict

   :returns: The merged dictionary.
   :rtype: dict


.. py:function:: deep_merge(a, b)

   Merge two values, with `b` taking precedence over `a`.

   Semantics:
   - If either `a` or `b` is not a dictionary, `a` will be returned only if
     `b` is `None`. Otherwise `b` will be returned.
   - If both values are dictionaries, they are merged as follows:
       * Each key that is found only in `a` or only in `b` will be included in
         the output collection with its value intact.
       * For any key in common between `a` and `b`, the corresponding values
         will be merged with the same semantics.

   From David Schneider answer at https://stackoverflow.com/questions/7204805/how-to-merge-dictionaries-of-dictionaries/15836901#15836901

   :param a:
   :type a: object
   :param b:
   :type b: object

   :returns: Merged dictionary.
   :rtype: dict


.. py:function:: flatten(d, parent_key='', sep='.')

   Flatten the nested dictionary structure using the given separator.

   If parent_key is given, then that level is added at the start of the tree.

   :param d: The dictionary to flat.
   :type d: dict
   :param parent_key: The optional top-level field of the dictionary.
   :type parent_key: str, optional
   :param sep: The separator to indicate nesting/branching/hierarchy.
   :type sep: str, optional

   :returns: A dictionary with only one level of fields.
   :rtype: dict


.. py:function:: nested_notation_to_tree(key, value, leaf='.')

   Create a nested dictionary from the single (key,value) pair, with the key being branched by the leaf separator.

   :param key: The key/field to be nested, assuming nesting is represented with the "leaf" parameters.
   :type key: str
   :param value: The value that it will have at the last level of nesting.
   :type value: object
   :param leaf: The separator used to indicate nesting in "key" parameter.
   :type leaf: str, optional

   :returns: Nested dictionary.
   :rtype: dict