============
DICT-TOOLBOX
============

INSTALLATION
============
.. code-block:: bash

    pip install dict-toolbox

Contains various dict tools from the `Salt Project <https://github.com/saltstack/salt>`_.

Differ
======
.. code-block:: python

    from dict_tools import differ

deep_diff
---------
Computes the difference between to dictionaries.

recursive_diff
--------------
Computes the recursive difference between two dictionaries.

Trim
====
.. code-block:: python

    from dict_tools import trim

trim_dict
---------
Takes a dictionary and iterates over its keys, looking for
large values and replacing them with a trimmed string.


Update
======
.. code-block:: python

    from dict_tools import trim


update
------
Merges "upd" recursively into the target

merge_list
----------

merge_recurse
-------------

merge_aggregate
---------------

merge_overwrite
---------------

merge
-----

ensure_dict_key
---------------
Ensures that in_dict contains the series of recursive keys defined in keys.

set_dict_key_value
------------------
Ensures that in_dict contains the series of recursive keys defined in keys.
Also sets whatever is at the end of `in_dict` traversed with `keys` to `value`.

update_dict_key_value
---------------------
Ensures that in_dict contains the series of recursive keys defined in keys.
Also updates the dict, that is at the end of `in_dict` traversed with `keys`,
with `value`.

append_dict_key_value
---------------------
Ensures that in_dict contains the series of recursive keys defined in keys.
Also appends `value` to the list that is at the end of `in_dict` traversed
with `keys`.

extend_dict_key_value
---------------------
Ensures that in_dict contains the series of recursive keys defined in keys.
Also extends the list, that is at the end of `in_dict` traversed with `keys`,
with `value`.


XML
===
.. code-block:: python

    from dict_tools import xml

to_dict
-------
Convert an XML tree into a dict. The tree that is passed in must be an
ElementTree object.

YAMLEX
======
.. code-block:: python

    from dict_tools import yamlex

YAMLEX is a format that allows for things like sls files to be
more intuitive.

SLSMap
------
Ensures that dict str() and repr() are YAML friendly.

SLSString
---------
Ensures that str str() and repr() are YAML friendly.

AggregatedMap
-------------

AggregatedSequence
------------------

Dumper
------
sls dumper.

merge_recursive
---------------
Merge obj_b into obj_a.

MySQL
=====
.. code-block:: python

    from dict_tools import mysql

to_num
------
Convert a string to a number.


to_dict
-------
Convert MySQL-style output to a python dictionary.


DATA
====
.. code-block:: python

    from dict_tools import data

CaseInsensitiveDict
-------------------
Inspired by requests' case-insensitive dict implementation, but works with
non-string keys as well.

ImmutableDict
-------------
An immutable mapping that can access it's keys via the namespace

NamespaceDict
-------------
A dictionary that can access it's string keys through the namespace


compare_dicts
-------------
Compare before and after results from various functions, returning a
dict describing the chagnes that were made.

is_dictlist
-----------
Returns True if data is a list of one-element dicts (as found in many SLS schemas)

object_to_dict
--------------
Convert an arbitrary object to a dictionary

recursive_diff
--------------
Performs a recursive diff on mappings and/or iterables and returns the result
in a {'old': values, 'new': values}-style.
Compares dicts and sets unordered (obviously), OrderedDicts and Lists ordered
(but only if both ``old`` and ``new`` are of the same type),
all other Mapping types unordered, and all other iterables ordered.

repack_dictlist
---------------
Takes a list of one-element dicts (as found in many SLS schemas) and
repacks into a single dictionary.

subdict_match
-------------
Check for a match in a dictionary using a delimiter character to denote
levels of subdicts, and also allowing the delimiter character to be
matched. Thus, 'foo:bar:baz' will match data['foo'] == 'bar:baz' and
data['foo']['bar'] == 'baz'. The latter would take priority over the
former, as more deeply-nested matches are tried first.


traverse_dict
-------------
Traverse a dict using a colon-delimited (or otherwise delimited, using the
'delimiter' param) target string. The target 'foo:bar:baz' will return
data['foo']['bar']['baz'] if this value exists, and will otherwise return
the dict in the default argument.

traverse_dict_and_list
----------------------
Traverse a dict or list using a colon-delimited (or otherwise delimited,
using the 'delimiter' param) target string. The target 'foo:bar:0' will
return data['foo']['bar'][0] if this value exists, and will otherwise
return the dict in the default argument.
Function will automatically determine the target type.
The target 'foo:bar:0' will return data['foo']['bar'][0] if data like
{'foo':{'bar':['baz']}} , if data like {'foo':{'bar':{'0':'baz'}}}
then return data['foo']['bar']['0']

Arg
===
.. code-block:: python

    from dict_tools import arg

yamlify_arg
-----------
yaml.safe_load the arg


Aggregation
===========
.. code-block:: python

    from dict_tools import aggregation

Makes it possible to introspect dataset and aggregate nodes
when it is instructed


levelise
--------
Describe which levels are allowed to do deep merging.

mark
----
Convert obj into an Aggregate instance

aggregate
---------
Merge obj_b into obj_a.
