Package: bitlist
Pure-Python library for working with bit vectors.PurposeThis library allows programmers to work with bit vectors using a pure-Python data structure. Its design prioritizes interoperability with built-in Python classes and operators.Installation and UsageThis library is available as apackage on PyPI:python-mpipinstallbitlistThe library can be imported in the usual way:importbitlistfrombitlistimportbitlistExamplesThis library makes it possible to construct bit vectors from a variety of representations (including integers, bytes-like objects, strings of binary digits, lists of binary digits, and other bit vectors). Integer arguments are converted into a big-endian binary representation:>>>bitlist(123)bitlist('1111011')>>>bitlist(bytes([255,254]))bitlist('1111111111111110')>>>bitlist('101')bitlist('101')>>>bitlist([1,0,1,1])bitlist('1011')>>>bitlist(bitlist('1010'))bitlist('1010')The optionallengthparameter can be used to specify the length of the created bit vector (padding consisting of zero bits is applied automaticallyon the left-hand size, if necessary):>>>bitlist(bytes([123]),length=16)bitlist('0000000001111011')>>>bitlist(16,64)bitlist('0000000000000000000000000000000000000000000000000000000000010000')>>>bitlist(bitlist(123),8)bitlist('01111011')If thelengthparameter has a value that is less than the minimum number of bits that would be included according to the default constructor behaviors, the bit vector is truncatedon the left-hand sideto match the specified length:>>>bitlist(bytes([123]),length=7)bitlist('1111011')>>>bitlist(bytes([123]),4)bitlist('1011')>>>bitlist(bytes([123]),2)bitlist('11')>>>bitlist(bytes([123]),0)bitlist()Bit vectors are iterable sequences of individual bits (where each bit is represented as an integer). Both slice notation and retrieval of individual bits by index are supported. Furthermore, methods are available for converting a bit vector into other common representations:>>>b=bitlist('1111011')>>>b[1:-1]bitlist('11101')>>>b[0]1>>>[bitforbitinb][1,1,1,1,0,1,1]>>>b.bin()'1111011'>>>b.hex()'7b'>>>list(b.to_bytes())[123]Concatenation,partitioning,subscription and slicing,shift and rotation,comparison, andlogicaloperations are also supported by instances of thebitlistclass. The larger example below – a bitwise addition function – illustrates the use of various operators supported by instances of thebitlistclass:>>>defadd(x,y):..."""Bitwise addition algorithm."""...r=bitlist(0)...carry=0...# Use negative indices for big-endian interface....foriinrange(1,max(len(x),len(y))+1):...r[-i]=(x[-i]^y[-i])^carry...carry=(x[-i]&y[-i])|(x[-i]&carry)|(y[-i]&carry)...r[-(max(len(x),len(y))+1)]=carry...returnr...>>>int(add(bitlist(123),bitlist(456)))579Thetesting scriptthat accompanies this library contains additional examples of bitwise arithmetic operations implemented with the help ofbitlistoperators.DevelopmentAll installation and development dependencies are fully specified inpyproject.toml. Theproject.optional-dependenciesobject is used tospecify optional requirementsfor various development tasks. This makes it possible to specify additional options (such asdocs,lint, and so on) when performing installation usingpip:python-mpipinstall.[docs,lint]DocumentationThe documentation can be generated automatically from the source files usingSphinx:python-mpipinstall.[docs]cddocssphinx-apidoc-f-E--templatedir=_templates-o_source..&&makehtmlTesting and ConventionsAll unit tests are executed and their coverage is measured when usingpytest(see thepyproject.tomlfile for configuration details):python-mpipinstall.[test]python-mpytestThe subset of the unit tests included in the module itself and thedocumentation examplesthat appear in the testing script can be executed separately usingdoctest:pythonsrc/bitlist/bitlist.py-vpythontest/test_bitlist.py-vStyle conventions are enforced usingPylint:python-mpipinstall.[lint]python-mpylintsrc/bitlisttest/test_bitlist.pyContributionsIn order to contribute to the source code, open an issue or submit a pull request on theGitHub pagefor this library.VersioningBeginning with version 0.3.0, the version number format for this library and the changes to the library associated with version number increments conform withSemantic Versioning 2.0.0.PublishingThis library can be published as apackage on PyPIby a package maintainer. First, install the dependencies required for packaging and publishing:python-mpipinstall.[publish]Ensure that the correct version number appears inpyproject.toml, and that any links in this README document to the Read the Docs documentation of this package (or its dependencies) have appropriate version numbers. Also ensure that the Read the Docs project for this library has anautomation rulethat activates and sets as the default all tagged versions. Create and push a tag for this version (replacing?.?.?with the version number):gittag?.?.?gitpushorigin?.?.?Remove any old build/distribution files. Then, package the source into a distribution archive:rm-rfbuilddistsrc/*.egg-infopython-mbuild--sdist--wheel.Finally, upload the package distribution archive toPyPI:python-mtwineuploaddist/*