tessl/pypi-bitarray

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Creation and Conversion

Name: tessl/pypi-bitarray
Author: tessl

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

Capabilities

Object Creation Functions

Utility functions for creating bitarrays with specific patterns and properties.

def zeros(length: int, endian: Optional[str] = None) -> bitarray:
    """
    Create bitarray of all zeros.
    
    Args:
        length: Number of bits
        endian: Bit-endianness ('big' or 'little'), uses default if None
        
    Returns:
        bitarray with all bits set to 0
    """

def ones(length: int, endian: Optional[str] = None) -> bitarray:
    """
    Create bitarray of all ones.
    
    Args:
        length: Number of bits  
        endian: Bit-endianness ('big' or 'little'), uses default if None
        
    Returns:
        bitarray with all bits set to 1
    """

Usage Examples:

from bitarray.util import zeros, ones

# Create patterns
a = zeros(8)           # bitarray('00000000')
b = ones(5)            # bitarray('11111')
c = zeros(12, 'little') # 12 zeros, little-endian

Random Generation

Functions for generating random bitarrays with various probability distributions.

def urandom(length: int, endian: Optional[str] = None) -> bitarray:
    """
    Generate cryptographically random bitarray using os.urandom().
    
    Args:
        length: Number of bits
        endian: Bit-endianness
        
    Returns:
        Random bitarray
    """

def random_k(n: int, k: int, endian: Optional[str] = None) -> bitarray:
    """
    Generate pseudo-random bitarray with exactly k bits set.
    Requires Python 3.9+.
    
    Args:
        n: Total number of bits
        k: Number of bits to set to 1
        endian: Bit-endianness
        
    Returns:
        Random bitarray with exactly k ones
    """

def random_p(n: int, p: float = 0.5, endian: Optional[str] = None) -> bitarray:
    """
    Generate pseudo-random bitarray where each bit has probability p of being 1.
    Requires Python 3.12+.
    
    Args:
        n: Number of bits
        p: Probability of each bit being 1 (0.0 to 1.0)
        endian: Bit-endianness
        
    Returns:
        Random bitarray
    """

Usage Examples:

from bitarray.util import urandom, random_k, random_p
import random

# Set seed for reproducible results
random.seed(42)

# Random generation  
a = urandom(16)              # Cryptographically random
b = random_k(20, 5)          # Exactly 5 bits set in 20 bits
c = random_p(100, 0.3)       # Each bit has 30% chance of being 1

Byte Conversion

Methods for converting between bitarrays and byte representations.

def frombytes(self, a: Union[bytes, bytearray]) -> None:
    """
    Append bits from bytes/bytearray to bitarray.
    
    Args:
        a: Bytes or bytearray to convert
    """

def tobytes(self) -> bytes:
    """
    Convert bitarray to bytes object.
    Padding bits are set to 0.
    
    Returns:
        bytes representation of bitarray
    """

def fromfile(self, f: BinaryIO, n: int = -1) -> None:
    """
    Read bits from file and append to bitarray.
    
    Args:
        f: Binary file object
        n: Maximum number of bytes to read (-1 for all)
    """

def tofile(self, f: BinaryIO) -> None:
    """
    Write bitarray to file as bytes.
    
    Args:
        f: Binary file object to write to
    """

def pack(self, a: Union[bytes, bytearray]) -> None:
    """
    Pack bytes into bitarray, extending with bits from bytes."""

def unpack(self, zero: bytes = b'\\x00', one: bytes = b'\\x01') -> bytes:
    """
    Unpack bitarray to bytes, using specified bytes for 0 and 1 bits."""

Usage Examples:

from bitarray import bitarray

# Byte operations
a = bitarray()
a.frombytes(b'\\x5A\\x3C')    # Append bytes as bits
byte_data = a.tobytes()      # Convert to bytes

# File operations  
with open('data.bin', 'rb') as f:
    a.fromfile(f, 10)        # Read 10 bytes from file

with open('output.bin', 'wb') as f:
    a.tofile(f)              # Write to file

