Metadata-Version: 2.1
Name: eth-bloom
Version: 1.0.2
Summary: Python implementation of the Ethereum Trie structure
Home-page: https://github.com/ethereum/eth-bloom
Author: Piper Merriam
Author-email: pipermerriam@gmail.com
License: MIT
Keywords: ethereum blockchain evm trie merkle
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.5, !=3.5.2, <4
Requires-Dist: eth-hash (<0.3.0,>=0.1.0a3)
Provides-Extra: deploy
Requires-Dist: bumpversion (<1.0.0,>=0.5.3) ; extra == 'deploy'
Requires-Dist: wheel (<1.0.0,>=0.30.0) ; extra == 'deploy'
Provides-Extra: dev
Requires-Dist: bumpversion (<1.0.0,>=0.5.3) ; extra == 'dev'
Requires-Dist: wheel (<1.0.0,>=0.30.0) ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'
Requires-Dist: pytest (==3.0.7) ; extra == 'dev'
Requires-Dist: hypothesis (==3.7.0) ; extra == 'dev'
Requires-Dist: tox (==2.6.0) ; extra == 'dev'
Requires-Dist: flake8 (<4.0.0,>=3.5.0) ; extra == 'dev'
Provides-Extra: lint
Requires-Dist: flake8 (<4.0.0,>=3.5.0) ; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest (==3.0.7) ; extra == 'test'
Requires-Dist: hypothesis (==3.7.0) ; extra == 'test'
Requires-Dist: tox (==2.6.0) ; extra == 'test'

Ethereum Bloom Filter
=====================

|Build Status| |PyPI version| |Python versions|

A python implementation of the bloom filter used by Ethereum.

    This library and repository was previously located at
    https://github.com/pipermerriam/ethereum-bloom. It was transferred
    to the Ethereum foundation github in November 2017 and renamed to
    ``eth-bloom``. The PyPi package was also renamed from
    ``ethereum-bloom`` to \`eth-bloom.

For more information on what Ethereum Bloom Filters are see
`here <what_Is_eth-bloom.txt>`__

Installation
------------

.. code:: shell

    $ pip install eth-bloom

Development
-----------

.. code:: sh

    pip install -e .[dev]

Running the tests
~~~~~~~~~~~~~~~~~

You can run the tests with:

.. code:: sh

    py.test tests

Or you can install ``tox`` to run the full test suite.

Releasing
~~~~~~~~~

Pandoc is required for transforming the markdown README to the proper
format to render correctly on pypi.

For Debian-like systems:

::

    apt install pandoc

Or on OSX:

.. code:: sh

    brew install pandoc

To release a new version:

.. code:: sh

    bumpversion $$VERSION_PART_TO_BUMP$$
    git push && git push --tags
    make release

How to bumpversion
^^^^^^^^^^^^^^^^^^

The version format for this repo is ``{major}.{minor}.{patch}`` for
stable, and ``{major}.{minor}.{patch}-{stage}.{devnum}`` for unstable
(``stage`` can be alpha or beta).

To issue the next version in line, use bumpversion and specify which
part to bump, like ``bumpversion minor`` or ``bumpversion devnum``.

If you are in a beta version, ``bumpversion stage`` will switch to a
stable.

To issue an unstable version when the current version is stable, specify
the new version explicitly, like
``bumpversion --new-version 4.0.0-alpha.1 devnum``

Usage
-----

The ``BloomFilter`` object

.. code:: python

    >>> from eth_bloom import BloomFilter
    >>> b = BloomFilter()
    >>> b'a value' in b  # check whether a value is present
    False
    >>> b.add(b'a value')  # add a single value
    >>> b'a value' in b
    True
    >>> int(b)  # cast to an integer
    3458628712844765018311492773359360516229024449585949240367644166080576879632652362184119765613545163153674691520749911733485693171622325900647078772681584616740134230153806267998022370194756399579977294154062696916779055028045657302214591620589415314367270329881298073237757853875497241510733954508399863880080986777555986663988492288946856978031023631618215522505971170427986911575695114157059398791122395379400594948096
    >>> bin(b)  # cast to a binary string
    '0b100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'

You can also add an iterable of items to a bloom filter.

.. code:: python

    >>> b = BloomFilter()
    >>> b'value-a' in b
    False
    >>> b'value-b' in b
    False
    >>> b.extend([b'value-a', b'value-b'])
    >>> b'value-a' in b
    True
    >>> b'value-b' in b
    True

You can initialize a bloom filter from an iterable of byte strings.

.. code:: python

    >>> b = BloomFilter.from_iterable([b'value-a', b'value-b'])  # initialize from an iterable of values.
    >>> b'value-a' in b
    True
    >>> b'value-b' in b
    True

You can initialize a bloom filter from the integer representation of the
bloom bits.

.. code:: python

    >>> b = BloomFilter(3458628712844765018311492773359360516229024449585949240367644166080576879632652362184119765613545163153674691520749911733485693171622325900647078772681584616740134230153806267998022370194756399579977294154062696916779055028045657302214591620589415314367270329881298073237757853875497241510733954508399863880080986777555986663988492288946856978031023631618215522505971170427986911575695114157059398791122395379400594948096)
    >>> b'a value' in b
    True

You can also merge bloom filters

.. code:: python

    >>> from eth_bloom import BloomFilter
    >>> b1 = BloomFilter()
    >>> b2 = BloomFilter()
    >>> b1.add(b'a')
    >>> b1.add(b'common')
    >>> b2.add(b'b')
    >>> b2.add(b'common')
    >>> b'a' in b1
    True
    >>> b'b' in b1
    False
    >>> b'common' in b1
    True
    >>> b'a' in b2
    False
    >>> b'b' in b2
    True
    >>> b'common' in b2
    True
    >>> b3 = b1 + b2  # using addition
    >>> b'a' in b3
    True
    >>> b'b' in b3
    True
    >>> b'common' in b3
    True
    >>> b4 = b1 | b2  # or using bitwise or
    >>> b'a' in b4
    True
    >>> b'b' in b4
    True
    >>> b'common' in b4
    True
    >>> b1 |= b2  # or using in-place operations (works with += too)
    >>> b'a' in b1
    True
    >>> b'b' in b1
    True
    >>> b'common' in b1
    True

.. |Build Status| image:: https://travis-ci.org/ethereum/eth-bloom.svg?branch=master
   :target: https://travis-ci.org/ethereum/eth-bloom
.. |PyPI version| image:: https://badge.fury.io/py/eth-bloom.svg
   :target: https://badge.fury.io/py/eth-bloom
.. |Python versions| image:: https://img.shields.io/pypi/pyversions/eth-bloom.svg
   :target: https://pypi.python.org/pypi/eth-bloom


