flexfloat 0.1.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

flexfloat/__init__.py

@@ -1,32 +1,36 @@
 """FlexFloat - A library for arbitrary precision floating point arithmetic.
 
-This package provides the FlexFloat class for handling floating-point numbers
-with growable exponents and fixed-size fractions.
+This package provides the FlexFloat class for handling floating-point numbers with
+growable exponents and fixed-size fractions. It also provides several BitArray
+implementations for efficient bit manipulation.
+
+Example:
+    from flexfloat import FlexFloat
+    x = FlexFloat(1.5, exponent_length=8, fraction_length=23)
+    print(x)
+    # Output: FlexFloat(sign=False, exponent=..., fraction=...)
+
+Modules:
+    core: Main FlexFloat class implementation
+    bitarray: BitArray implementations (bool, int64, bigint)
+    types: Type definitions
 """
 
 from .bitarray import (
+    BigIntBitArray,
     BitArray,
-    BitArrayType,
-    Int64BitArray,
-    ListBitArray,
-    create_bitarray,
-    get_available_implementations,
-    parse_bitarray,
-    set_default_implementation,
+    ListBoolBitArray,
+    ListInt64BitArray,
 )
 from .core import FlexFloat
 
-__version__ = "0.1.3"
+__version__ = "0.3.0"
 __author__ = "Ferran Sanchez Llado"
 
 __all__ = [
     "FlexFloat",
-    "BitArrayType",
     "BitArray",
-    "ListBitArray",
-    "Int64BitArray",
-    "create_bitarray",
-    "set_default_implementation",
-    "get_available_implementations",
-    "parse_bitarray",
+    "ListBoolBitArray",
+    "ListInt64BitArray",
+    "BigIntBitArray",
 ]

flexfloat/bitarray/__init__.py

@@ -1,90 +1,31 @@
-"""BitArray implementation for the flexfloat package."""
+"""BitArray implementation for the flexfloat package.
+
+This module provides a factory and utilities for working with different BitArray
+implementations, including:
+    - ListBoolBitArray: List of booleans (default, flexible, easy to use)
+    - ListInt64BitArray: List of int64 chunks (memory efficient for large arrays)
+    - BigIntBitArray: Single Python int (arbitrary size, efficient for very large
+        arrays)
+
+Example:
+    from flexfloat.bitarray import create_bitarray
+    ba = create_bitarray('int64', [True, False, True])
+    print(type(ba).__name__)
+    # Output: ListInt64BitArray
+"""
 
 from __future__ import annotations
 
-from typing import Dict, Type
-
 from .bitarray import BitArray
-from .bitarray_int64 import Int64BitArray
-from .bitarray_list import ListBitArray
+from .bitarray_bigint import BigIntBitArray
+from .bitarray_bool import ListBoolBitArray
+from .bitarray_int64 import ListInt64BitArray
 from .bitarray_mixins import BitArrayCommonMixin
 