# Packing/unpacking
a.pack(b'\\xFF\\x00')        # Pack bytes as individual bits
unpacked = a.unpack(b'0', b'1')  # Custom 0/1 representations

String Representations

Methods for converting between bitarrays and string formats.

def to01(self, group: int = 0, sep: str = '') -> str:
    """
    Convert bitarray to '01' string representation.
    
    Args:
        group: Group bits (0 for no grouping)
        sep: Separator between groups
        
    Returns:
        String of '0' and '1' characters
    """

def tolist(self) -> list[int]:
    """
    Convert bitarray to list of integers (0s and 1s).
    
    Returns:
        List of 0 and 1 integers
    """

Usage Examples:

a = bitarray('10110011')

# String representations
s1 = a.to01()              # '10110011'
s2 = a.to01(4, ' ')        # '1011 0011'
s3 = a.to01(2, '-')       # '10-11-00-11'

# List conversion
lst = a.tolist()           # [1, 0, 1, 1, 0, 0, 1, 1]

Hexadecimal Conversion

Functions for converting between bitarrays and hexadecimal representations.

def ba2hex(a: bitarray, group: int = 0, sep: str = '') -> str:
    """
    Convert bitarray to hexadecimal string.
    
    Args:
        a: Input bitarray
        group: Group hex digits (0 for no grouping)
        sep: Separator between groups
        
    Returns:
        Hexadecimal string representation
    """

def hex2ba(s: str, endian: Optional[str] = None) -> bitarray:
    """
    Convert hexadecimal string to bitarray.
    
    Args:
        s: Hexadecimal string (with or without '0x' prefix)
        endian: Bit-endianness
        
    Returns:
        bitarray from hex string
    """

Usage Examples:

from bitarray import bitarray
from bitarray.util import ba2hex, hex2ba

# Hex conversion
a = bitarray('1010110011110000')
hex_str = ba2hex(a)           # 'AB3F0'
hex_grouped = ba2hex(a, 2, ' ')  # 'AB 3F 0'

# From hex
b = hex2ba('5A3C')            # Convert hex to bitarray
c = hex2ba('0xFF00')          # With '0x' prefix
d = hex2ba('ABCD', 'little')  # Little-endian

Base Conversion

Functions for converting bitarrays to and from various number bases.

def ba2base(n: int, a: bitarray, group: int = 0, sep: str = '') -> str:
    """
    Convert bitarray to base-n string representation.
    
    Args:
        n: Target base (2-36)
        a: Input bitarray
        group: Group digits (0 for no grouping)
        sep: Separator between groups
        
    Returns:
        Base-n string representation
    """

def base2ba(n: int, s: str, endian: Optional[str] = None) -> bitarray:
    """
    Convert base-n string to bitarray.
    
    Args:
        n: Source base (2-36)
        s: Base-n string
        endian: Bit-endianness
        
    Returns:
        bitarray from base-n string
    """

Usage Examples:

from bitarray import bitarray
from bitarray.util import ba2base, base2ba

a = bitarray('11010110')

# Base conversions
binary = ba2base(2, a)        # '11010110' (binary)
octal = ba2base(8, a)         # '326' (octal)
decimal = ba2base(10, a)      # '214' (decimal)
hex_str = ba2base(16, a)      # 'D6' (hexadecimal)

# From base-n strings
b = base2ba(8, '755')         # From octal
c = base2ba(16, 'CAFE')       # From hex
d = base2ba(3, '12021')       # From base-3

Integer Conversion

Functions for converting between bitarrays and integer values.

def ba2int(a: bitarray, signed: bool = False) -> int:
    """
    Convert bitarray to integer.
    
    Args:
        a: Input bitarray
        signed: Interpret as signed integer (two's complement)
        
    Returns:
        Integer value
    """

def int2ba(i: int, 
           length: Optional[int] = None,
           endian: Optional[str] = None,
           signed: bool = False) -> bitarray:
    """
    Convert integer to bitarray.
    
    Args:
        i: Integer value
        length: Bit length (auto-determined if None)
        endian: Bit-endianness
        signed: Use two's complement for negative numbers
        
    Returns:
        bitarray representation of integer
    """

