or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdcore-operations.mdcreation-conversion.mdindex.mdutility-functions.md
tile.json

tessl/pypi-bitarray

Efficient arrays of booleans with comprehensive sequence operations, bitwise operations, and specialized functionality for encoding/decoding variable-length prefix codes.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/bitarray@3.7.x

To install, run

npx @tessl/cli install tessl/pypi-bitarray@3.7.0

index.mddocs/

Bitarray

Bitarray provides an efficient object type for representing arrays of booleans. Bitarrays behave like Python lists but store data as packed bits, using one byte for every eight bits. The library offers comprehensive sequence operations, bitwise operations, and specialized functionality for encoding/decoding variable-length prefix codes, with all core operations implemented in C for maximum performance.

Package Information

  • Package Name: bitarray
  • Package Type: pypi
  • Language: Python (with C extensions)
  • Installation: pip install bitarray

Core Imports

from bitarray import bitarray, frozenbitarray, decodetree, bits2bytes, get_default_endian, test

For utility functions:

from bitarray.util import zeros, ones, ba2hex, hex2ba, ba2int, int2ba

Basic Usage

from bitarray import bitarray
from bitarray.util import zeros, ones, ba2hex

# Create bitarrays
a = bitarray('1010110')        # From string
b = bitarray([1, 0, 1, 0])     # From list
c = zeros(8)                   # All zeros
d = ones(5)                    # All ones

# Basic operations
print(len(a))                  # 7
print(a[2])                    # 1
a.append(1)                    # Add bit
a.extend('01')                 # Add multiple bits

# Bitwise operations
result = a & b                 # AND
result = a | b                 # OR  
result = a ^ b                 # XOR
result = ~a                    # NOT
result = a << 2                # Left shift
result = a >> 1                # Right shift

# Conversions
hex_str = ba2hex(a)            # To hexadecimal
bytes_data = a.tobytes()       # To bytes
int_val = a.count()            # Count set bits

# Search operations
pos = a.find(bitarray('10'))   # Find subsequence
all_pos = list(a.search(bitarray('1')))  # Find all occurrences

# Immutable version
frozen = frozenbitarray(a)     # Hashable, immutable

Architecture

Bitarray's design centers around efficient bit manipulation and storage:

  • Core bitarray class: Sequence-like interface with comprehensive bit operations
  • C implementation: Core operations implemented in C for maximum performance
  • Buffer protocol: Zero-copy integration with NumPy and memory-mapped files
  • Endianness support: Little-endian and big-endian bit representations
  • Utility module: Extended functionality for specific use cases
  • Immutable variant: frozenbitarray for hashable bit sequences

The library supports both individual bit operations and bulk operations on bit sequences, with optimized algorithms for common patterns like searching, counting, and bitwise arithmetic.

Capabilities

Core Operations

Fundamental bitarray operations including creation, modification, sequence operations, and bitwise arithmetic. These form the foundation for all bit manipulation tasks.

class bitarray:
    def __init__(self, initializer=0, /, endian='big', buffer=None) -> None: ...
    def append(self, value: int) -> None: ...
    def extend(self, x: Union[str, Iterable[int]]) -> None: ...
    def count(self, sub_bitarray=1, start=0, stop=None, step=1) -> int: ...
    def find(self, sub_bitarray, start=0, stop=None, right=False) -> int: ...
    def search(self, sub_bitarray, start=0, stop=None, right=False) -> Iterator[int]: ...
    
    # Properties
    @property
    def endian(self) -> str: ...
    @property
    def nbytes(self) -> int: ...
    @property
    def readonly(self) -> bool: ...

Core Operations

Creation and Conversion

Comprehensive methods for creating bitarrays from various sources and converting to different formats including integers, hex strings, bytes, and other representations.

# Core conversion methods
def tobytes(self) -> bytes: ...
def tolist(self) -> list[int]: ...
def to01(self, group=0, sep='') -> str: ...
def frombytes(self, a: bytes) -> None: ...

# Utility functions
def zeros(length: int, endian: Optional[str] = None) -> bitarray: ...
def ones(length: int, endian: Optional[str] = None) -> bitarray: ...
def ba2int(a: bitarray, signed: bool = False) -> int: ...
def int2ba(i: int, length: Optional[int] = None, endian: Optional[str] = None, signed: bool = False) -> bitarray: ...
def ba2hex(a: bitarray, group: int = 0, sep: str = '') -> str: ...
def hex2ba(s: str, endian: Optional[str] = None) -> bitarray: ...

Creation and Conversion

Utility Functions

Extended functionality from the bitarray.util module including random generation, analysis functions, pretty printing, compression, and specialized bit manipulation operations.

def urandom(length: int, endian: Optional[str] = None) -> bitarray: ...
def count_n(a: bitarray, n: int, value: int = 1) -> int: ...
def parity(a: bitarray) -> int: ...
def count_and(a: bitarray, b: bitarray) -> int: ...
def subset(a: bitarray, b: bitarray) -> bool: ...
def serialize(a: bitarray) -> bytes: ...
def deserialize(b: bytes) -> bitarray: ...

Utility Functions

Advanced Features

Specialized functionality for encoding/decoding variable-length prefix codes, Huffman coding, compression algorithms, and advanced bit manipulation techniques.

def encode(self, code: dict, iterable) -> None: ...
def decode(self, code: Union[dict, decodetree]) -> Iterator: ...

class decodetree:
    def __init__(self, code: dict) -> None: ...
    def complete(self) -> bool: ...
    def nodes(self) -> int: ...

def huffman_code(freq_map: dict, endian: Optional[str] = None) -> dict: ...
def vl_encode(a: bitarray) -> bytes: ...
def vl_decode(stream: Iterable[int], endian: Optional[str] = None) -> bitarray: ...

Advanced Features

Types

from typing import Union, Optional, Iterable, Iterator, Any, NamedTuple
from collections.abc import Sequence
from unittest.runner import TextTestResult

# Type aliases
BytesLike = Union[bytes, bytearray]
CodeDict = dict[Any, bitarray]

class BufferInfo(NamedTuple):
    address: int
    nbytes: int  
    endian: str
    padbits: int
    alloc: int
    readonly: bool
    imported: bool
    exports: int

class frozenbitarray(bitarray):
    def __hash__(self) -> int: ...