{"id":6325,"library":"btrees","title":"BTrees","description":"BTrees is a Python package that provides a set of scalable, persistent object containers built around a modified BTree data structure. It is heavily optimized for use within ZODB's \"optimistic concurrency\" paradigm, offering efficient storage and retrieval of large mappings by only loading relevant nodes into memory. The current version is 6.3, released on November 16, 2025, with an active release cadence, often aligning with Python version support.","status":"active","version":"6.3","language":"en","source_language":"en","source_url":"https://github.com/zopefoundation/BTrees","tags":["data structure","persistence","B-tree","ZODB","mapping"],"install":[{"cmd":"pip install BTrees","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for object persistence, especially with ZODB integration.","package":"persistent","optional":false},{"reason":"Used for interface definitions and adherence within the Zope ecosystem.","package":"zope.interface","optional":false}],"imports":[{"note":"For B-trees with arbitrary Python objects as both keys and values.","symbol":"OOBTree","correct":"from BTrees.OOBTree import OOBTree"},{"note":"For B-trees with 32-bit signed integers as both keys and values. Optimized for performance and memory.","symbol":"IIBTree","correct":"from BTrees.IIBTree import IIBTree"},{"note":"For B-trees with 32-bit signed integers as keys and arbitrary Python objects as values.","symbol":"IOBTree","correct":"from BTrees.IOBTree import IOBTree"},{"note":"For B-trees with arbitrary Python objects as keys and 32-bit signed integers as values.","symbol":"OIBTree","correct":"from BTrees.OIBTree import OIBTree"}],"quickstart":{"code":"from BTrees.OOBTree import OOBTree\n\n# Create an in-memory Object-Object BTree\nmy_btree = OOBTree()\n\n# Insert key-value pairs (like a dictionary)\nmy_btree['apple'] = 1\nmy_btree['banana'] = 2\nmy_btree['cherry'] = 3\nmy_btree['date'] = 4\n\nprint(f\"BTree after insertions: {list(my_btree.items())}\")\n\n# Access values by key\nprint(f\"Value for 'banana': {my_btree['banana']}\")\n\n# Iterate over sorted keys\nprint(\"Keys in sorted order:\")\nfor key in my_btree.keys():\n    print(key)\n\n# Check for key existence\nprint(f\"'apple' in btree: {'apple' in my_btree}\")\nprint(f\"'grape' in btree: {'grape' in my_btree}\")\n\n# Delete a key\ndel my_btree['cherry']\nprint(f\"BTree after deleting 'cherry': {list(my_btree.items())}\")\n\n# Example of getting a value with a default\nvalue_or_default = my_btree.get('fig', 'default_value')\nprint(f\"Value for 'fig' (with default): {value_or_default}\")","lang":"python","description":"This quickstart demonstrates basic usage of an OOBTree (Object-Object BTree), including creation, insertion, access, iteration, existence checks, and deletion. BTrees behave largely like standard Python dictionaries but are optimized for persistence and large datasets."},"warnings":[{"fix":"Ensure your Python environment is at least 3.10. Upgrade Python and BTrees to compatible versions.","message":"BTrees regularly drops support for older Python versions with new major/minor releases. Version 6.3 requires Python >=3.10. Older versions like 3.7, 3.8, and 3.9 are no longer supported by recent BTrees releases (e.g., 6.0 and 6.2).","severity":"breaking","affected_versions":"<6.3"},{"fix":"Define `__lt__` (or a full rich comparison set) and `__hash__` methods on your custom key objects to ensure stable and meaningful ordering for BTree operations.","message":"When using custom objects as keys in BTrees (especially OOBTree) that are intended for persistence, ensure these objects implement proper comparison methods (`__lt__`, `__le__`, `__eq__`, `__hash__`). Python's default object comparison (by memory address) leads to non-deterministic order and problematic behavior upon deserialization if not handled correctly.","severity":"gotcha","affected_versions":"All"},{"fix":"Always import and use the BTree variant that matches the types of keys and values you intend to store. For example, `IIBTree` for integers, `OOBTree` for arbitrary objects, `IOBTree` for integer keys and object values.","message":"The BTrees library provides different modules for specific key/value types (e.g., `IIBTree` for integer keys/values, `OOBTree` for arbitrary objects). Mixing key/value types that do not match the chosen BTree variant (e.g., putting strings into an `IIBTree`) can lead to `TypeError` or other unexpected runtime issues.","severity":"gotcha","affected_versions":"All"},{"fix":"Always provide a second argument (the default value) to `setdefault()`, e.g., `my_btree.setdefault('missing_key', 'default_value')`. This is because some BTree types (like `IIBTree`) cannot store `None` as a value.","message":"Unlike standard Python `dict.setdefault()`, the `BTrees.BTree.setdefault()` method requires a default value argument. It does not implicitly default to `None`.","severity":"gotcha","affected_versions":"All"},{"fix":"For optimal performance, especially with large inputs, pre-sort any iterables passed to BTree set operations. If not pre-sorted, be aware of the potential performance overhead for internal sorting.","message":"In versions prior to 4.9.2, set-like operations (`union`, `intersection`, `difference`, `multiunion`) could produce incorrect results if input iterables were not pre-sorted. While newer versions automatically sort internally, for large datasets, providing pre-sorted iterables can still offer performance benefits.","severity":"gotcha","affected_versions":"<4.9.2 (functionally fixed, but performance consideration remains)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}