{"library":"optree","title":"Optimized PyTree Utilities","description":"OpTree is an optimized Python library for working with PyTrees, which are arbitrarily nested Python containers. It provides efficient utilities for flattening, unflattening, and mapping functions over tree structures. The current version is 0.19.0, and the library maintains an active development cycle with frequent releases.","status":"active","version":"0.19.0","language":"en","source_language":"en","source_url":"https://github.com/metaopt/optree","tags":["pytree","tree-traversal","functional-programming","python>=3.9","data-structures"],"install":[{"cmd":"pip install optree","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for type hinting support, especially for Python versions older than 3.12.","package":"typing-extensions","optional":false}],"imports":[{"symbol":"tree_flatten","correct":"from optree import tree_flatten"},{"symbol":"tree_unflatten","correct":"from optree import tree_unflatten"},{"symbol":"tree_map","correct":"from optree import tree_map"},{"symbol":"register_pytree_node","correct":"from optree import register_pytree_node"},{"note":"While `from optree import pytree` works, using `import optree.pytree as pt` is a common alias for convenience, especially since v0.14.1 for its `tree_*` aliases.","wrong":"from optree import pytree","symbol":"pytree","correct":"import optree.pytree as pt"}],"quickstart":{"code":"from optree import tree_map\n\ndef add_one(x):\n    return x + 1\n\ntree = {'a': 1, 'b': [2, 3], 'c': {'d': 4}}\nmapped_tree = tree_map(add_one, tree)\nprint(mapped_tree)\n\nfrom optree import tree_flatten, tree_unflatten, PyTreeSpec\n\nleaves, treespec = tree_flatten(tree)\nprint(f\"Leaves: {leaves}\")\nprint(f\"TreeSpec: {treespec}\")\n\nreconstructed_tree = tree_unflatten(treespec, [l * 10 for l in leaves])\nprint(f\"Reconstructed tree with modified leaves: {reconstructed_tree}\")","lang":"python","description":"This quickstart demonstrates the core `tree_map` function to apply a transformation to all leaves of a PyTree, and also shows how to flatten a PyTree into leaves and a structure (`treespec`) and then unflatten it back, potentially with modified leaves."},"warnings":[{"fix":"Upgrade Python to 3.8+ (preferably 3.9+) or pin optree to `<0.14.0`.","message":"Python 3.7 support was dropped in optree v0.14.0. Users on Python 3.7 must upgrade their Python version or use optree versions prior to 0.14.0.","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Update code to use the current API. Refer to optree documentation for alternatives to key path APIs and `functools.partial` for `optree.Partial`.","message":"Deprecated key path APIs and `optree.Partial` were removed in optree v0.15.0. Any code relying on these older APIs will break.","severity":"breaking","affected_versions":">=0.15.0"},{"fix":"Always provide a unique, non-empty `namespace` string (e.g., 'mylibrary.pytrees') when registering custom PyTree nodes. Example: `optree.register_pytree_node(MyClass, flatten_func, unflatten_func, namespace='my.namespace')`.","message":"When registering a custom PyTree node type using `optree.register_pytree_node` or `optree.register_pytree_node_class`, a `namespace` argument is explicitly required. This prevents accidental collisions between different libraries registering the same type with different behaviors in the same Python interpreter.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If `None` should be processed as a leaf, use `none_is_leaf=True` in relevant functions: `tree_map(func, tree, none_is_leaf=True)`.","message":"By default, `None` is treated as a non-leaf node with zero children. This means it's part of the tree structure (`treespec`), not the list of leaves. To treat `None` as a leaf node, you must explicitly pass `none_is_leaf=True` to functions like `tree_flatten` or `tree_map`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully design `flatten_func` to ensure that it eventually produces only leaf nodes or built-in non-leaf types, or explicitly handle recursion depth. The library defines `MAX_RECURSION_DEPTH`.","message":"Custom `flatten_func` implementations for `register_pytree_node` must include a proper termination condition to prevent infinite recursion, especially if the children can be of the same type as the current node. This can lead to a `RecursionError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update import statements. For example, change `from optree import accessor` to `from optree import accessors`.","message":"Module naming conventions changed in v0.16.0, affecting direct imports. Specifically, `optree.accessor` became `optree.accessors`, `optree.integration` became `optree.integrations`, etc.","severity":"breaking","affected_versions":">=0.16.0"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}