coola
Overview
coola is a lightweight Python library to compare, hash and summarize complex and
nested data structures.
It provides simple, extensible functions that work on objects containing
PyTorch tensors,
NumPy arrays,
pandas/polars DataFrames, and other scientific
computing objects:
- Compare:
objects_are_equal, objects_are_allclose, assert_objects_equal and compare
check equality (exact or with a tolerance) and tell where two objects differ.
- Hash:
hash_object computes a deterministic hash of a nested object.
- Summarize:
summarize creates a short, readable description of a large structure for logs.
Quick Links:
Why coola?
Python's native equality operator (==) doesn't work well with complex nested structures
containing tensors, arrays, or DataFrames. You'll often encounter errors or unexpected behavior.
coola solves this with intuitive comparison functions:
Check exact equality:
>>> import numpy as np
>>> import torch
>>> from coola.equality import objects_are_equal
>>> data1 = {"torch": torch.ones(2, 3), "numpy": np.zeros((2, 3))}
>>> data2 = {"torch": torch.ones(2, 3), "numpy": np.zeros((2, 3))}
>>> objects_are_equal(data1, data2)
True
Compare with numerical tolerance:
>>> from coola.equality import objects_are_allclose
>>> data1 = {"value": 1.0}
>>> data2 = {"value": 1.0 + 1e-9}
>>> objects_are_allclose(data1, data2)
True
Assert equality in your tests, with the path of the difference:
>>> from coola.equality import assert_objects_equal
>>> actual = {"users": [{"id": 1, "score": 95}, {"id": 2, "score": 87}]}
>>> expected = {"users": [{"id": 1, "score": 95}, {"id": 2, "score": 88}]}
>>> assert_objects_equal(actual, expected)
Traceback (most recent call last):
...
AssertionError: objects are not equal at actual['users'][1]['score']
numbers are different:
actual : 87
expected : 88
assert_objects_allclose does the same with a tolerance.
Get the difference as data:
>>> from coola.equality import compare
>>> result = compare(actual, expected)
>>> result.equal
False
>>> result.path
('users', 1, 'score')
>>> print(result.reason)
numbers are different:
actual : 87
expected : 88
Hash and summarize:
>>> from coola.hashing import hash_object
>>> from coola.summary import summarize
>>> len(hash_object(actual))
64
>>> print(summarize(actual, max_depth=2))
<class 'dict'> (length=1)
(users): <class 'list'> (length=2)
(0): {'id': 1, 'score': 95}
(1): {'id': 2, 'score': 87}
compare(actual, expected) explains the first difference (its path and its reason), and
assert_objects_equal(actual, expected) raises an AssertionError with the same message.
See the user guide for detailed examples.
Features
coola provides a comprehensive set of utilities for working with complex data structures:
🔍 Equality Comparison
Compare complex nested objects with support for multiple data types:
- Exact equality:
objects_are_equal() for strict comparison
- Approximate equality:
objects_are_allclose() for numerical tolerance
- Assertions for tests:
assert_objects_equal() and assert_objects_allclose() raise an
AssertionError with the path of the difference
- Structured results:
compare() returns a ComparisonResult with the path and the reason
- Extensible: Add custom equality testers for your own types
Learn more →
Supported types:
JAX •
NumPy •
pandas •
polars •
PyArrow •
pydantic •
PyTorch •
SciPy (sparse matrices and arrays) •
xarray •
Python built-ins (dict, list, tuple, set, etc.)
See all type-specific comparison rules →
📊 Data Summarization
Generate human-readable summaries of nested data structures for debugging and logging:
- Configurable depth control
- Type-specific formatting
- Truncation for large collections
Learn more →
🔄 Data Conversion
Transform data between different nested structures:
- Convert between list-of-dicts and dict-of-lists formats
- Useful for working with tabular data and different data representations
Learn more →
🗂️ Mapping Utilities
Work with nested dictionaries efficiently:
- Flatten nested dictionaries into flat key-value pairs
- Extract specific values from complex nested structures
- Filter dictionary keys based on patterns or criteria, rename keys and merge mappings
Learn more →
🔁 Iteration
Traverse nested data structures systematically:
- Depth-first search (DFS) traversal for nested containers
- Breadth-first search (BFS) traversal for level-by-level processing
- Filter and extract specific types from heterogeneous collections
Learn more →
📈 Reduction
Compute statistics on sequences with flexible backends:
- Calculate min, max, mean, median, quantile, std on numeric sequences
- Support for multiple backends: native Python, NumPy, PyTorch
- Consistent API regardless of backend choice
This is the beginning of the README. Read the rest at the original. Read the full README ↗
