Bitsets

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.8+ and has no required dependencies, use pip to install:

$ pip install bitsets

Quickstart

Create a class for sets taken from your pool of objects:

>>> 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:

>>> 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:

>>> 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):

>>> 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.