Bitsets
=======
|PyPI version| |License| |Supported Python| |Wheel|
|Build| |Codecov| |Readthedocs-stable| |Readthedocs-latest|
This package provides a memory-efficient pure-python **immutable ordered set
data type** for working with large numbers of subsets from a predetermined pool
of objects.
Given a name and a tuple of hashable objects, the ``bitset()``-function returns
a custom integer subclass for creating ordered subsets from the object pool.
Each instance is a Python integer where the presence/absence of the *nth* pool
item is its *nth* bit being set/unset (a.k.a. bit strings, powers of two, rank
in *colexicographical* order).
Being just a regular (arbitrary precision) integer with some convenience
methods for translating between unique object collections and bit patterns
allows to perform certain tasks in a more natural way, e.g. sorting a
collection of sets lexicographically, or enumerating possible combinations in
an ordered fashion.
Links
-----
- GitHub: https://github.com/xflr6/bitsets
- PyPI: https://pypi.org/project/bitsets/
- Documentation: https://bitsets.readthedocs.io
- Changelog: https://bitsets.readthedocs.io/en/latest/changelog.html
- Issue Tracker: https://github.com/xflr6/bitsets/issues
- Download: https://pypi.org/project/bitsets/#files
Installation
------------
This package runs under Python 3.7+ and has no required dependencies,
use pip_ to install:
.. code:: bash
$ pip install bitsets
Quickstart
----------
Create a class for sets taken from your pool of objects:
.. code:: python
>>> from bitsets import bitset
>>> PYTHONS = ('Chapman', 'Cleese', 'Gilliam', 'Idle', 'Jones', 'Palin')
>>> Pythons = bitset('Pythons', PYTHONS)
Access its maximal and minimal instances. Retrieve instance members in
definition order:
.. code:: python
>>> Pythons.supremum
Pythons(['Chapman', 'Cleese', 'Gilliam', 'Idle', 'Jones', 'Palin'])
>>> Pythons.infimum
Pythons()
>>> Pythons(['Idle', 'Gilliam', 'Idle', 'Idle']).members()
('Gilliam', 'Idle')
Translate to/from bit string, boolean sequence, and int:
.. code:: python
>>> Pythons(['Chapman', 'Gilliam']).bits()
'101000'
>>> Pythons.frombits('101000')
Pythons(['Chapman', 'Gilliam'])
>>> Pythons(['Chapman', 'Gilliam']).bools()
(True, False, True, False, False, False)
>>> Pythons.frombools([True, None, 1, False, 0])
Pythons(['Chapman', 'Gilliam'])
>>> int(Pythons(['Chapman', 'Gilliam']))
5
>>> Pythons.fromint(5)
Pythons(['Chapman', 'Gilliam'])
Set operation and comparison methods (cf. build-in ``frozenset``):
.. code:: python
>>> Pythons(['Jones', 'Cleese', 'Idle']).intersection(Pythons(['Idle']))
Pythons(['Idle'])
>>> Pythons(['Idle']).union(Pythons(['Jones', 'Cleese']))
Pythons(['Cleese', 'Idle', 'Jones'])
>>> Pythons.supremum.difference(Pythons(['Chapman', 'Cleese']))
Pythons(['Gilliam', 'Idle', 'Jones', 'Palin'])
>>> Pythons(['Palin', 'Jones']).symmetric_difference(Pythons(['Cleese', 'Jones']))
Pythons(['Cleese', 'Palin'])
>>> Pythons(['Gilliam']).issubset(Pythons(['Cleese', 'Palin']))
False
>>> Pythons(['Cleese', 'Palin']).issuperset(Pythons())
True
Further reading
---------------
- https://wiki.python.org/moin/BitManipulation
- https://wiki.python.org/moin/BitArrays
- https://en.wikipedia.org/wiki/Bit_array
- https://en.wikipedia.org/wiki/Bit_manipulation
- https://en.wikipedia.org/wiki/Lexicographical_order
- https://en.wikipedia.org/wiki/Colexicographical_order
See also
--------
- bitarray_ |--| efficient boolean array implemented as C extension
- bitstring_ |--| pure-Python bit string based on ``bytearray``
- BitVector_ |--| pure-Python bit array based on unsigned short ``array``
- Bitsets_ |--| Cython interface to fast bitsets in Sage
- bitfield_ |--| Cython positive integer sets
- intbitset_ |--| integer bit sets as C extension
- gmpy2_ |--| fast arbitrary precision integer arithmetic
License
-------
Bitsets is distributed under the `MIT license`_.
.. _pip: https://pip.readthedocs.io
.. _bitarray: https://pypi.org/project/bitarray/
.. _bitstring: https://pypi.org/project/bitstring/
.. _BitVector: https://pypi.org/project/BitVector/
.. _Bitsets: https://www.sagemath.org/doc/reference/data_structures/sage/data_structures/bitset.html
.. _bitfield: https://pypi.org/project/bitfield/
.. _intbitset: https://pypi.org/project/intbitset/
.. _gmpy2: https://pypi.org/project/gmpy2/
.. _MIT license: https://opensource.org/licenses/MIT
.. |--| unicode:: U+2013
.. |PyPI version| image:: https://img.shields.io/pypi/v/bitsets.svg
:target: https://pypi.org/project/bitsets/
:alt: Latest PyPI Version
.. |License| image:: https://img.shields.io/pypi/l/bitsets.svg
:target: https://github.com/xflr6/bitsets/blob/master/LICENSE.txt
:alt: License
.. |Supported Python| image:: https://img.shields.io/pypi/pyversions/bitsets.svg
:target: https://pypi.org/project/bitsets/
:alt: Supported Python Versions
.. |Wheel| image:: https://img.shields.io/pypi/wheel/bitsets.svg
:target: https://pypi.org/project/bitsets/#files
:alt: Wheel format
.. |Build| image:: https://github.com/xflr6/bitsets/actions/workflows/build.yaml/badge.svg?branch=master
:target: https://github.com/xflr6/bitsets/actions/workflows/build.yaml?query=branch%3Amaster
:alt: Build
.. |Codecov| image:: https://codecov.io/gh/xflr6/bitsets/branch/master/graph/badge.svg
:target: https://codecov.io/gh/xflr6/bitsets
:alt: Codecov
.. |Readthedocs-stable| image:: https://readthedocs.org/projects/bitsets/badge/?version=stable
:target: https://bitsets.readthedocs.io/en/stable/?badge=stable
:alt: Readthedocs stable
.. |Readthedocs-latest| image:: https://readthedocs.org/projects/bitsets/badge/?version=latest
:target: https://bitsets.readthedocs.io/en/latest/?badge=latest
:alt: Readthedocs latest
Raw data
{
"_id": null,
"home_page": "https://github.com/xflr6/bitsets",
"name": "bitsets",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "ordered set finite immutable bit string array map field",
"author": "Sebastian Bank",
"author_email": "sebastian.bank@uni-leipzig.de",
"download_url": "https://files.pythonhosted.org/packages/4d/a8/8934a8201288c12d4fbae78d0adb5f39255ba781ba4bf83e18abbf566786/bitsets-0.8.4.zip",
"platform": "any",
"description": "Bitsets\n=======\n\n|PyPI version| |License| |Supported Python| |Wheel|\n\n|Build| |Codecov| |Readthedocs-stable| |Readthedocs-latest|\n\nThis package provides a memory-efficient pure-python **immutable ordered set\ndata type** for working with large numbers of subsets from a predetermined pool\nof objects.\n\nGiven a name and a tuple of hashable objects, the ``bitset()``-function returns\na custom integer subclass for creating ordered subsets from the object pool.\nEach instance is a Python integer where the presence/absence of the *nth* pool\nitem is its *nth* bit being set/unset (a.k.a. bit strings, powers of two, rank\nin *colexicographical* order).\n\nBeing just a regular (arbitrary precision) integer with some convenience\nmethods for translating between unique object collections and bit patterns\nallows to perform certain tasks in a more natural way, e.g. sorting a\ncollection of sets lexicographically, or enumerating possible combinations in\nan ordered fashion.\n\n\nLinks\n-----\n\n- GitHub: https://github.com/xflr6/bitsets\n- PyPI: https://pypi.org/project/bitsets/\n- Documentation: https://bitsets.readthedocs.io\n- Changelog: https://bitsets.readthedocs.io/en/latest/changelog.html\n- Issue Tracker: https://github.com/xflr6/bitsets/issues\n- Download: https://pypi.org/project/bitsets/#files\n\n\nInstallation\n------------\n\nThis package runs under Python 3.7+ and has no required dependencies,\nuse pip_ to install:\n\n.. code:: bash\n\n $ pip install bitsets\n\n\nQuickstart\n----------\n\nCreate a class for sets taken from your pool of objects:\n\n.. code:: python\n\n >>> from bitsets import bitset\n\n >>> PYTHONS = ('Chapman', 'Cleese', 'Gilliam', 'Idle', 'Jones', 'Palin')\n\n >>> Pythons = bitset('Pythons', PYTHONS)\n\n\nAccess its maximal and minimal instances. Retrieve instance members in\ndefinition order:\n\n.. code:: python\n\n >>> Pythons.supremum\n Pythons(['Chapman', 'Cleese', 'Gilliam', 'Idle', 'Jones', 'Palin'])\n\n >>> Pythons.infimum\n Pythons()\n\n >>> Pythons(['Idle', 'Gilliam', 'Idle', 'Idle']).members()\n ('Gilliam', 'Idle')\n\n\nTranslate to/from bit string, boolean sequence, and int:\n\n.. code:: python\n\n >>> Pythons(['Chapman', 'Gilliam']).bits()\n '101000'\n\n >>> Pythons.frombits('101000')\n Pythons(['Chapman', 'Gilliam'])\n\n >>> Pythons(['Chapman', 'Gilliam']).bools()\n (True, False, True, False, False, False)\n\n >>> Pythons.frombools([True, None, 1, False, 0])\n Pythons(['Chapman', 'Gilliam'])\n \n >>> int(Pythons(['Chapman', 'Gilliam']))\n 5\n\n >>> Pythons.fromint(5)\n Pythons(['Chapman', 'Gilliam'])\n \n\nSet operation and comparison methods (cf. build-in ``frozenset``):\n\n.. code:: python\n\n >>> Pythons(['Jones', 'Cleese', 'Idle']).intersection(Pythons(['Idle']))\n Pythons(['Idle'])\n\n >>> Pythons(['Idle']).union(Pythons(['Jones', 'Cleese']))\n Pythons(['Cleese', 'Idle', 'Jones'])\n\n >>> Pythons.supremum.difference(Pythons(['Chapman', 'Cleese']))\n Pythons(['Gilliam', 'Idle', 'Jones', 'Palin'])\n\n >>> Pythons(['Palin', 'Jones']).symmetric_difference(Pythons(['Cleese', 'Jones']))\n Pythons(['Cleese', 'Palin'])\n\n >>> Pythons(['Gilliam']).issubset(Pythons(['Cleese', 'Palin']))\n False\n\n >>> Pythons(['Cleese', 'Palin']).issuperset(Pythons())\n True\n\n\nFurther reading\n---------------\n\n- https://wiki.python.org/moin/BitManipulation\n- https://wiki.python.org/moin/BitArrays\n\n- https://en.wikipedia.org/wiki/Bit_array\n- https://en.wikipedia.org/wiki/Bit_manipulation\n\n- https://en.wikipedia.org/wiki/Lexicographical_order\n- https://en.wikipedia.org/wiki/Colexicographical_order\n\n\nSee also\n--------\n\n- bitarray_ |--| efficient boolean array implemented as C extension\n- bitstring_ |--| pure-Python bit string based on ``bytearray``\n- BitVector_ |--| pure-Python bit array based on unsigned short ``array``\n- Bitsets_ |--| Cython interface to fast bitsets in Sage\n- bitfield_ |--| Cython positive integer sets\n- intbitset_ |--| integer bit sets as C extension \n- gmpy2_ |--| fast arbitrary precision integer arithmetic\n\n\nLicense\n-------\n\nBitsets is distributed under the `MIT license`_.\n\n\n.. _pip: https://pip.readthedocs.io\n\n.. _bitarray: https://pypi.org/project/bitarray/\n.. _bitstring: https://pypi.org/project/bitstring/\n.. _BitVector: https://pypi.org/project/BitVector/\n.. _Bitsets: https://www.sagemath.org/doc/reference/data_structures/sage/data_structures/bitset.html\n.. _bitfield: https://pypi.org/project/bitfield/\n.. _intbitset: https://pypi.org/project/intbitset/\n.. _gmpy2: https://pypi.org/project/gmpy2/\n\n.. _MIT license: https://opensource.org/licenses/MIT\n\n\n.. |--| unicode:: U+2013\n\n\n.. |PyPI version| image:: https://img.shields.io/pypi/v/bitsets.svg\n :target: https://pypi.org/project/bitsets/\n :alt: Latest PyPI Version\n.. |License| image:: https://img.shields.io/pypi/l/bitsets.svg\n :target: https://github.com/xflr6/bitsets/blob/master/LICENSE.txt\n :alt: License\n.. |Supported Python| image:: https://img.shields.io/pypi/pyversions/bitsets.svg\n :target: https://pypi.org/project/bitsets/\n :alt: Supported Python Versions\n.. |Wheel| image:: https://img.shields.io/pypi/wheel/bitsets.svg\n :target: https://pypi.org/project/bitsets/#files\n :alt: Wheel format\n\n.. |Build| image:: https://github.com/xflr6/bitsets/actions/workflows/build.yaml/badge.svg?branch=master\n :target: https://github.com/xflr6/bitsets/actions/workflows/build.yaml?query=branch%3Amaster\n :alt: Build\n.. |Codecov| image:: https://codecov.io/gh/xflr6/bitsets/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/xflr6/bitsets\n :alt: Codecov\n.. |Readthedocs-stable| image:: https://readthedocs.org/projects/bitsets/badge/?version=stable\n :target: https://bitsets.readthedocs.io/en/stable/?badge=stable\n :alt: Readthedocs stable\n.. |Readthedocs-latest| image:: https://readthedocs.org/projects/bitsets/badge/?version=latest\n :target: https://bitsets.readthedocs.io/en/latest/?badge=latest\n :alt: Readthedocs latest\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Ordered subsets over a predefined domain",
"version": "0.8.4",
"project_urls": {
"CI": "https://github.com/xflr6/bitsets/actions",
"Changelog": "https://bitsets.readthedocs.io/en/latest/changelog.html",
"Coverage": "https://codecov.io/gh/xflr6/bitsets",
"Documentation": "https://bitsets.readthedocs.io",
"Homepage": "https://github.com/xflr6/bitsets",
"Issue Tracker": "https://github.com/xflr6/bitsets/issues"
},
"split_keywords": [
"ordered",
"set",
"finite",
"immutable",
"bit",
"string",
"array",
"map",
"field"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b8541ed39efddcb862dcc9cf777fe4b89d6081539a7bc91b07b46dba45eafc83",
"md5": "860a8ae95f7764ee32f5271baf38db6c",
"sha256": "074763e47cd9a28704cbc979ce5ace600695eee6315845e12a01fb2b841f3c21"
},
"downloads": -1,
"filename": "bitsets-0.8.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "860a8ae95f7764ee32f5271baf38db6c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13588,
"upload_time": "2022-06-13T08:24:35",
"upload_time_iso_8601": "2022-06-13T08:24:35.253859Z",
"url": "https://files.pythonhosted.org/packages/b8/54/1ed39efddcb862dcc9cf777fe4b89d6081539a7bc91b07b46dba45eafc83/bitsets-0.8.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4da88934a8201288c12d4fbae78d0adb5f39255ba781ba4bf83e18abbf566786",
"md5": "53d2d882b6baa5e63a582cecda768a44",
"sha256": "313ec5807f6ea2a95dec5fdbf5d1229a34f6d49f081584ae4be4bc279f5831cd"
},
"downloads": -1,
"filename": "bitsets-0.8.4.zip",
"has_sig": false,
"md5_digest": "53d2d882b6baa5e63a582cecda768a44",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 119459,
"upload_time": "2022-06-13T08:24:37",
"upload_time_iso_8601": "2022-06-13T08:24:37.815288Z",
"url": "https://files.pythonhosted.org/packages/4d/a8/8934a8201288c12d4fbae78d0adb5f39255ba781ba4bf83e18abbf566786/bitsets-0.8.4.zip",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-06-13 08:24:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xflr6",
"github_project": "bitsets",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "bitsets"
}
JSON