-# Type alias for the default BitArray implementation
-BitArrayType: Type[BitArray] = ListBitArray
-
-# Available implementations
-IMPLEMENTATIONS: Dict[str, Type[BitArray]] = {
-    "list": ListBitArray,
-    "int64": Int64BitArray,
-}
-
-
-def create_bitarray(
-    implementation: str = "list", bits: list[bool] | None = None
-) -> BitArray:
-    """Factory function to create a BitArray with the specified implementation.
-
-    Args:
-        implementation: The implementation to use ("list" or "int64")
-        bits: Initial list of boolean values
-
-    Returns:
-        BitArray: A BitArray instance using the specified implementation
-
-    Raises:
-        ValueError: If the implementation is not supported
-    """
-    if implementation not in IMPLEMENTATIONS:
-        raise ValueError(
-            f"Unknown implementation '{implementation}'. "
-            f"Available: {list(IMPLEMENTATIONS.keys())}"
-        )
-
-    return IMPLEMENTATIONS[implementation](bits)
-
-
-def set_default_implementation(implementation: str) -> None:
-    """Set the default BitArray implementation.
-
-    Args:
-        implementation: The implementation to use as default ("list" or "int64")
-
-    Raises:
-        ValueError: If the implementation is not supported
-    """
-    global BitArrayType
-
-    if implementation not in IMPLEMENTATIONS:
-        raise ValueError(
-            f"Unknown implementation '{implementation}'. "
-            f"Available: {list(IMPLEMENTATIONS.keys())}"
-        )
-
-    BitArrayType = IMPLEMENTATIONS[implementation]
-
-
-def get_available_implementations() -> list[str]:
-    """Get the list of available BitArray implementations.
-
-    Returns:
-        list[str]: List of available implementation names
-    """
-    return list(IMPLEMENTATIONS.keys())
-
-
-# Maintain backward compatibility by exposing the methods as module-level functions
-def parse_bitarray(bitstring: str) -> BitArray:
-    """Parse a string of bits (with optional spaces) into a BitArray instance."""
-    return BitArrayType.parse_bitarray(bitstring)
-
-
 __all__ = [
     "BitArray",
-    "ListBitArray",
-    "Int64BitArray",
+    "ListBoolBitArray",
+    "ListInt64BitArray",
+    "BigIntBitArray",
     "BitArrayCommonMixin",
-    "create_bitarray",
-    "set_default_implementation",
-    "get_available_implementations",
-    "parse_bitarray",
 ]

flexfloat/bitarray/bitarray.py

@@ -1,8 +1,19 @@
-"""BitArray protocol definition for the flexfloat package."""
+"""BitArray protocol definition for the flexfloat package.
+
+This module defines the BitArray protocol, which all BitArray implementations must
+follow. The protocol ensures a consistent interface for bit manipulation.
+
+Example:
+    from flexfloat.bitarray import BitArray
+    class MyBitArray(BitArray):
+        ...
+    my_bitarray = MyBitArray()
+    isinstance(my_bitarray, BitArray)  # True
+"""
 
 from __future__ import annotations
 
-from typing import Iterator, Protocol, overload, runtime_checkable
+from typing import Iterable, Iterator, Protocol, overload, runtime_checkable
 
 
 @runtime_checkable
@@ -11,81 +22,103 @@ class BitArray(Protocol):
 
     This protocol defines all the methods and properties that a BitArray
     implementation must provide.
+
+    For consistency, all BitArray implementations should order bits as LSB-first,
+    meaning the least significant bit is at index 0 and the most significant bit
+    is at the highest index.
     """
 
-    def __init__(self, bits: list[bool] | None = None) -> None:
-        """Initialize a BitArray.
+    @classmethod
+    def from_bits(cls, bits: list[bool] | None = None) -> "BitArray":
+        """Creates a BitArray from a list of boolean values.
 
         Args:
-            bits: Initial list of boolean values. Defaults to empty list.
+            bits (list[bool] | None, optional): List of boolean values. Defaults to
+                None, which creates an empty BitArray.
+
+        Returns:
+            BitArray: A BitArray created from the bits.
         """
         ...
 
     @classmethod
-    def from_float(cls, value: float) -> BitArray:
-        """Convert a floating-point number to a bit array.
+    def from_float(cls, value: float) -> "BitArray":
+        """Converts a floating-point number to a bit array.
 
         Args:
             value (float): The floating-point number to convert.
+
         Returns:
-            BitArrayProtocol: A BitArray representing the bits of the floating-point
-                number.
+            BitArray: A BitArray representing the bits of the floating-point number.
         """
         ...
 
     @classmethod
-    def from_signed_int(cls, value: int, length: int) -> BitArray:
-        """Convert a signed integer to a bit array using off-set binary representation.
+    def from_signed_int(cls, value: int, length: int) -> "BitArray":
+        """Converts a signed integer to a bit array using off-set binary representation.
 
         Args:
             value (int): The signed integer to convert.
             length (int): The length of the resulting bit array.
+
         Returns:
-            BitArrayProtocol: A BitArray representing the bits of the signed integer.
+            BitArray: A BitArray representing the bits of the signed integer.
+
         Raises:
             AssertionError: If the value is out of range for the specified length.
         """
         ...
 
     @classmethod
