PyPI · #1536 most downloaded on PyPI

optree

0.20.06.3M downloads/mometaopt/optree ↗New releases in your daily digest, changelog included.

Optimized PyTree Utilities.

Last release 1 months ago
20 Aug 2026
Ships fairly regularly
a new release about every 2 months
Nearly every release is documented
notes for 14 of 14 stable releases
15 versions withdrawn
withdrawn after publishing
4 years old
30 releases · first in 2022

Release timeline

30 releases since 2022

20222023202420252026

20222026

One column per quarter.

Releases

0.20.020 Aug 20263 sources agree
Preserve dict insertion order on unflatten for the Python tree_flatten_one_level path mirroring the C++ path by @XuehaiPan in #280 .
optree v0.20.0

Added

Preserve dict insertion order on unflatten for the Python tree_flatten_one_level path mirroring the C++ path by @XuehaiPan in #280.

Add built-in frozendict support for Python 3.15+ (PEP 814), with PyTreeKind.FROZENDICT, optree.treespec_frozendict(), optree.treespec.frozendict(), and optree.typing.FrozenDict by @XuehaiPan in #274.

Migrate to Python_FIND_ABI for CMake's FindPython by @XuehaiPan in #292.

Add Python 3.15 and Python 3.15t support by @XuehaiPan in #293.

Changed

Update minimal version of typing-extensions to 4.10.0 for typing_extensions.TypeIs by @XuehaiPan in #285.

Fixed

Define Py_GIL_DISABLED for free-threaded debug builds on Windows when building the C extension to work around an upstream CMake FindPython bug by @XuehaiPan in #285.

Correct rare-case bugs from adversarial audit across deadlocks, caching, serialization, memory safety, and Python frontend by @XuehaiPan in #290.

Details of fixed rare-case bugs

Fix a deadlock when registering or unregistering a pytree node concurrently with flattening, caused by releasing the GIL while holding the registry lock by @XuehaiPan in #290.

Fix a deadlock when a duplicate registration or an unregistration of an unregistered type formats its error message, which runs the type's __repr__ while the registry lock is held and wedges any thread that is flattening by @XuehaiPan in #290.

Fix registering an already-registered collections.namedtuple subclass or PyStructSequence emitting the override warning even though the registration is rejected, which raised UserWarning instead of ValueError under warnings-as-errors by @XuehaiPan in #290.

Fix a deadlock when unregistering a pytree node drops the last reference to its flatten or unflatten function, so a __del__ or weakref callback re-entered the registry while its lock was held by @XuehaiPan in #290.

Fix a deadlock while flattening on free-threading builds, caused by acquiring the non-recursive dictionary insertion order lock twice by @XuehaiPan in #290.

Fix a spurious SystemError from optree._C.get_registry_size() when a concurrent registration slipped between its two reads by @XuehaiPan in #290.

Fix optree.tree_iter() hanging uninterruptibly when the is_leaf predicate or a custom flatten function advances the same iterator, now reported as a RuntimeError by @XuehaiPan in #290.

Fix the type caches handing an interpreter a value owned by another one, by keying them on the interpreter in addition to the type address by @XuehaiPan in #290.

Fix the type caches retaining entries for a finalized interpreter, which leaked immortal keys and could be inherited by a fresh interpreter reusing the same ID by @XuehaiPan in #290.

Fix a deadlock in the PyStructSequence field cache, caused by re-acquiring the GIL while still holding the cache lock by @XuehaiPan in #290.

Fix the type caches publishing an entry that a failed cleanup registration would orphan, leaving a value owned by an interpreter with no callback able to evict it, whether the publish preceded that registration or raced another thread still performing it by @XuehaiPan in #290.

Fix optree.structseq_fields() and the struct sequence accessors reporting the trailing hidden field names for unnamed sequence slots, by mapping each field to the slot its member offset names; the pure Python fallback, which cannot read those offsets, recovers the positions from a probe instance instead of assuming the unnamed slots trail the named ones by @XuehaiPan in #290.

Fix the treespec repr printing the raw unnamed-field marker as if it were a keyword argument, now rendered as <unnamed@N> by @XuehaiPan in #290.

Fix StructSequenceEntry reporting an unnamed sequence slot as field='unnamed field', which reads as a real field name, now reported by its index by @XuehaiPan in #290.

Fix PyTreeSpec.__setstate__() accepting a malformed state, which could read out of bounds or abort the interpreter when the treespec was later used by @XuehaiPan in #290.

Fix PyTreeSpec.__getstate__() returning the treespec's internal mutable containers, so mutating the pickled state corrupted an otherwise immutable treespec by @XuehaiPan in #290.

Fix PyTreeSpec.__setstate__() borrowing the key lists from the state it was given rather than copying them, so mutating that state afterwards silently reordered the restored treespec by @XuehaiPan in #290.

Fix pickling a PyTreeSpec with protocol 0 or 1 aborting the interpreter, by reducing through copyreg.__newobj__ by @XuehaiPan in #290.

Fix PyTreeSpec.compose(), PyTreeSpec.broadcast_to_common_suffix(), treespec_transform(), and treespec_from_collection() silently rebinding a custom node to a different registration when an empty namespace adopted a non-empty one by @XuehaiPan in #290.

