Skip to main content

Ordered subsets over a predefined domain

Project description

Latest PyPI Version License Supported Python Versions Wheel format

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.

Installation

This package runs under Python 3.7+ 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

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bitsets-0.8.4.zip (119.5 kB view hashes)

Uploaded Source

Built Distribution

bitsets-0.8.4-py3-none-any.whl (13.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page