Deepmerge

Warnings

• breaking Deepmerge v2.0 dropped support for Python versions older than 3.8. Projects still using Python 3.7 or earlier must pin `deepmerge<2.0`.
  Fix: Upgrade your Python environment to 3.8+ or pin `deepmerge` to a version prior to 2.0 (e.g., `pip install 'deepmerge<2.0'`).
• breaking Version 2.0 introduced extensive type hinting. While this generally improves static analysis, if you have custom merge strategies or logic that relied on implicit type coercions or incorrect type assumptions, your code might now fail type checks or behave differently when used with type-aware tools like MyPy.
  Fix: Review any custom merge strategies or type-sensitive code after upgrading. Ensure your custom strategies correctly handle expected input and output types according to the new type hints.
• gotcha The default `always_merger.merge(destination, source1, source2, ...)` modifies the `destination` dictionary in-place. If you intend to preserve the original `destination` dictionary, you must provide a copy (e.g., `always_merger.merge({}, original_dict, new_data)` or `always_merger.merge(copy.deepcopy(original_dict), new_data)`).
  Fix: Always pass a fresh dictionary (`{}`) or a deep copy (`copy.deepcopy(original_dict)`) as the first argument if the original dictionary must remain unchanged.
• gotcha The default list merging strategy for `always_merger` is `list_extend_strategy`, which appends elements from the source list to the destination list. If you expect lists to be overwritten/replaced or merged differently, you need to configure a custom `Merger` instance.
  Fix: To replace lists, initialize `Merger` with an 'override' strategy for lists: `my_merger = Merger([(list, ['override'])])`. To customize further, define your own list strategy function.

Install

• pip install deepmerge Install stable version

Imports

• always_merger

  from deepmerge import always_merger

  The default, most commonly used merger instance for deep merging dictionaries.
• Merger

  from deepmerge import Merger

  Used to create custom merger instances with specific strategies for different data types.

Quickstart

This example demonstrates how to use the default `always_merger` to combine two dictionaries. Nested dictionaries are merged recursively, and lists are extended by default (elements from the second list are appended to the first). It's crucial to understand that `always_merger.merge(a, b)` modifies `a` in-place, so passing `{}`, `copy.copy(a)`, or `copy.deepcopy(a)` as the first argument is often necessary to prevent unintended side effects on the original dictionary.

from deepmerge import always_merger

dict1 = {
    "name": "Alice",
    "settings": {"theme": "dark", "notifications": True},
    "tags": ["user", "admin"]
}
dict2 = {
    "name": "Bob",
    "settings": {"notifications": False, "language": "en"},
    "tags": ["active"]
}

# By default, always_merger modifies the first dict passed (or a copy).
# To keep dict1 unchanged, merge into an empty dict or a deep copy of dict1.
merged_dict = always_merger.merge({}, dict1, dict2)

print(merged_dict)
# Expected output for tags: ['user', 'admin', 'active'] (default list_extend_strategy)
# Expected output for settings: {'theme': 'dark', 'notifications': False, 'language': 'en'}