Fix PyTreeSpec.broadcast_to_common_suffix() sorting the argument treespec's dictionary keys in place while building its key-mismatch error message, corrupting a treespec the caller still holds by @XuehaiPan in #290.

Fix the dictionary key order being lost when a treespec built under the global namespace is promoted to an insertion-ordered namespace by @XuehaiPan in #290.

Fix treespec_from_collection() on a leaf reporting an escalated UserWarning as a confusing SystemError, by checking the return value of PyErr_WarnEx() by @XuehaiPan in #290.

Fix treespec_from_collection() keeping the caller's namespace on a leaf or None root, which made otherwise identical treespecs compare unequal by @XuehaiPan in #290.

Fix treespec_is_prefix() and treespec_is_suffix() comparing against a stale subtree when a dictionary node's keys had been reordered by @XuehaiPan in #290.

Fix the tree iterator never reporting or clearing its is_leaf predicate to the garbage collector, leaking any reference cycle that passes through it by @XuehaiPan in #290.

Fix a list shrunk by an is_leaf predicate part way through flattening being read out of bounds on Python versions before 3.13.0a4, now raising IndexError by @XuehaiPan in #290.

Fix a reference cycle passing through a registered custom type not being collectable once the registry no longer holds the registration, by reporting the registration's members to the garbage collector when a treespec's own nodes hold every reference to it; a cycle spanning several treespecs remains uncollectable by @XuehaiPan in #290.

Fix a deeply nested treespec overflowing the native stack and crashing in treespec_paths(), treespec_accessors(), and PyTreeSpec.broadcast_to_common_suffix() instead of raising RecursionError by @XuehaiPan in #290.

Fix DataclassEntry and AttrsEntry resolving an integer entry against every declared field rather than the children the registration emitted, which returned the wrong attribute for a class holding a metadata or non-init field, now read from the record register_node() leaves on the class itself by @XuehaiPan in #290.

Fix optree.dataclasses.register_node() and optree.integrations.attrs.register_node() leaving a class in a half-registered state that could never be registered again: the registry entry and the field marker are now committed together, and a failure of either rolls the other back by @XuehaiPan in #290.

Fix optree.dataclasses.register_node() silently dropping InitVar pseudo-fields, which are neither children nor metadata and cannot round-trip, now rejected with a pointer to the generic API by @XuehaiPan in #290.

Fix tree_broadcast_common() and broadcast_common() applying the caller's is_leaf predicate to an internal sentinel tree, which could raise from the predicate or collapse a filled subtree and under-replicate by @XuehaiPan in #290.

Fix PyTreeEntry equality and hashing comparing the bytecode of __call__() and codify() rather than the methods themselves, so two entry classes that happened to share an implementation compared equal by @XuehaiPan in #290.

Fix PyTreeAccessor overriding __eq__() while inheriting tuple.__ne__(), so comparing one with a plain tuple of equal entries reported False for both == and != by @XuehaiPan in #290.

Fix GetAttrEntry.codify() emitting invalid attribute access for a field name that is not an identifier, now rendered as a getattr() call by @XuehaiPan in #290.

Fix prefix_errors() raising AssertionError instead of reporting an error for a custom node whose per-instance entries differ while its metadata does not, a pair broadcast_prefix() accepts by @XuehaiPan in #290.

Fix prefix_errors() raising TypeError while formatting a dictionary key mismatch when the keys have different types, now ordered with total_order_sorted() by @XuehaiPan in #290.

Fix tree_transpose_map(), tree_transpose_map_with_path(), tree_transpose_map_with_accessor(), and tree_partition() rejecting a leafless outer structure when an explicit inner_treespec leaves nothing to infer by @XuehaiPan in #290.

Fix the tree_broadcast_map() family flattening a custom node twice when called with a single input tree, which broke a one-shot flatten function and contradicted the documented equivalence with tree_map() by @XuehaiPan in #290.

Fix treespec_entry() and treespec_child() annotating their index as int while the runtime accepts any SupportsInt or SupportsIndex object by @XuehaiPan in #290.

Fix optree.utils.total_order_sorted() mistaking a TypeError raised by the caller's key callback for a comparison failure and silently returning the sequence unsorted, and calling the callback twice per element by @XuehaiPan in #290.

Fix a dictionary whose keys cannot be compared being flattened in a partially sorted order instead of insertion order, when a comparison raised part way through the sort by @XuehaiPan in #290.

Fix tree_broadcast_common() documenting that its results share one structure and broadcast_common() documenting that it returns two pytrees rather than two lists of leaves by @XuehaiPan in #290.

Full Changelog: v0.19.1...v0.20.0

0.19.16 May 20263 sources agree

Add attrs integration module optree.integrations.attrs with field , define , frozen , mutable , make_class , register_node , and AttrsEntry by @Xuehai

optree v0.19.1

Added

Add attrs integration module optree.integrations.attrs with field, define, frozen, mutable, make_class, register_node, and AttrsEntry by @XuehaiPan in #273.
Add optree.dataclasses.register_node to register existing dataclasses as pytree nodes by @XuehaiPan in #273.
Extend GetAttrEntry to support dotted attribute paths for traversing nested attributes (e.g., a.b.c) by @XuehaiPan.
Add functools.Placeholder support and re-export for optree.functools.partial (Python 3.14+) by @XuehaiPan in #276.