-    def zeros(cls, length: int) -> BitArray:
-        """Create a BitArray filled with zeros.
+    def zeros(cls, length: int) -> "BitArray":
+        """Creates a BitArray filled with zeros.
 
         Args:
-            length: The length of the bit array.
+            length (int): The length of the bit array.
+
         Returns:
-            BitArrayProtocol: A BitArray filled with False values.
+            BitArray: A BitArray filled with False values.
         """
         ...
 
     @classmethod
-    def ones(cls, length: int) -> BitArray:
-        """Create a BitArray filled with ones.
+    def ones(cls, length: int) -> "BitArray":
+        """Creates a BitArray filled with ones.
 
         Args:
-            length: The length of the bit array.
+            length (int): The length of the bit array.
+
         Returns:
-            BitArrayProtocol: A BitArray filled with True values.
+            BitArray: A BitArray filled with True values.
         """
         ...
 
-    @staticmethod
-    def parse_bitarray(bitstring: str) -> BitArray:
-        """Parse a string of bits (with optional spaces) into a BitArray instance."""
+    @classmethod
+    def parse_bitarray(cls, bitstring: Iterable[str]) -> "BitArray":
+        """Parses a string of bits (with optional spaces) into a BitArray instance.
+        Non-valid characters are ignored.
+
+        Args:
+            bitstring (Iterable[str]): A string of bits, e.g., "1010 1100".
+
+        Returns:
+            BitArray: A BitArray instance created from the bit string.
+        """
         ...
 
     def to_float(self) -> float:
-        """Convert a 64-bit array to a floating-point number.
+        """Converts a 64-bit array to a floating-point number.
 
         Returns:
             float: The floating-point number represented by the bit array.
+
         Raises:
             AssertionError: If the bit array is not 64 bits long.
         """
         ...
 
     def to_int(self) -> int:
-        """Convert the bit array to an unsigned integer.
+        """Converts the bit array to an unsigned integer.
 
         Returns:
             int: The integer represented by the bit array.
@@ -93,18 +126,19 @@ class BitArray(Protocol):
         ...
 
     def to_signed_int(self) -> int:
-        """Convert a bit array into a signed integer using off-set binary
+        """Converts a bit array into a signed integer using off-set binary
         representation.
 
         Returns:
             int: The signed integer represented by the bit array.
+
         Raises:
             AssertionError: If the bit array is empty.
         """
         ...
 
-    def shift(self, shift_amount: int, fill: bool = False) -> BitArray:
-        """Shift the bit array left or right by a specified number of bits.
+    def shift(self, shift_amount: int, fill: bool = False) -> "BitArray":
+        """Shifts the bit array left or right by a specified number of bits.
 
         This function shifts the bits in the array, filling in new bits with the
         specified fill value.
@@ -114,85 +148,151 @@ class BitArray(Protocol):
         Args:
             shift_amount (int): The number of bits to shift. Positive for left shift,
                 negative for right shift.
-            fill (bool): The value to fill in the new bits created by the shift.
-                Defaults to False.
+            fill (bool, optional): The value to fill in the new bits created by the
+                shift. Defaults to False.
+
         Returns:
-            BitArrayProtocol: A new BitArray with the bits shifted and filled.
+            BitArray: A new BitArray with the bits shifted and filled.
         """
         ...
 
-    def copy(self) -> BitArray:
-        """Create a copy of the bit array.
+    def copy(self) -> "BitArray":
+        """Creates a copy of the bit array.
 
         Returns:
-            BitArrayProtocol: A new BitArray with the same bits.
+            BitArray: A new BitArray with the same bits.
         """
         ...
 
     def __len__(self) -> int:
-        """Return the length of the bit array."""
+        """Returns the length of the bit array.
+
+        Returns:
+            int: The number of bits in the array.
+        """
         ...
 
     @overload
     def __getitem__(self, index: int) -> bool: ...
     @overload
