{"id":2009,"library":"dm-tree","title":"dm-tree: Nested Data Structure Utilities","description":"dm-tree (DeepMind Tree) is a lightweight Python library designed for working with nested data structures such as lists, tuples, and dictionaries. It provides functional tools like `map_structure`, `flatten`, and `unflatten` to apply operations across arbitrary tree-like data. The current stable version is 0.1.10, and it follows an infrequent release cadence focused on stability for its core functionalities.","status":"active","version":"0.1.10","language":"en","source_language":"en","source_url":"https://github.com/deepmind/tree","tags":["data structures","nested data","deepmind","functional programming","tree traversal"],"install":[{"cmd":"pip install dm-tree","lang":"bash","label":"Install dm-tree"}],"dependencies":[{"reason":"Requires Python 3.10 or newer for installation and execution.","package":"python","optional":false}],"imports":[{"note":"The PyPI package `dm-tree` provides the `tree` module, not `dm_tree`.","wrong":"import dm_tree","symbol":"tree","correct":"import tree"},{"symbol":"map_structure","correct":"from tree import map_structure"},{"symbol":"flatten","correct":"from tree import flatten"},{"symbol":"unflatten","correct":"from tree import unflatten"}],"quickstart":{"code":"import tree\n\n# Define a nested data structure\ndata_tree = {\n    'a': [1, 2],\n    'b': {'c': 3, 'd': (4, 5)},\n    'e': 6\n}\n\n# 1. Map a function over all 'leaves' in the structure\ndef increment(x):\n    return x + 1\n\nmapped_tree = tree.map_structure(increment, data_tree)\nprint(f\"Mapped tree: {mapped_tree}\")\n# Expected: {'a': [2, 3], 'b': {'c': 4, 'd': (5, 6)}, 'e': 7}\n\n# 2. Flatten the structure into a list of leaves and a 'structure' object\nleaves, structure = tree.flatten(data_tree)\nprint(f\"Flattened leaves: {leaves}\")\nprint(f\"Original structure (abstracted): {structure}\")\n# Expected: Flattened leaves: [1, 2, 3, 4, 5, 6]\n\n# 3. Unflatten the leaves back into the original structure\nnew_leaves = [x * 10 for x in leaves]\nunflattened_tree = tree.unflatten(structure, new_leaves)\nprint(f\"Unflattened tree: {unflattened_tree}\")\n# Expected: {'a': [10, 20], 'b': {'c': 30, 'd': (40, 50)}, 'e': 60}","lang":"python","description":"This quickstart demonstrates the core functionalities of `dm-tree`: `map_structure` for applying a function to all 'leaf' elements, and `flatten`/`unflatten` for converting a nested structure into a flat list of elements and back again, preserving the original structure."},"warnings":[{"fix":"Use `import tree` or `from tree import ...` after `pip install dm-tree`.","message":"The PyPI package `dm-tree` should be imported as `import tree`, not `import dm_tree`. This is a common source of 'ModuleNotFoundError'.","severity":"gotcha","affected_versions":"All versions (0.1.x)"},{"fix":"Be aware of this classification. For custom classes, ensure they mimic standard containers if you want them treated as nodes, or explicitly implement `_fields` and `_asdict` if you want `namedtuple`-like behavior.","message":"dm-tree's core functions (e.g., `map_structure`) define 'nested structures' (nodes) as `dict`, `list`, `tuple`, `namedtuple`, and `collections.OrderedDict`. All other types are considered 'leaves'. This can be unexpected for custom objects that you might consider iterable or 'tree-like' but don't fall into these categories.","severity":"gotcha","affected_versions":"All versions (0.1.x)"},{"fix":"Ensure your Python environment is 3.10 or newer. Upgrade Python if necessary.","message":"dm-tree requires Python 3.10 or newer. Attempting to install or run on older Python versions will fail or result in compatibility errors.","severity":"breaking","affected_versions":"0.1.0 and later"},{"fix":"Ensure all structures passed to `map_structure` have identical nesting and container types at corresponding positions. If you need to map over structures with differing shapes, you'll need to handle the differences before mapping or use `flatten` and manually map the leaves.","message":"`tree.map_structure` is strict about structure matching. All arguments to `map_structure` must have the same nested structure. If the structures differ (e.g., one has a list of 3 items, another a list of 2), it will raise a `ValueError`.","severity":"gotcha","affected_versions":"All versions (0.1.x)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}