Fixed

Fix Windows wheels crashing when another extension preloads an older msvcp140.dll by disabling MSVC's constexpr std::mutex constructor by @XuehaiPan in #279. Issued by @jmkolbe in #278.

Full Changelog: v0.19.0...v0.19.1

Open source →

0.19.023 Feb 20263 sources agree

Add subinterpreters support for Python 3.14+ by @XuehaiPan in #245.

optree v0.19.0

Added

Add subinterpreters support for Python 3.14+ by @XuehaiPan in #245.

Fixed

Polish docstrings and fix grammars by @XuehaiPan in #256.

Full Changelog: https://github.com/metaopt/optree/compare/v0.18.0...v0.19.0

Open source →

Additional notes

optree v0.19.0

Added

Add subinterpreters support for Python 3.14+ by @XuehaiPan in #245.

Fixed

Polish docstrings and fix grammars by @XuehaiPan in #256.

Full Changelog: v0.18.0...v0.19.0

Open source →

0.18.014 Nov 2025Deprecated3 sources agree

Remove previously deprecated singular-named modules in #209 by @XuehaiPan in #238.

optree v0.18.0

Added

Use ARM-based GHA runners to build ARM wheels by @XuehaiPan in #234.
Add Android support by @XuehaiPan in #236.
Add manylinux-riscv64 wheels by @XuehaiPan in #243.
Add cp{313,314}-ios / cp{313,314}-android / cp{312,313}-pyodide wheels by @XuehaiPan in #242 and #244.
Add support for method pair (__tree_flatten__, __tree_unflatten__) for register_pytree_node_class(cls) by @XuehaiPan in #253.

Removed

Remove CPython 3.9/3.10 wheels for Windows ARM64 due to unavailability of official Python distribution by @XuehaiPan in #234.
Remove previously deprecated singular-named modules in #209 by @XuehaiPan in #238.
Remove PyPy 3.10 (EOL) wheels by @dependabot in #241.

Full Changelog: https://github.com/metaopt/optree/compare/v0.17.0...v0.18.0

Open source →

0.17.025 Jul 20253 sources agree

Add WASM support by @XuehaiPan in #226.

optree v0.17.0

Added

Add WASM support by @XuehaiPan in #226.
Bump cibuildwheel from 2.23 to 3.0 by @dependabot in #228.
Add iOS support by @XuehaiPan in #232.
Build Python 3.14 and 3.14t wheels in CI by @XuehaiPan in #233.

Changed

Build wheels against pybind11 3.0.0 by @XuehaiPan in #231.

Fixed

Handle pybind11 macro defined as 0 instead of non-exist by @XuehaiPan in #227.

Removed

Remove PyPy 3.9 (EOL) wheels by @dependabot in #228.

Full Changelog: https://github.com/metaopt/optree/compare/v0.16.0...v0.17.0

Open source →

0.16.028 May 20253 sources agree

Explicitly set recursion limit for recursion tests by @XuehaiPan in #207.

optree v0.16.0

Added

Explicitly set recursion limit for recursion tests by @XuehaiPan in #207.
Dump build-time meta-information to C extension by @XuehaiPan in #215.
Use pybind11::native_enum to create enum class PyTreeKind if available by @XuehaiPan in #214.
Enable pybind11::smart_holder to create class PyTreeSpec and PyTreeIter if available by @XuehaiPan in #217.
Implement optional tp_clear for class PyTreeSpec and PyTreeIter by @XuehaiPan in #218.
Add function tree_partition by @pfackeldey in #222.
Add Python 3.14 and Python 3.14t support by @XuehaiPan in #216.

Changed

Enforce naming convention of packages with singular and plural: optree.{accessor,integration} -> optree.{accessors,integrations} by @XuehaiPan in #209.
Allow creating dataclass types in the global namespace by @XuehaiPan in #212.
Migrate to setuptools>=77 for PEP-639 by @XuehaiPan in #208.
Update minimal version of typing-extensions to 4.6.0 for typing_extensions.TypeAliasType by @XuehaiPan in #216.

Fixed

Never call PyType_Ready twice and use PyType_Modified instead by @XuehaiPan in #214.
Fix optree.typing.PyTree[T] for Python 3.14 due to immutable UnionType by @XuehaiPan in #216.

Removed

Drop Python 3.8 support by @XuehaiPan in #206.
Retire benchmark script by @XuehaiPan in #211.

New Contributors

@pfackeldey made their first contribution in #222

Full Changelog: https://github.com/metaopt/optree/compare/v0.15.0...v0.16.0

Open source →

0.15.06 Apr 2025Deprecated3 sources agree

Remove deprecated key path APIs by @XuehaiPan in #195.

optree v0.15.0

Added

Add method PyTreeSpec.traverse by @XuehaiPan in #197.
Include test suites in SDist by @XuehaiPan in #201.
Include branch coverage and add conditional pragmas by @XuehaiPan in #204.
Detect cmake version and guard minimum version in setup.py by @XuehaiPan in #205.

Removed

Remove deprecated key path APIs by @XuehaiPan in #195.
Remove deprecated optree.Partial by @XuehaiPan in #196.
Remove duplicate lint checks by @XuehaiPan in #202.

