MeldDict badge

A dict subclass that supports adding and subtracting other Mappings to perform recursive merging and removal.

By default, lists are also melded, but this can be configured. You can also have keys whose values are empty after a subtraction dropped automatically.

The full documentation is available online at: https://melddict.readthedocs.io/

Examples

You can add two mappings together to combine them:

meld_dict = MeldDict({'a': 'a',
                      'b': [1, 2],
                      'c': {'1': 1},
                      'd': 'd'})
norm_dict = {'b': [3, 4],
             'c': {'2': 2},
             'd': 'D',
             'e': 'e'}
meld_res = meld_dict + norm_dict
meld_res == {'a': 'a',
             'b': [1, 2, 3, 4],
             'c': {'1': 1, '2': 2},
             'd': 'D',
             'e': 'e'}
meld_dict += norm_dict  # a.k.a. meld_dict.add(norm_dict)
meld_dict == meld_res

You can also subtract one mapping from another:

meld_dict = MeldDict({'a': 'a',
                      'b': [1, 2],
                      'c': {'1': 1, '2': 2},
                      'd': 'd'})
norm_dict = {'b': [2, 3],
             'c': {'2': 2, '3': 3},
             'd': 'D',
             'e': 'e'}
meld_res = meld_dict - norm_dict
meld_res == {'a': 'a',
             'b': [1],
             'c': {'1': 1}}
meld_dict -= norm_dict  # a.k.a. meld_dict.subtract(norm_dict)
meld_dict == meld_res

Documentation

class melddict.MeldDict

Bases: dict

A dict subclass which supports adding and subtracting.

add(other)

Recursively merge another Mapping into this one, adding to or replacing the existing key / values.

Corresponding values which are both Mappings will be converted to a MeldDict and added (i.e., recursively).

Corresponding values that are both Iterable (but not strings) will be added or replaced according to meld_iters.

Otherwise, corresponding values will be replaced. Non-corresponding values from the other Mapping will be inserted into this one.

You can also perform addition using the forward, reverse, and in-place operators:

meld_dict = MeldDict({...})
norm_dict = {...}

meld_dict + norm_dict
norm_dict + meld_dict
meld_dict += norm_dict
norm_dict += meld_dict
meld_iters = True

Whether or not to meld Iterables as well.

When adding, corresponding values which are both Iterable are converted to a list of all the items. When subtracting, corresponding values which are both Iterable are converted to a list with common items removed, while other items are ignored. Corresponding values where the types don’t match are replaced or ignored.

remove_emptied = False

Whether or not to remove Mappings or Iterables that are completely empty after subtraction.

subtract(other)

Recursively subtract another Mapping from this one, removing corresponding the existing key / values.

Corresponding values which are both Mappings will be converted to a MeldDict and subtracted.

Corresponding values that are both Iterable (but not strings) will be subtracted or not according to meld_iters.

Otherwise, corresponding keys will be deleted. Non-corresponding keys will be ignored.

You can also perform subtraction using the forward, reverse, and in-place operators:

meld_dict = MeldDict({...})
norm_dict = {...}

meld_dict - norm_dict
norm_dict - meld_dict
meld_dict -= norm_dict
norm_dict -= meld_dict