-    def __getitem__(self, index: slice) -> BitArray: ...
+    def __getitem__(self, index: slice) -> "BitArray": ...
 
     def __getitem__(self, index: int | slice) -> bool | BitArray:
-        """Get an item or slice from the bit array."""
+        """Get a bit or a slice of bits as a new BitArray."""
         ...
 
     @overload
     def __setitem__(self, index: int, value: bool) -> None: ...
     @overload
-    def __setitem__(self, index: slice, value: BitArray | list[bool]) -> None: ...
+    def __setitem__(self, index: slice, value: "BitArray" | list[bool]) -> None: ...
 
     def __setitem__(
-        self, index: int | slice, value: bool | list[bool] | BitArray
+        self, index: int | slice, value: bool | list[bool] | "BitArray"
     ) -> None:
-        """Set an item or slice in the bit array."""
+        """Sets an item or slice in the bit array.
+
+        Args:
+            index (int or slice): The index or slice to set.
+            value (bool or list[bool] or BitArray): The value(s) to assign.
+        """
         ...
 
     def __iter__(self) -> Iterator[bool]:
-        """Iterate over the bits in the array."""
+        """Iterates over the bits in the array.
+
+        Yields:
+            bool: The next bit in the array.
+        """
         ...
 
-    def __add__(self, other: BitArray | list[bool]) -> BitArray:
-        """Concatenate two bit arrays."""
+    def __add__(self, other: "BitArray" | list[bool]) -> "BitArray":
+        """Concatenates two bit arrays.
+
+        Args:
+            other (BitArray or list[bool]): The other bit array or list to concatenate.
+
+        Returns:
+            BitArray: The concatenated bit array.
+        """
         ...
 
-    def __radd__(self, other: list[bool]) -> BitArray:
-        """Reverse concatenation with a list."""
+    def __radd__(self, other: list[bool]) -> "BitArray":
+        """Reverse concatenation with a list.
+
+        Args:
+            other (list[bool]): The list to concatenate before this bit array.
+
+        Returns:
+            BitArray: The concatenated bit array.
+        """
         ...
 
     def __eq__(self, other: object) -> bool:
-        """Check equality with another BitArray or list."""
+        """Checks equality with another BitArray or list.
+
+        Args:
+            other (object): The object to compare with.
+
+        Returns:
+            bool: True if equal, False otherwise.
+        """
         ...
 
     def __bool__(self) -> bool:
-        """Return True if any bit is set."""
+        """Returns True if any bit is set.
+
+        Returns:
+            bool: True if any bit is set, False otherwise.
+        """
         ...
 
     def __repr__(self) -> str:
-        """Return a string representation of the BitArray."""
+        """Returns a string representation of the BitArray.
+
+        Returns:
+            str: String representation of the BitArray.
+        """
         ...
 
     def __str__(self) -> str:
-        """Return a string representation of the bits."""
+        """Returns a string representation of the bits.
+
+        Returns:
+            str: String representation of the bits.
+        """
         ...
 
     def any(self) -> bool:
-        """Return True if any bit is set to True."""
+        """Returns True if any bit is set to True.
+
+        Returns:
+            bool: True if any bit is set to True, False otherwise.
+        """
         ...
 
     def all(self) -> bool:
-        """Return True if all bits are set to True."""
+        """Returns True if all bits are set to True.
+
+        Returns:
+            bool: True if all bits are set to True, False otherwise.
+        """
         ...
 
     def count(self, value: bool = True) -> int:
-        """Count the number of bits set to the specified value."""
+        """Counts the number of bits set to the specified value.
+
+        Args:
+            value (bool, optional): The value to count. Defaults to True.
+
+        Returns:
+            int: The number of bits set to the specified value.
+        """
         ...
 
-    def reverse(self) -> BitArray:
-        """Return a new BitArray with the bits in reverse order."""
+    def reverse(self) -> "BitArray":
+        """Returns a new BitArray with the bits in reverse order.
+
+        Returns:
+            BitArray: A new BitArray with the bits in reverse order.
+        """
         ...