bloom-filter2

library2.0.0pypypi✓ verified 21d ago

bloom-filter2 is a pure Python Bloom filter module, providing a space-efficient and probabilistic set data structure. It supports mmap, in-memory, and disk-seek backends, offering a balance between memory usage and performance. The library automatically calculates optimal Bloom filter parameters based on user-specified maximum elements and desired false positive rate. It is compatible with CPython 3.x, Pypy, and Jython and is actively maintained.

database

pip install bloom-filter2

github ↗package ↗

INSTALL

IMPORT

SIG · BLOOM-FILTER2

bloom-filter2

databasepythonv2.0.0

Install

2.3s avg

Import

10ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.008s · 19MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.3s · import 0.006s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BloomFilter

✓ from bloom_filter2 import BloomFilter

Initialize a BloomFilter, add elements, and check for membership using the `in` operator. The `max_elements` and `error_rate` parameters control the filter's capacity and false positive probability.

from bloom_filter2 import BloomFilter # Instantiate BloomFilter with custom settings: # max_elements is how many elements you expect the filter to hold. # error_rate defines accuracy (false positive probability). # You can use defaults with `BloomFilter()` without any arguments. bloom = BloomFilter(max_elements=10000, error_rate=0.01) # Test whether the bloom-filter has seen a key: assert "test-key" not in bloom # Mark the key as seen bloom.add("test-key") # Now check again assert "test-key" in bloom # Example with a different item (should be False initially) assert "another-key" not in bloom

Debug

Known issues

gotchaBloom filters are probabilistic data structures. A membership query (`item in bloom`) returning `True` means the item *might* be in the set (with a specified false positive probability), while `False` means it is *definitely not* in the set. False negatives are not possible.

fix

Always account for the possibility of false positives in your application logic, especially when querying items that are not expected to be present.

affects: All

gotchaThe false positive rate of a Bloom filter increases as more elements are added, especially if the number of added elements significantly exceeds the `max_elements` specified during initialization. Over-filling the filter will severely degrade its accuracy and utility.

fix

Accurately estimate `max_elements` for your use case and consider re-initializing or creating a new Bloom filter if the number of elements grows beyond expectations. Monitor the actual false positive rate if critical.

affects: All

breakingThe previous `bloom-filter` package (without '2') is unmaintained and should not be used. Users migrating from `bloom-filter` must switch to `bloom-filter2` and update import paths from `from bloom_filter import BloomFilter` to `from bloom_filter2 import BloomFilter`.

fix

Uninstall `bloom-filter` and `pip install bloom-filter2`. Update all import statements to `from bloom_filter2 import BloomFilter`.

affects: < 2.0.0 (for `bloom-filter` package)

gotchaThe efficiency (memory usage) and accuracy (false positive rate) of the Bloom filter are directly determined by the `max_elements` and `error_rate` parameters provided during instantiation. Poor selection can lead to either excessive memory consumption or an unacceptably high false positive rate.

fix

Carefully consider the expected maximum number of elements and the tolerable false positive rate for your application to choose optimal parameters. The library handles the internal bit array size and hash function count based on these inputs.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'bloom_filter'

Developers often encounter this when migrating from the older, unmaintained `bloom-filter` library to `bloom-filter2`, or mistakenly using the old package name in their import statement.

fix

First, ensure `bloom-filter2` is installed: `pip install bloom-filter2`. Then, update your import statements from `from bloom_filter import BloomFilter` to `from bloom_filter2 import BloomFilter`.

ModuleNotFoundError: No module named 'bloom_filter2'

This error occurs when the `bloom-filter2` package has not been installed in the active Python environment, or the Python interpreter cannot locate the installed package.

fix

Install the package using pip: `pip install bloom-filter2`. If using a virtual environment, ensure it is activated before installation.

AttributeError: 'BloomFilter' object has no attribute 'remove'

Standard Bloom filters are probabilistic data structures designed for adding elements and checking membership, but they do not support the removal of individual elements. Attempting to call a `remove` method will raise an AttributeError.

fix

Bloom filters inherently do not support individual element removal. If an element needs to be 'removed', it typically implies a need for a different data structure, a counting Bloom filter (not a feature of `bloom-filter2`), or re-initializing the Bloom filter with the remaining desired elements. To empty the entire filter, use `bloom_filter_instance.clear()`.

high false positive rate or excessive memory usage

This is a common behavioral problem, not a Python error, resulting from sub-optimal configuration of the `max_elements` and `error_rate` parameters, or exceeding the `max_elements` specified during initialization.

fix

Carefully estimate the maximum number of elements (`max_elements`) your Bloom filter is expected to hold and select a tolerable `error_rate` when instantiating `BloomFilter`. If the number of elements grows beyond expectations, consider re-initializing with larger parameters or using multiple Bloom filters.

Upgrade

Version history

2.0.0latest on PyPI · released May 5, 2021

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/remram44/python-bloom-filter ↗

packagehttps://pypi.org/project/bloom-filter2/ ↗