New Contributors

@Flamefire made their first contribution in #203.

Full Changelog: https://github.com/metaopt/optree/compare/v0.14.1...v0.15.0

Open source →

0.14.11 Mar 20253 sources agree

Support using system cmake executable during setup by @mgorny in #188.

optree v0.14.1

Added

Support using system cmake executable during setup by @mgorny in #188.
Add shortcut module optree.pytree and optree.treespec by @lqhuang in #189.
Support lookup all registry entries in a namespace via register_pytree_node.get() by @XuehaiPan in #190.
Add PyPy 3.11 support by @XuehaiPan in #194.

Changed

Enable CXX11 ABI in C++ extension by @XuehaiPan in #184.

New Contributors

@mgorny made their first contribution in #188.
@lqhuang made their first contribution in #189.

Full Changelog: https://github.com/metaopt/optree/compare/v0.14.0...v0.14.1

Open source →

0.14.016 Jan 20253 sources agree

Add method PyTreeSpec.one_level and PyTreeSpec.is_one_level by @XuehaiPan in #179.

optree v0.14.0

Added

Add method PyTreeSpec.one_level and PyTreeSpec.is_one_level by @XuehaiPan in #179.
Add method PyTreeSpec.transform by @XuehaiPan in #177.

Changed

Mark some arguments as positional-only as of Python 3.8+ by @XuehaiPan in #178.

Fixed

Fix cross-compiling for ARM64 on x64 Windows by @XuehaiPan in #183.

Removed

Drop Python 3.7 support by @XuehaiPan in #161.

Full Changelog: https://github.com/metaopt/optree/compare/v0.13.1...v0.14.0

Open source →

0.14.0rc115 Dec 2024pre-release

Nothing published for this version

0.13.112 Nov 20243 sources agree

CI workflow improvements and minor fixes for typing annotation.

optree v0.13.1

What's New

CI workflow improvements and minor fixes for typing annotation.

Added

Upload coverage / JUnit results / core dumps in CI workflows by @XuehaiPan in #170 and #172.
Add more info to tree_flatten_one_level by @XuehaiPan in #168.
Improve typing support for generic PyTree[T] and registry lookup / register functions by @XuehaiPan in #160 and #166.

Changed

