PyRoaring

1.0.4 · active · verified Sun Mar 29

PyRoaring is a Python library providing an efficient and light-weight ordered set of integers. It serves as a Python wrapper for the highly optimized C library CRoaring, which implements Roaring Bitmaps. The library is actively maintained, with the current version being 1.0.4, and sees regular releases with new features and improvements.

Warnings

breaking Python 3.7 support was dropped in PyRoaring 1.0.0, and Python 3.8 support was dropped in PyRoaring 1.0.4. Users on these older Python versions must use an earlier PyRoaring release.
Fix: Upgrade to Python 3.9 or higher, or pin pyroaring to an earlier version (e.g., `<1.0.0` for Python 3.7, `<1.0.4` for Python 3.8).
breaking Prior to version 1.0.0, in-place operations where a BitMap was modified by itself (e.g., `bm &= bm`) were not correctly handled due to an underlying CRoaring library limitation. This was fixed in 1.0.0.
Fix: Upgrade to PyRoaring 1.0.0 or later to ensure correct behavior for in-place self-operations. If upgrading is not possible, avoid such operations or create a copy before modifying.
gotcha When compiling PyRoaring from source, specific Cython version compatibility issues have been noted. Version 1.0.2 restricted Cython to `<3.1.0` due to a bug, although earlier 0.4.3 added general Cython 3 compatibility. Ensure your Cython version is compatible with the PyRoaring version you are compiling.
Fix: If compiling from source, consult the PyRoaring release notes or `setup.py` for recommended Cython versions. For most users, installing pre-built wheels with `pip install pyroaring` avoids this issue.
gotcha Safe deserialization of bitmaps was introduced in PyRoaring 1.0.1. Earlier versions might be vulnerable to issues if deserializing untrusted or malformed data.
Fix: Upgrade to PyRoaring 1.0.1 or later to benefit from safe deserialization, especially when handling data from external sources.
gotcha PyRoaring offers two main classes: `BitMap` for 32-bit integers (0 to 2**32-1) and `BitMap64` for 64-bit integers (0 to 2**64-1). Using `BitMap` for values exceeding 2**32-1 will lead to incorrect behavior or errors.
Fix: Always use `from pyroaring import BitMap64` when working with integers that may exceed the 32-bit unsigned integer range.

Install

pip install pyroaring Install with pip
uv add pyroaring Install with uv

Imports

BitMap
```
from pyroaring import BitMap
```
BitMap64
```
from pyroaring import BitMap64
```
Use BitMap64 for integers larger than 2**32-1.

Quickstart

This example demonstrates creating two Roaring BitMaps, adding elements, initializing from a list, performing intersection and union operations, and checking for element existence.

from pyroaring import BitMap

bm1 = BitMap()
bm1.add(3)
bm1.add(18)

bm2 = BitMap([3, 27, 42])

print(f"bm1 = {bm1}")
print(f"bm2 = {bm2}")
print(f"bm1 & bm2 = {bm1 & bm2}")
print(f"bm1 | bm2 = {bm1 | bm2}")
print(f"Does bm1 contain 3? {3 in bm1}")

view raw JSON →