mergedeep

You can control how mergedeep handles overlapping keys and values by passing a strategy argument to the merge function. The available strategies are:

• Strategy.REPLACE (Default): Replaces the destination value with the source value.
• Strategy.ADDITIVE: Extends additive collection types (like list, tuple, set, and Counter) instead of replacing them.
• Strategy.TYPESAFE_REPLACE (or Strategy.TYPESAFE): Performs a replace merge but raises a TypeError if the destination and source values have different types.
• Strategy.TYPESAFE_ADDITIVE: Performs an additive merge but raises a TypeError if the destination and source values have different types.

Install the mergedeep package using pip to enable deep merging capabilities in your Python projects.

$ pip install mergedeep

Use Strategy.TYPESAFE_REPLACE or Strategy.TYPESAFE_ADDITIVE to ensure that merging only occurs between values of the same type. If a type mismatch is detected, a TypeError is raised.

from mergedeep import merge, Strategy

# Example: Typesafe Replace
dst = {"key": [1, 2]}
src = {"key": {3, 4}}

merge(dst, src, strategy=Strategy.TYPESAFE_REPLACE) 
# Raises: TypeError: destination type: <class 'list'> differs from source type: <class 'set'> for key: "key"

The REPLACE strategy is the default behavior. When keys are identical in both the destination and source, the value from the source (or the rightmost source in a multi-source merge) replaces the destination value.

from mergedeep import merge, Strategy

dst = {"key": [1, 2]}
src = {"key": [3, 4]}

merge(dst, src, strategy=Strategy.REPLACE) 
# same as: merge(dst, src)

print(dst)
# {"key": [3, 4]}

The ADDITIVE strategy extends the destination if both the destination and source values are the same additive collection type. Supported types include list, tuple, set, and Counter. If the types do not match, it falls back to REPLACE behavior.

from mergedeep import merge, Strategy
from collections import Counter

dst = {"key": [1, 2], "count": Counter({"a": 1, "b": 1})}
src = {"key": [3, 4], "count": Counter({"a": 1, "c": 1})}

merge(dst, src, strategy=Strategy.ADDITIVE) 

print(dst)
# {"key": [1, 2, 3, 4], "count": Counter({"a": 2, "b": 1, "c": 1})}

The merge function performs a deep merge of multiple mappings. It can be used to create a new merged dictionary without mutating the sources, or to merge sources into an existing destination dictionary.

Signature: merge(destination: MutableMapping, *sources: Mapping, strategy: Strategy = Strategy.REPLACE) -> MutableMapping

from mergedeep import merge

a = {"keyA": 1}
b = {"keyB": {"sub1": 10}}
c = {"keyB": {"sub2": 20}}

# Deep merge into a new dictionary without mutating a, b, or c
merged = merge({}, a, b, c) 
print(merged)
# {"keyA": 1, "keyB": {"sub1": 10, "sub2": 20}}

# Deep merge into an existing dictionary (mutates 'a')
merge(a, b, c) 
print(a)
# {"keyA": 1, "keyB": {"sub1": 10, "sub2": 20}}