Move include directory include/{ => optree}/*.h by @XuehaiPan in #167.

Fixed

Improve typing support for optree.dataclasses.dataclass and optree.dataclasses.field by @manulari in #165.

Full Changelog: https://github.com/metaopt/optree/compare/v0.13.0...v0.13.1

New Contributors

@manulari made their first contribution in #165.

Open source →

Additional notes

optree v0.13.1

What's New

CI workflow improvements and minor fixes for typing annotation.

Added

Upload coverage / JUnit results / core dumps in CI workflows by @XuehaiPan in #170 and #172.
Add more info to tree_flatten_one_level by @XuehaiPan in #168.
Improve typing support for generic PyTree[T] and registry lookup / register functions by @XuehaiPan in #160 and #166.

Changed

Move include directory include/{ => optree}/*.h by @XuehaiPan in #167.

Fixed

Improve typing support for optree.dataclasses.dataclass and optree.dataclasses.field by @manulari in #165.

Full Changelog: v0.13.0...v0.13.1

New Contributors

@manulari made their first contribution in #165.

Open source →

0.13.03 Oct 20243 sources agree

Add Python 3.13 and Python 3.13t (free-threading build) support.

optree v0.13.0

What's New

Add Python 3.13 and Python 3.13t (free-threading build) support.
Add dataclasses integration.
Significantly refactor and improve CXX build support.

Added

Add Python 3.13t support by @XuehaiPan in #137.
Expose Python implementation for C utilities for namedtuple and PyStructSequence by @XuehaiPan in #157.
Add dataclasses integration by @XuehaiPan in #142.
Add Python 3.13 support by @XuehaiPan in #156.
Respect cmake variable pybind11_DIR by @XuehaiPan in #155.
Add tests with PyDebug enabled in CI by @XuehaiPan in #150.

Changed

Split implementation files and add more inline / constexpr / noexcept qualifiers by @XuehaiPan in #159.
Use cmake's FindPython module by @XuehaiPan in #151.

Fixed

Fix potential segmentation fault for structseq_fields cache support by @XuehaiPan in #150.

Full Changelog: https://github.com/metaopt/optree/compare/v0.12.1...v0.13.0

Open source →

0.12.16 Jul 20243 sources agree

Fix warning regression during import when launch with strict warning filters by @XuehaiPan in #149.

optree v0.12.1

Fixed

Fix warning regression during import when launch with strict warning filters by @XuehaiPan in #149.

Full Changelog: https://github.com/metaopt/optree/compare/v0.12.0...v0.12.1

Open source →

0.12.04 Jul 2024withdrawn: suppress warnings under strict warning filters in 0.12.1Deprecated3 sources agree

Update minimal version of typing-extensions to 4.5.0 for typing_extensions.deprecated by @XuehaiPan in #134.

optree v0.12.0

Added

Add context manager to temporarily set the dictionary sorting mode by @XuehaiPan in #147.
Add PyPy support by @XuehaiPan in #145.
Add 32-bit wheels for Linux and Windows by @XuehaiPan in #141.
Add Linux ppc64le and s390x wheels by @XuehaiPan in #138.
Add accessor APIs tree_flatten_with_accessor and PyTreeSpec.accessors by @XuehaiPan in #108.
Add submodule optree.functools by @XuehaiPan in #134.

Changed

Use stable tag instead of 2.12.0 for pybind11 version by @XuehaiPan in #146.
Refactor the raw import statement in setup.py with importlib utilities by @XuehaiPan in #135.
Update minimal version of typing-extensions to 4.5.0 for typing_extensions.deprecated by @XuehaiPan in #134.
Update string representation for OrderedDict by @XuehaiPan in #133.

Fixed

Fix gc for self-referential case by implementing tp_traverse by @XuehaiPan in #144.
Fix potential segmentation fault for pickling support by @XuehaiPan in #143.
Update CI runner image for Python 3.7 on macOS by @XuehaiPan in #135.

Removed

Deprecate key path APIs by @XuehaiPan in #108.
Deprecate optree.Partial and replace with optree.functools.partial by @XuehaiPan in #134.

Full Changelog: https://github.com/metaopt/optree/compare/v0.11.0...v0.12.0

Open source →

0.11.025 Mar 20243 sources agree

Add function is_namedtuple_instance and is_structseq_instance and result caches by @XuehaiPan in #121.

optree v0.11.0

Added

Add function is_namedtuple_instance and is_structseq_instance and result caches by @XuehaiPan in #121.
Add tree_iter function by @XuehaiPan in #130.
Add API to unregister node type in the registry by @XuehaiPan in #124.
Add tree map functions with transposed outputs tree_transpose_map and tree_transpose_map_with_path by @XuehaiPan in #127.
Add static constructors to create PyTreeSpec instances by @XuehaiPan in #120.
Cache intermediate str objects in PyObject_GetAttr calls by @XuehaiPan in #106 and #109.
Install clang-format and clang-tidy from PyPI by @XuehaiPan in #107.
Also check _make and _asdict in function is_namedtuple_class by @XuehaiPan in #105.

Changed

Set recursion limit to 1000 for all platforms by @XuehaiPan in #121.
Allow types to be registered in both the global namespace and custom namespaces by @XuehaiPan in #124.
Set treespec_is_leaf as strict by default by @XuehaiPan in #120.
Reorder functions for better code correspondence between C++ and Python by @XuehaiPan in #117.
Standardize py::handle and py::object usage in function signature by @XuehaiPan in #115.
Reorder cases for namedtuple and PyStructSequence types by @XuehaiPan in #111.
Use __bases__ rather than __base__ in function is_structseq_class by @XuehaiPan in #104.

Fixed

Fix potential segmentation fault when modifying treespec.entries() by @XuehaiPan in #116.

Full Changelog: https://github.com/metaopt/optree/compare/v0.10.0...v0.11.0

Open source →

0.10.07 Nov 20233 sources agree

Add tree_ravel function for JAX/NumPy/PyTorch array/tensor tree manipulation by @XuehaiPan in #100.

optree v0.10.0

Added

Add tree_ravel function for JAX/NumPy/PyTorch array/tensor tree manipulation by @XuehaiPan in #100.
Expose node kind enum for PyTreeSpec by @XuehaiPan in #98.
Expose function tree_flatten_one_level by @XuehaiPan in #101.
Add tree broadcast functions broadcast_common, tree_broadcast_common, tree_broadcast_map, and tree_broadcast_map_with_path by @XuehaiPan in #87.
Add function tree_is_leaf and add is_leaf argument to function all_leaves by @XuehaiPan in #93.
Add methods PyTreeSpec.entry and PyTreeSpec.child by @XuehaiPan in #88.
Add Python 3.12 support by @XuehaiPan in #90.
Allow passing third-party dependency version from environment variable by @XuehaiPan in #80.

Changed

Set recursion limit to 2000 for all platforms by @XuehaiPan in #97.
Make PyTreeSpec.is_prefix to be consistent with PyTreeSpec.flatten_up_to by @XuehaiPan in #94.
Decrease the MAX_RECURSION_DEPTH to 2000 on Windows by @XuehaiPan in #85.
Bump abseil-cpp version to 20230802.1 by @XuehaiPan in #80.

Fixed

Memorize ongoing repr / hash calls to resolve infinite recursion under self-referential case by @XuehaiPan and @JieRen98 in #82.

Removed

Remove dependence on abseil-cpp by @XuehaiPan in #85.

Full Changelog: https://github.com/metaopt/optree/compare/v0.9.2...v0.10.0

Open source →

0.9.218 Sept 2023withdrawn: old version3 sources agree

Bump pybind11 version to 2.11.1 and add initial Python 3.12 support by @XuehaiPan in #78.

Patch Release [0.9.2] - 2023-09-18

Changed

Bump pybind11 version to 2.11.1 and add initial Python 3.12 support by @XuehaiPan in #78.
Bump abseil-cpp version to 20230802.0 by @XuehaiPan in #79.

Fixed

Fix empty paths when flatten with custom is_leaf function by @XuehaiPan in #76.

Full Changelog: https://github.com/metaopt/optree/compare/v0.9.1...v0.9.2

Open source →

0.9.123 May 2023withdrawn: old versionDeprecated3 sources agree

Use py::handle_of(obj) rather than deprecated obj.get_type() by @XuehaiPan in #49.

Patch Release [0.9.1] - 2023-05-23

Changed

Use py::type::handle_of(obj) rather than deprecated obj.get_type() by @XuehaiPan in #49.
Bump abseil-cpp version to 20230125.3 by @XuehaiPan in #57.

Fixed

Add @runtime_checkable decorator for CustomTreeNode protocol class by @XuehaiPan in #56.

Full Changelog: https://github.com/metaopt/optree/compare/v0.9.0...v0.9.1

Open source →

0.9.023 Mar 2023withdrawn: old version3 sources agree

Now `optree` preserves `dict` / `defaultdict` key order in the output of `tree_unflatten`, `tree_map`, and `tree_map_with_path`.

What's New

Now optree preserves dict / defaultdict key order in the output of tree_unflatten, tree_map, and tree_map_with_path.

This behavior needs extra operations during flattening/unflattening. There would be performance regression for dict and defaultdict. No impact is added for other collection types, such as OrderedDict, list, tuple.

optree v0.8.0: the output dict from tree_unflatten is stored in sorted order.

tree_flatten and tree_unflatten will lose the information above the insertion order of the input dict. Map over a dict with the identity function will change the key order.

>>> optree.tree_map(lambda x: x, {'b': 2, 'a': 1})
{'a': 1, 'b': 2}

optree v0.9.0: the output dict from tree_unflatten will have the consistent key order with the input dict.

>>> optree.tree_map(lambda x: x, {'b': 2, 'a': 1})
{'b': 2, 'a': 1}

As the key order is preserved, it's safe to use tree_map to process "unordered dict" (builtins.dict) (e.g., **kwargs in functions). In this case, users no longer need to convert dict to OrderedDict manually.

def func(*args, **kwargs):
    args, kwargs = optree.tree_map(do_something, (args, kwargs))
    # optree v0.8.0: args, kwargs = optree.tree_map(do_something, (args, OrderedDict(kwargs)))
    ...

Note that tree_map still maps the leaves in sorted key order (the same order as tree_flatten and tree_leaves).

>>> leaves = [] 
...
... def add_leaves(x):
...     leaves.append(x)
...     return x
...
>>> ptree.tree_map(add_leaves, {'b': 2, 'a': 1})
{'b': 2, 'a': 1}
>>> leaves
[1, 2]

Breaking Changes

Revert "Change keyword argument initial to initializer for tree_reduce to align with functools.reduce". The previous change is reverted due to a documentation issue for Python (see also python/cpython#102757 and python/cpython#102759). The argument name is changed back to initial in tree_reduce. Users are recommended to use positional arguments.

Full Changelog [0.9.0] - 2023-03-23

Added

Preserve dict key order in the output of tree_unflatten, tree_map, and tree_map_with_path by @XuehaiPan in #46.

Changed

Change keyword argument initializer back to initial for tree_reduce to align with functools.reduce C implementation by @XuehaiPan in #47.

Full Changelog: https://github.com/metaopt/optree/compare/v0.8.0...v0.9.0

Open source →

0.8.014 Mar 2023withdrawn: old version3 sources agree

Add new and refactor utility functions for namedtuple and PyStructSequence types.

What's New

Add new and refactor utility functions for namedtuple and PyStructSequence types.
- is_namedtuple
- is_namedtuple_class
- is_structseq
- is_structseq_class
- namedtuple_fields (new)
- structseq_fields
Add more methods and properties for PyTreeSpec class.
- PyTreeSpec.is_prefix (treespec_is_prefix and __le__ / __lt__)
- PyTreeSpec.is_suffix (treespec_is_suffix and __ge__ / __gt__)
- PyTreeSpec.paths (treespec_paths)
- PyTreeSpec.entries (treespec_entries)
Add tree reduce functions.
- tree_sum
- tree_max
- tree_min

Miscellaneous changes.

Rephrase error messages.

>>> optree.tree_map(lambda x, y: x + y, {'a': 1, 'b': 2}, {'b': 3, 'c': 4})
Traceback (most recent call last):
    ...
ValueError: dictionary key mismatch; expected key(s): ['a', 'b'], got key(s): ['b', 'c'], missing key(s): ['a'], extra key(s): ['c']; dict: {'b': 3, 'c': 4}.

Add function tree_broadcast_prefix.
Linter integration for flake8 plugins and ruff.

Breaking Changes

PyTreeSpec.flatten_up_to now allows ordered (OrderedDict) and unordered (dict and defaultdict) dictionaries mutually exchangeable.

This behavior will affect all functions based on flatten_up_to, such as tree_map, tree_map_with_path, tree_broadcast_prefix. Calling multi-treemap with mixed inputs of ordered and unordered dictionaries will no longer raise ValueError.

optree v0.7.0: raise ValueError if the dictionary type mismatch

>>> from collections import *
>>> import optree
>>> d = {'a': 1, 'b': 2, 'c': 3}
>>> od = OrderedDict([('b', 5), ('c', 6), ('a', 4)])
>>> dd = defaultdict(int, {'c': 9, 'a': 7, 'b': 8})
>>> optree.tree_map(lambda x, y, z: 100 * x + 10 * y + z, d, od, dd)
Traceback (most recent call last):
    ...
ValueError: Expected dict, got OrderedDict([('b', 5), ('c', 6), ('a', 4)]).
>>> optree.tree_map(lambda x, y, z: 100 * x + 10 * y + z, od, dd, d)
Traceback (most recent call last):
    ...
ValueError: Expected collections.OrderedDict, got defaultdict(<class 'int'>, {'c': 9, 'a': 7, 'b': 8}).
>>> optree.tree_map(lambda x, y, z: 100 * x + 10 * y + z, od, dd, d)
Traceback (most recent call last):
    ...
ValueError: Expected collections.defaultdict, got {'a': 1, 'b': 2, 'c': 3}.

optree v0.8.0: allow mixed input of dict, OrderedDict, and defaultdict. The result pytree type and key ordering are determined by the first input pytree.

>>> from collections import *
>>> import optree
>>> d = {'a': 1, 'b': 2, 'c': 3}
>>> od = OrderedDict([('b', 5), ('c', 6), ('a', 4)])
>>> dd = defaultdict(int, {'c': 9, 'a': 7, 'b': 8})
>>> optree.tree_map(lambda x, y, z: 100 * x + 10 * y + z, d, od, dd)
{'a': 147, 'b': 258, 'c': 369}
>>> optree.tree_map(lambda x, y, z: 100 * x + 10 * y + z, od, dd, d)
OrderedDict([('b', 582), ('c', 693), ('a', 471)])
>>> optree.tree_map(lambda x, y, z: 100 * x + 10 * y + z, dd, d, od)
defaultdict(<class 'int'>, {'a': 714, 'b': 825, 'c': 936})

Use more appropriate exception types.

structseq_fields now raises TypeError rather than ValueError when got non-PyStructSequence types

optree v0.7.0: raise ValueError when got non-PyStructSequence types

>>> from collections import *
>>> import optree
>>> optree.structseq_fields((1, 2))
Traceback (most recent call last):
    ...
ValueError: Expected StructSequence, got (1, 2).
>>> mytuple = namedtuple('mytuple', ['a', 'b'])
>>> optree.structseq_fields(mytuple(1, 2))
Traceback (most recent call last):
    ...
ValueError: Expected StructSequence, got mytuple(a=1, b=2).

optree v0.8.0: raise TypeError when got non-PyStructSequence types

>>> from collections import *
>>> import optree
>>> optree.structseq_fields((1, 2))
Traceback (most recent call last):
    ...
TypeError: Expected an instance of PyStructSequence type, got (1, 2).
>>> mytuple = namedtuple('mytuple', ['a', 'b'])
>>> optree.structseq_fields(mytuple(1, 2))
Traceback (most recent call last):
    ...
TypeError: Expected an instance of PyStructSequence type, got mytuple(a=1, b=2).

optree._C.InternalError now inherits from SystemError rather than RuntimeError.

optree v0.7.0: need to use RuntimeError to catch InternalError

>>> import optree
>>> optree._C.InternalError.mro()
[<class 'optree._C.InternalError'>, <class 'RuntimeError'>, <class 'Exception'>, <class 'BaseException'>, <class 'object'>]

optree v0.8.0: need to use SystemError to catch InternalError

>>> import optree
>>> optree._C.InternalError.mro()
[<class 'optree._C.InternalError'>, <class 'SystemError'>, <class 'Exception'>, <class 'BaseException'>, <class 'object'>]

Change keyword argument initial to initializer for tree_reduce to align with functools.reduce.

Full Changelog [0.8.0] - 2023-03-14

Added

Add methods PyTreeSpec.paths and PyTreeSpec.entries by @XuehaiPan in #43.
Allow tree-map with mixed inputs of ordered and unordered dictionaries by @XuehaiPan in #42.
Add more utility functions for namedtuple and PyStructSequence type by @XuehaiPan in #41.
Add methods PyTreeSpec.is_prefix and PyTreeSpec.is_suffix and function tree_broadcast_prefix by @XuehaiPan in #40.
Add tree reduce functions tree_sum, tree_max, and tree_min by @XuehaiPan in #39.
Test dict key equality with PyDict_Contains ($O (n)$) rather than sorting ($O (n \log n)$) by @XuehaiPan in #37.
Make error message more clear when value mismatch by @XuehaiPan in #36.
Add ruff and flake8 plugins integration by @XuehaiPan in #33.

Changed

Allow tree-map with mixed inputs of ordered and unordered dictionaries by @XuehaiPan in #42.
Use more appropriate exception handling (e.g., change ValueError to TypeError in structseq_fields) by @XuehaiPan in #41.
Inherit optree._C.InternalError from SystemError rather than RuntimeError by @XuehaiPan in #41.
Change keyword argument initial to initializer for tree_reduce to align with functools.reduce by @XuehaiPan in #39.

Full Changelog: https://github.com/metaopt/optree/compare/v0.7.0...v0.8.0

Open source →

0.7.07 Feb 2023withdrawn: old version3 sources agree

Add PyStructSequence types as internal node types by @XuehaiPan in #30.

[0.7.0] - 2023-02-07

Added

Add PyStructSequence types as internal node types by @XuehaiPan in #30.

Changed

Add PyStructSequence types as internal node types by @XuehaiPan in #30.
Use postponed evaluation of annotations by @XuehaiPan in #28.

Full Changelog: https://github.com/metaopt/optree/compare/v0.6.0...v0.7.0

Open source →

0.6.02 Feb 2023withdrawn: old version2 sources agree

Add Linux AArch64 and Windows ARM64 wheels by @XuehaiPan in #25.

Added

Add Linux AArch64 and Windows ARM64 wheels by @XuehaiPan in #25.
Add property PyTreeSpec.type and method PyTreeSpec.is_leaf by @XuehaiPan in #26.
Raise a warning when registering subclasses of namedtuple by @XuehaiPan in #24.
Add clang-tidy integration and update code style by @XuehaiPan in #20.

Fixed

Add doctest integration and fix docstring by @XuehaiPan in #23.

Open source →

0.5.120 Jan 2023withdrawn: old version2 sources agree

Add property PyTreeSpec.num_children by @XuehaiPan.

Added

Add property PyTreeSpec.num_children by @XuehaiPan.
Update docstring and documentation by @XuehaiPan.

Open source →

0.5.030 Nov 2022withdrawn: old version2 sources agree

Add custom exceptions for internal error handling by @XuehaiPan.

Added

Add custom exceptions for internal error handling by @XuehaiPan.

Fixed

Fix PyTreeSpec equality test and hash by @XuehaiPan.

Open source →

0.4.227 Nov 2022withdrawn: old version2 sources agree

Better internal error handling by @XuehaiPan in #17.

Changed

Better internal error handling by @XuehaiPan in #17.
Use static raw pointers for global imports by @XuehaiPan in #16.

Open source →

0.4.125 Nov 2022withdrawn: old version2 sources agree

Fix segmentation fault error for global imports @XuehaiPan in #14.

Fixed

Fix segmentation fault error for global imports @XuehaiPan in #14.

Open source →

0.4.024 Nov 2022withdrawn: old version2 sources agree

Add namespace support for custom node type registry by @XuehaiPan in #12.

Added

Add namespace support for custom node type registry by @XuehaiPan in #12.
Add tree flatten and tree map functions with extra paths by @XuehaiPan in #11.
Add in-place version of tree-map function tree_map_ by @XuehaiPan.
Add macOS ARM64 wheels by @XuehaiPan in #9.
Add Python 3.11 support by @XuehaiPan.

Changed

Use shallow clone for third-party Git repos by @XuehaiPan.
Use cmake FetchContent rather than Git submodules by @XuehaiPan.

Removed

Drop Python 3.6 support by @XuehaiPan.

Open source →

0.3.025 Oct 2022withdrawn: old version2 sources agree

Add Read the Docs integration by @XuehaiPan.

Added

Add Read the Docs integration by @XuehaiPan.
Add benchmark script and results by @XuehaiPan.
Support both "None is Node" and "None is Leaf" by @XuehaiPan.
Add OrderedDict and defaultdict and deque as builtin support by @XuehaiPan.

Changed

Reorganize code structure and rename PyTreeDef to PyTreeSpec by @XuehaiPan.

Fixed

Fix Python 3.6 support by @XuehaiPan.
Fix generic NamedTuple for Python 3.8-3.10 by @XuehaiPan.
Fix builds for Python 3.8-3.10 on Windows by @XuehaiPan.

Open source →

0.2.024 Sept 2022withdrawn: old version2 sources agree

Add cibuildwheel integration for building wheels by @XuehaiPan.

Added

Add cibuildwheel integration for building wheels by @XuehaiPan.
Add full type annotations by @XuehaiPan.

Changed

Improve custom tree node representation by @XuehaiPan.

Fixed

Fix cross-platform compatibility by @XuehaiPan.

Open source →

0.1.020 Aug 2022withdrawn: old version2 sources agree

The first beta release of OpTree by @XuehaiPan.

Added

The first beta release of OpTree by @XuehaiPan.
OpTree with Linux / Windows / macOS x64 support by @XuehaiPan.

Open source →

Your coding agent can read these notes before it upgrades. Set up the MCP server →

optree

Release timeline

Releases

optree v0.20.0

Added

Changed

Fixed

optree v0.19.1

Added

Fixed

optree v0.19.0

Added

Fixed

optree v0.19.0

Added

Fixed

optree v0.18.0

Added

Removed

optree v0.17.0

Added

Changed

Fixed

Removed

optree v0.16.0

Added

Changed

Fixed

Removed

New Contributors

optree v0.15.0

Added

Removed

New Contributors

optree v0.14.1

Added

Changed

New Contributors

optree v0.14.0

Added

Changed

Fixed

Removed

optree v0.13.1

What's New

Added

Changed

Fixed

New Contributors

optree v0.13.1

What's New

Added

Changed

Fixed

New Contributors

optree v0.13.0

What's New

Added

Changed

Fixed

optree v0.12.1

Fixed

optree v0.12.0

Added

Changed

Fixed

Removed

optree v0.11.0

Added

Changed

Fixed

optree v0.10.0

Added

Changed

Fixed

Removed

Patch Release [0.9.2] - 2023-09-18

Changed

Fixed

Patch Release [0.9.1] - 2023-05-23