BTrees

Warnings

• breaking 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).
  Fix: Ensure your Python environment is at least 3.10. Upgrade Python and BTrees to compatible versions.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha Unlike standard Python `dict.setdefault()`, the `BTrees.BTree.setdefault()` method requires a default value argument. It does not implicitly default to `None`.
  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.
• gotcha 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.
  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.

Install

• pip install BTrees Install latest version

Imports

• OOBTree

  from BTrees.OOBTree import OOBTree

  For B-trees with arbitrary Python objects as both keys and values.
• IIBTree

  from BTrees.IIBTree import IIBTree

  For B-trees with 32-bit signed integers as both keys and values. Optimized for performance and memory.
• IOBTree

  from BTrees.IOBTree import IOBTree

  For B-trees with 32-bit signed integers as keys and arbitrary Python objects as values.
• OIBTree

  from BTrees.OIBTree import OIBTree

  For B-trees with arbitrary Python objects as keys and 32-bit signed integers as values.

Quickstart

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.

from BTrees.OOBTree import OOBTree

# Create an in-memory Object-Object BTree
my_btree = OOBTree()

# Insert key-value pairs (like a dictionary)
my_btree['apple'] = 1
my_btree['banana'] = 2
my_btree['cherry'] = 3
my_btree['date'] = 4

print(f"BTree after insertions: {list(my_btree.items())}")

# Access values by key
print(f"Value for 'banana': {my_btree['banana']}")

# Iterate over sorted keys
print("Keys in sorted order:")
for key in my_btree.keys():
    print(key)

# Check for key existence
print(f"'apple' in btree: {'apple' in my_btree}")
print(f"'grape' in btree: {'grape' in my_btree}")

# Delete a key
del my_btree['cherry']
print(f"BTree after deleting 'cherry': {list(my_btree.items())}")

# Example of getting a value with a default
value_or_default = my_btree.get('fig', 'default_value')
print(f"Value for 'fig' (with default): {value_or_default}")