{"id":779,"library":"mergedeep","title":"mergedeep","description":"mergedeep is a Python library providing a deep merge function for dictionaries and other mutable mappings. It offers flexible strategies for handling conflicts, including replacement (default), additive merging for collections like lists, and type-safe replacement. The current version is 1.3.4, and the library is actively maintained with regular releases.","status":"active","version":"1.3.4","language":"python","source_language":"en","source_url":"https://github.com/clarketm/mergedeep","tags":["merge","dictionary","deep-merge","utility","config","data-structure"],"install":[{"cmd":"pip install mergedeep","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The primary merge function `merge` is typically imported directly.","wrong":"import mergedeep; mergedeep.merge(...)","symbol":"merge","correct":"from mergedeep import merge"},{"note":"Import `Strategy` enum if custom merge strategies are needed.","symbol":"Strategy","correct":"from mergedeep import merge, Strategy"}],"quickstart":{"code":"from mergedeep import merge, Strategy\n\na = {'keyA': 1, 'nested': {'x': 10, 'list_data': [1, 2]}}\nb = {'keyB': 2, 'nested': {'y': 20, 'list_data': [3, 4]}}\nc = {'keyC': 3, 'nested': {'x': 100, 'new_list': [5]}}\n\n# 1. Merge into a new dictionary (non-mutating)\nmerged_new = merge({}, a, b, c)\nprint(f\"Merged into new: {merged_new}\")\n# Expected: {'keyA': 1, 'nested': {'x': 100, 'list_data': [3, 4], 'y': 20, 'new_list': [5]}, 'keyB': 2, 'keyC': 3}\n\n# 2. Merge into an existing dictionary (mutating 'a')\nmerge(a, b, c)\nprint(f\"Merged into existing 'a': {a}\")\n# Expected: {'keyA': 1, 'nested': {'x': 100, 'list_data': [3, 4], 'y': 20, 'new_list': [5]}, 'keyB': 2, 'keyC': 3}\n\n# 3. Merging with an additive strategy for lists\ndst_additive = {'items': [1, 2], 'counts': {'a': 1}}\nsrc_additive = {'items': [3, 4], 'counts': {'b': 1}}\nmerged_additive = merge({}, dst_additive, src_additive, strategy=Strategy.ADDITIVE)\nprint(f\"Merged with ADDITIVE strategy: {merged_additive}\")\n# Expected: {'items': [1, 2, 3, 4], 'counts': {'a': 1, 'b': 1}}","lang":"python","description":"Demonstrates basic deep merging using the default REPLACE strategy and an example of the ADDITIVE strategy for collections. It shows both non-mutating and mutating merge patterns."},"warnings":[{"fix":"To prevent mutation, use `merged_dict = merge({}, original_dict, *sources)`.","message":"By default, `mergedeep.merge` modifies the first dictionary (destination) in-place. If you need to preserve the original destination dictionary, pass an empty dictionary as the first argument to `merge`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you intend to combine (e.g., concatenate or union) collections, explicitly use `strategy=Strategy.ADDITIVE`.","message":"The default merge strategy (`Strategy.REPLACE`) for lists, tuples, and sets is to replace the destination collection with the source collection. This differs from some other deep merge implementations that might concatenate or union lists by default.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that types are consistent when using `Strategy.TYPESAFE_REPLACE`, or use `Strategy.REPLACE` for more permissive type handling during replacement.","message":"Using `Strategy.TYPESAFE_REPLACE` will raise a `TypeError` if the types of corresponding values in the destination and source dictionaries are different. This can be unexpected if you rely on implicit replacement even when types mismatch.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.3.4':43 'activ':48 'addit':28 'collect':31 'config':59 'conflict':24 'current':40 'data':61 'data-structur':60 'deep':9,56 'deep-merg':55 'default':27 'dictionari':13,54 'flexibl':20 'function':11 'handl':23 'includ':25 'librari':6,46 'like':32 'list':33 'maintain':49 'map':17 'merg':10,29,53,57 'mergedeep':1,2 'mutabl':16 'offer':19 'provid':7 'python':5 'regular':51 'releas':52 'replac':26,38 'safe':37 'strategi':21 'structur':62 'type':36 'type-saf':35 'util':58 'version':41","created_at":"2026-03-29T04:21:19.927495+00:00","updated_at":"2026-04-15T18:12:27.072771+00:00","problems":[{"fix":"Install the package using pip: 'pip install mergedeep'.","cause":"The 'mergedeep' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'mergedeep'"},{"fix":"Ensure the package is installed and use the correct import statement: 'from mergedeep import merge'.","cause":"The 'mergedeep' package is not installed or the import statement is incorrect.","error":"ImportError: cannot import name 'merge' from 'mergedeep'"},{"fix":"Ensure that the destination and source values are of the same type when using typesafe merge strategies.","cause":"Attempting a typesafe merge with mismatched types between destination and source values.","error":"TypeError: destination type: <class 'list'> differs from source type: <class 'set'> for key: \"key\""},{"fix":"from mergedeep import merge, Strategy\n\ndst = {\"key\": [1, 2]}\nsrc = {\"key\": {\"a\", \"b\"}} # Example: trying to merge a set into a list key\n\n# To resolve, either ensure types are compatible or use a different strategy:\n# Option 1: Adjust source type if possible\n# src = {\"key\": [3, 4]}\n# merge(dst, src, strategy=Strategy.TYPESAFE_REPLACE)\n\n# Option 2: Use Strategy.REPLACE to overwrite with the new type\nmerge(dst, src, strategy=Strategy.REPLACE)\nprint(dst) # Output: {'key': {'a', 'b'}}\n\n# Option 3: Use Strategy.ADDITIVE to combine collections if applicable\n# This example still raises TypeError because set and list are incompatible for ADDITIVE\n# If both were lists, ADDITIVE would extend the list.\n# dst = {\"key\": [1, 2]}\n# src = {\"key\": [3, 4]}\n# merge(dst, src, strategy=Strategy.ADDITIVE)\n# print(dst) # Output: {'key': [1, 2, 3, 4]}","cause":"When using `Strategy.TYPESAFE_REPLACE`, `mergedeep` encounters a conflict where a key exists in both dictionaries but with values of incompatible types (e.g., a set and a list), and `TYPESAFE_REPLACE` explicitly prevents such type mismatches.","error":"TypeError: Cannot merge type <class 'set'> with <class 'list'> using strategy TYPESAFE_REPLACE."},{"fix":"Ensure that all objects within the dictionaries you are merging are picklable. If an object is inherently not picklable, you must remove it from the dictionaries before calling `mergedeep.merge` or implement custom pre-processing to handle such types.","cause":"`mergedeep` uses `deepcopy` internally for nested mutable objects, and one of the objects within your dictionaries is not picklable (e.g., a thread lock, file handle, or other non-serializable object).","error":"TypeError: cannot pickle '_thread.lock' object"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"1.3.4","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/clarketm/mergedeep","docs":null,"changelog":null,"pypi":"https://pypi.org/project/mergedeep/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}