User Guide¶
Simple Usage¶
deepmerge was written as a library to help construct merge functions, eliminating some of the boilerplate around recursing through common data structures and joining results. Although it’s recommended to choose your own strategies, deepmerge does provided some preconfigured mergers for a common situations:
deepmerge.always_merger: always try to merge. in the case of mismatches, the value from the second object overrides the first o ne.
deepmerge.merge_or_raise: try to merge, raise an exception if an unmergable situation is encountered.
deepmerge.conservative_merger: similar to always_merger, but in the case of a conflict, use the existing value.
Once a merger is constructed, it then has a merge() method that can be called:
from deepmerge import always_merger
base = {"foo": "value", "baz": ["a"]}
next = {"bar": "value2", "baz": ["b"]}
always_merger.merge(base, next)
assert base == {
"foo": "value",
"bar": "value2",
"baz": ["a", "b"]
}
Merges are Destructive¶
You may have noticed from the example, but merging is a destructive behavior: it will modify the first argument passed in (the base) as part of the merge.
This is intentional, as an implicit copy would result in a significant performance slowdown for deep data structures. If you need to keep the original objects unmodified, you can use the deepcopy method:
from copy import deepcopy
result = deepcopy(base)
always_merger.merge(result, next)
Built-in Strategies¶
If you name a strategy with a string, it will attempt to match that with the merge strategies that are built into deepmerge. You can see a list of which strategies exist for which types at Strategies
Custom Strategies¶
Strategies are functions that satisfy the following properties:
have the function signature (config, path, base, nxt)
return the merged object, or None.
Example:
def append_last_element(config, path, base, nxt):
""" a list strategy to append the last element of nxt only. """
if len(nxt) > 0:
base.append(nxt[-1])
return base
If a strategy fails, an exception should not be raised. This is to ensure it can be chained with other strategies, or the fall-back.