Usage Examples:

from bitarray import bitarray
from bitarray.util import ba2int, int2ba

# Integer to bitarray
a = int2ba(42)              # Auto-length
b = int2ba(42, 8)           # Fixed 8-bit length  
c = int2ba(-10, 8, signed=True)  # Signed representation

# Bitarray to integer
val1 = ba2int(bitarray('1010'))     # 10 (unsigned)
val2 = ba2int(bitarray('1010'), signed=True)  # -6 (signed)

# Large integers
big_int = 2**100 + 42
big_ba = int2ba(big_int)
recovered = ba2int(big_ba)  # == big_int

Special Creation Functions

Additional utility functions for creating specialized bitarrays.

def gen_primes(n: int, endian: Optional[str] = None, odd: bool = False) -> bitarray:
    """
    Generate bitarray representing prime numbers up to n using Sieve of Eratosthenes.
    
    Args:
        n: Upper limit
        endian: Bit-endianness  
        odd: Only consider odd numbers if True
        
    Returns:
        bitarray where bit i is 1 if i is prime
    """

def bits2bytes(n: int) -> int:
    """
    Calculate number of bytes needed to store n bits.
    
    Args:
        n: Number of bits
        
    Returns:
        Number of bytes required
    """

Usage Examples:

from bitarray import bits2bytes
from bitarray.util import gen_primes

# Prime generation
primes = gen_primes(100)     # Primes up to 100
odd_primes = gen_primes(100, odd=True)  # Only odd primes

# Check if number is prime
is_17_prime = primes[17]     # True
is_18_prime = primes[18]     # False

# Byte calculation
bytes_needed = bits2bytes(25)  # 4 bytes needed for 25 bits

Package Utility Functions

Additional package-level utility functions for configuration and testing.

def get_default_endian() -> str:
    """
    Get the default bit-endianness for new bitarray objects.
    
    Returns:
        Default endianness ('big' or 'little')
    """

def test(verbosity: int = 1) -> TextTestResult:
    """
    Run bitarray test suite and return results.
    
    Args:
        verbosity: Test output verbosity level (0=quiet, 1=normal, 2=verbose)
        
    Returns:
        unittest.runner.TextTestResult object
    """

Usage Examples:

from bitarray import get_default_endian, test

# Check default configuration
default_endian = get_default_endian()  # 'big' or 'little'

# Run comprehensive test suite
result = test(verbosity=1)
print(f"Tests successful: {result.wasSuccessful()}")
print(f"Tests run: {result.testsRun}")

# Verify all tests passed
assert result.wasSuccessful()

Immutable Bitarrays

class frozenbitarray(bitarray):
    """Immutable bitarray that can be used as dictionary key"""
    
    def __hash__(self) -> int:
        """Return hash value for use as dictionary key"""
    
    def __repr__(self) -> str:
        """Return string representation with 'frozen' prefix"""
    
    # The following methods are disabled and raise TypeError:
    # append, bytereverse, clear, extend, encode, fill
    # frombytes, fromfile, insert, invert, pack, pop
    # remove, reverse, setall, sort, __setitem__, __delitem__
    # __iadd__, __iand__, __imul__, __ior__, __ixor__
    # __ilshift__, __irshift__

Usage Examples:

from bitarray import bitarray, frozenbitarray

# Create immutable version
a = bitarray('10110')
frozen = frozenbitarray(a)

# Use as dictionary key
bit_dict = {frozen: 'some value'}
lookup = bit_dict[frozenbitarray('10110')]  # 'some value'

# Frozen bitarrays support all read-only operations
print(len(frozen))           # 5
print(frozen.count())        # 3
print(frozen.find('11'))     # 2

# Mutating operations raise TypeError
# frozen.append(1)           # TypeError: frozenbitarray is immutable

Install with Tessl CLI