This release is a pre-release and may not be stable for production use.
coola
Overview
coola is a lightweight Python library that makes it easy to compare complex and nested data
structures.
It provides simple, extensible functions to check equality between objects containing
PyTorch tensors,
NumPy arrays,
pandas/polars DataFrames, and other scientific
computing objects.
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
Debug differences easily:
>>> from coola.equality import objects_are_equal
>>> actual = {"users": [{"id": 1, "score": 95}, {"id": 2, "score": 87}]}
>>> expected = {"users": [{"id": 1, "score": 95}, {"id": 2, "score": 88}]}
>>> objects_are_equal(actual, expected, show_difference=True)
False
Log output
numbers are different:
actual : 87
expected : 88
mappings have different values for key 'score'
sequences have different values at index 1
mappings have different values for key 'users'
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 - User-friendly difference reporting: Clear, structured output showing exactly what differs
- Extensible: Add custom comparators for your own types
Supported types: JAX • NumPy • pandas • polars • PyArrow • PyTorch • 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
🔄 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
🗂️ 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
🔁 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
📈 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
Installation
We highly recommend installing
coola in
a virtual environment
to avoid dependency conflicts.
Using uv (recommended)
uv is a fast Python package installer and resolver:
uv pip install coola
Install with all optional dependencies:
uv pip install coola[all]
Install with specific optional dependencies:
uv pip install coola[numpy,torch] # with NumPy and PyTorch
Using pip
Alternatively, you can use pip:
pip install coola
Install with all optional dependencies:
pip install coola[all]
Install with specific optional dependencies:
pip install coola[numpy,torch] # with NumPy and PyTorch
Requirements
- Python: 3.10 or higher
- Operating system: Linux or macOS (no Windows support)
- Core dependencies: None (fully optional dependencies)
Optional dependencies (install with coola[all]):
JAX •
NumPy •
pandas •
polars •
PyArrow •
PyTorch •
xarray
Note: the
jaxandtorchextras are further restricted to Linux and Apple Silicon (macOS arm64), matching the platforms these libraries publish wheels for — installingcoola[jax]orcoola[torch]on Intel macOS will fail to resolve.
For detailed installation instructions, compatibility information, and alternative installation methods, see the installation guide.
Compatibility Matrix
coola |
jax* |
numpy* |
packaging* |
pandas* |
polars* |
pyarrow* |
pydantic* |
torch* |
xarray* |
python |
|---|---|---|---|---|---|---|---|---|---|---|
main |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
1.1.10 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
1.1.9 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
1.1.8 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
|
1.1.7 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
|
1.1.6 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
|
1.1.5 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
|
1.1.4 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
|
1.1.3 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
|
1.1.2 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
|
1.1.1 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
|
1.1.0 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
|
1.0.1 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<4.0 |
>=1.0,<2.0 |
>=11.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
|
1.0.0 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<3.0 |
>=1.0,<2.0 |
>=11.0,<23.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
* indicates an optional dependency
older versions
coola |
jax* |
numpy* |
packaging* |
pandas* |
polars* |
pyarrow* |
torch* |
xarray* |
python |
|---|---|---|---|---|---|---|---|---|---|
0.11.1 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<3.0 |
>=1.0,<2.0 |
>=11.0,<22.0 |
>=2.0,<3.0 |
>=2024.1 |
>=3.10 |
0.11.0 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<3.0 |
>=1.0,<2.0 |
>=11.0,<22.0 |
>=2.0,<3.0 |
>=2023.1 |
>=3.10 |
0.10.0 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0 |
>=2.0,<3.0 |
>=1.0,<2.0 |
>=11.0,<22.0 |
>=2.0,<3.0 |
>=2023.1 |
>=3.10 |
0.9.1 |
>=0.5.0,<1.0 |
>=1.24,<3.0 |
>=22.0,<26.0 |
>=2.0,<3.0 |
>=1.0,<2.0 |
>=11.0,<22.0 |
>=2.0,<3.0 |
>=2023.1 |
>=3.10,<3.15 |
0.9.0 |
>=0.4.6,<1.0 |
>=1.24,<3.0 |
>=22.0,<26.0 |
>=2.0,<3.0 |
>=1.0,<2.0 |
>=11.0,<20.0 |
>=2.0,<3.0 |
>=2023.1 |
>=3.9,<3.14 |
0.8.7 |
>=0.4.6,<1.0 |
>=1.22,<3.0 |
>=21.0,<26.0 |
>=1.5,<3.0 |
>=1.0,<2.0 |
>=10.0,<20.0 |
>=1.11,<3.0 |
>=2023.1 |
>=3.9,<3.14 |
0.8.6 |
>=0.4.6,<1.0 |
>=1.21,<3.0 |
>=1.3,<3.0 |
>=0.18.3,<2.0 |
>=10.0,<20.0 |
>=1.11,<3.0 |
>=2023.1 |
>=3.9,<3.14 |
|
0.8.5 |
>=0.4.6,<1.0 |
>=1.21,<3.0 |
>=1.3,<3.0 |
>=0.18.3,<2.0 |
>=10.0,<19.0 |
>=1.11,<3.0 |
>=2023.1 |
>=3.9,<3.14 |
|
0.8.4 |
>=0.4.6,<1.0 |
>=1.21,<3.0 |
>=1.3,<3.0 |
>=0.18.3,<2.0 |
>=10.0,<18.0 |
>=1.11,<3.0 |
>=2023.1 |
>=3.9,<3.14 |
|
0.8.3 |
>=0.4.1,<1.0 |
>=1.21,<3.0 |
>=1.3,<3.0 |
>=0.18.3,<2.0 |
>=10.0,<18.0 |
>=1.11,<3.0 |
>=2023.1 |
>=3.9,<3.13 |
|
0.8.2 |
>=0.4.1,<1.0 |
>=1.21,<3.0 |
>=1.3,<3.0 |
>=0.18.3,<2.0 |
>=10.0,<18.0 |
>=1.11,<3.0 |
>=2023.1 |
>=3.9,<3.13 |
|
0.8.1 |
>=0.4.1,<1.0 |
>=1.21,<3.0 |
>=1.3,<3.0 |
>=0.18.3,<2.0 |
>=10.0,<18.0 |
>=1.11,<3.0 |
>=2023.1 |
>=3.9,<3.13 |
|
0.8.0 |
>=0.4.1,<1.0 |
>=1.21,<3.0 |
>=1.3,<3.0 |
>=0.18.3,<2.0 |
>=10.0,<18.0 |
>=1.11,<3.0 |
>=2023.1 |
>=3.9,<3.13 |
|
0.7.4 |
>=0.4.1,<1.0 |
>=1.21,<3.0 |
>=1.3,<3.0 |
>=0.18.3,<2.0 |
>=10.0,<18.0 |
>=1.11,<3.0 |
>=2023.1 |
>=3.9,<3.13 |
|
0.7.3 |
>=0.4.1,<1.0 |
>=1.21,<3.0 |
>=1.3,<3.0 |
>=0.18.3,<2.0 |
>=1.11,<3.0 |
>=2023.1 |
>=3.9,<3.13 |
||
0.7.2 |
>=0.4.1,<1.0 |
>=1.21,<3.0 |
>=1.3,<3.0 |
>=0.18.3,<2.0 |
>=1.11,<3.0 |
>=2023.1 |
>=3.9,<3.13 |
||
0.7.1 |
>=0.4.1,<1.0 |
>=1.21,<3.0 |
>=1.3,<3.0 |
>=0.18.3,<1.0 |
>=1.10,<3.0 |
>=2023.1 |
>=3.9,<3.13 |
||
0.7.0 |
>=0.4.1,<1.0 |
>=1.21,<2.0 |
>=1.3,<3.0 |
>=0.18.3,<1.0 |
>=1.10,<3.0 |
>=2023.1 |
>=3.9,<3.13 |
||
0.6.2 |
>=0.4.1,<1.0 |
>=1.21,<2.0 |
>=1.3,<3.0 |
>=0.18.3,<1.0 |
>=1.10,<3.0 |
>=2023.1 |
>=3.9,<3.13 |
||
0.6.1 |
>=0.4.1,<1.0 |
>=1.21,<2.0 |
>=1.3,<3.0 |
>=0.18.3,<1.0 |
>=1.10,<3.0 |
>=2023.1 |
>=3.9,<3.13 |
||
0.6.0 |
>=0.4.1,<1.0 |
>=1.21,<2.0 |
>=1.3,<3.0 |
>=0.18.3,<1.0 |
>=1.10,<3.0 |
>=2023.1 |
>=3.9,<3.13 |
||
0.5.0 |
>=0.4.1,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<1.0 |
>=1.10,<2.2 |
>=2023.1,<2023.13 |
>=3.9,<3.13 |
||
0.4.0 |
>=0.4.1,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<1.0 |
>=1.10,<2.2 |
>=2023.1,<2023.13 |
>=3.9,<3.13 |
||
0.3.1 |
>=0.4.1,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<1.0 |
>=1.10,<2.2 |
>=2023.1,<2023.13 |
>=3.9,<3.13 |
||
0.3.0 |
>=0.4.1,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<1.0 |
>=1.10,<2.2 |
>=2023.1,<2023.13 |
>=3.9,<3.13 |
||
0.2.2 |
>=0.4.1,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<1.0 |
>=1.10,<2.2 |
>=2023.1,<2023.13 |
>=3.9,<3.13 |
||
0.2.1 |
>=0.4.1,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<1.0 |
>=1.10,<2.2 |
>=2023.1,<2023.13 |
>=3.9,<3.13 |
||
0.2.0 |
>=0.4.1,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<1.0 |
>=1.10,<2.2 |
>=2023.1,<2023.13 |
>=3.9,<3.13 |
||
0.1.2 |
>=0.4.1,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<0.21 |
>=1.10,<2.2 |
>=2023.1,<2023.13 |
>=3.9,<3.13 |
||
0.1.1 |
>=0.4.1,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<0.20 |
>=1.10,<2.2 |
>=2023.1,<2023.13 |
>=3.9,<3.13 |
||
0.1.0 |
>=0.4.1,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<0.20 |
>=1.10,<2.2 |
>=2023.1,<2023.13 |
>=3.9,<3.12 |
||
0.0.26 |
>=0.4.1,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<0.20 |
>=1.10,<2.2 |
>=2023.1,<2023.13 |
>=3.9,<3.12 |
||
0.0.25 |
>=0.4.1,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<0.20 |
>=1.10,<2.2 |
>=2023.4,<2023.11 |
>=3.9,<3.12 |
||
0.0.24 |
>=0.3,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<0.20 |
>=1.10,<2.2 |
>=2023.3,<2023.9 |
>=3.9,<3.12 |
||
0.0.23 |
>=0.3,<0.5 |
>=1.21,<1.27 |
>=1.3,<2.2 |
>=0.18.3,<0.20 |
>=1.10,<2.1 |
>=2023.3,<2023.9 |
>=3.9,<3.12 |
||
0.0.22 |
>=0.3,<0.5 |
>=1.20,<1.26 |
>=1.3,<2.1 |
>=0.18.3,<0.19 |
>=1.10,<2.1 |
>=2023.3,<2023.9 |
>=3.9,<3.12 |
||
0.0.21 |
>=0.3,<0.5 |
>=1.20,<1.26 |
>=1.3,<2.1 |
>=0.18.3,<0.19 |
>=1.10,<2.1 |
>=2023.3,<2023.8 |
>=3.9,<3.12 |
||
0.0.20 |
>=0.3,<0.5 |
>=1.20,<1.26 |
>=1.3,<2.1 |
>=0.18.3,<0.19 |
>=1.10,<2.1 |
>=2023.3,<2023.8 |
>=3.9 |
Contributing
Contributions are welcome! We appreciate bug fixes, feature additions, documentation improvements, and more. Please check the contributing guidelines for details on:
- Setting up the development environment
- Code style and testing requirements
- Submitting pull requests
Whether you're fixing a bug or proposing a new feature, please open an issue first to discuss your changes.
API Stability
:warning: Important: As coola is under active development, its API is not yet stable and may
change between releases. We recommend pinning a specific version in your project’s dependencies to
ensure consistent behavior.
License
coola is licensed under BSD 3-Clause "New" or "Revised" license available in LICENSE
file.
1 maintainer
Metadata
1 maintainer
Release files for coola 1.1.11a2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| coola-1.1.11a2.tar.gz | 145.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| coola-1.1.11a2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 398.8 kB
Release files / coola-1.1.11a2.tar.gz
| Download URL | coola-1.1.11a2.tar.gz |
|---|---|
| Size | 145.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3755b7b778fd8ae17f391c670060bedd87df1a6b7d1801e2dfe34acb3fcaaded
|
|
BLAKE2b-256 checksum How to use checksums |
aec2c7434dd472d33af9d83fcf3087b27892a3f2836ea79c785fe053d527245a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / coola-1.1.11a2-py3-none-any.whl
| Download URL | coola-1.1.11a2-py3-none-any.whl |
|---|---|
| Size | 253.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6a2bb61e55ae3b3654a4b0d1a8a787ee4873e26f81f05df3bdb0374c718652dd
|
|
BLAKE2b-256 checksum How to use checksums |
276e58bef18ac4a9bcfca831d86ce9ec82f5dbb707dcf09d159e11d39ee25826
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
