refactor(tap): extract BaseTap abstract class for tap implementations

Author: medeirosdev

src/trueentropy/tap.py

@@ -23,6 +23,7 @@
 from __future__ import annotations
 
 import struct
+from abc import ABC, abstractmethod
 from collections.abc import MutableSequence, Sequence
 from typing import Any, TypeVar
 
@@ -32,163 +33,36 @@
 T = TypeVar("T")
 
 
-class EntropyTap:
+class BaseTap(ABC):
     """
-    Extracts and formats random values from an entropy pool.
-
-    The tap is responsible for converting raw entropy bytes into
-    various formats like floats, integers, and booleans. It ensures
-    that all generated values are uniformly distributed.
+    Abstract base class for entropy taps.
 
-    Example:
-        >>> pool = EntropyPool()
-        >>> tap = EntropyTap(pool)
-        >>> value = tap.random()
-        >>> print(f"Random: {value}")
+    Provides common utility methods and higher-level distributions
+    dependent on the core random primitives.
     """
 
-    # -------------------------------------------------------------------------
-    # Initialization
-    # -------------------------------------------------------------------------
-
-    def __init__(self, pool: EntropyPool) -> None:
-        """
-        Initialize the tap with an entropy pool.
-
-        Args:
-            pool: The EntropyPool instance to extract entropy from
-        """
-        self._pool = pool
-
-    # -------------------------------------------------------------------------
-    # Random Value Generation
-    # -------------------------------------------------------------------------
-
+    @abstractmethod
     def random(self) -> float:
-        """
-        Generate a random float in the range [0.0, 1.0).
-
-        Uses 64 bits of entropy to generate a uniformly distributed
-        floating-point number. The result is always less than 1.0.
-
-        Returns:
-            A float value where 0.0 <= value < 1.0
-
-        How it works:
-            1. Extract 8 bytes (64 bits) from the pool
-            2. Interpret as unsigned 64-bit integer
-            3. Divide by 2^64 to get value in [0, 1)
-        """
-        # Extract 8 bytes of entropy
-        raw_bytes = self._pool.extract(8)
-
-        # Unpack as unsigned 64-bit integer (big-endian)
-        # We use big-endian for consistency across platforms
-        value = struct.unpack("!Q", raw_bytes)[0]
-
-        # Convert to float in range [0.0, 1.0)
-        # 2^64 = 18446744073709551616
-        return value / 18446744073709551616.0
+        """Generate a random float in the range [0.0, 1.0)."""
+        pass
 
+    @abstractmethod
     def randint(self, a: int, b: int) -> int:
-        """
-        Generate a random integer N such that a <= N <= b.
-
-        Uses rejection sampling to ensure uniform distribution.
-        This avoids modulo bias that would occur with simple modulo.
-
-        Args:
-            a: Lower bound (inclusive)
-            b: Upper bound (inclusive)
-
-        Returns:
-            Random integer in [a, b]
-
-        Raises:
-            ValueError: If a > b
-
-        How it works:
-            1. Calculate the range size (b - a + 1)
-            2. Find the smallest number of bits needed to represent range
-            3. Generate random bits and check if value < range
-            4. If not, reject and try again (rejection sampling)
-            5. This ensures perfectly uniform distribution
-        """
-        if a > b:
-            raise ValueError(f"randint: a ({a}) must be <= b ({b})")
+        """Generate a random integer N such that a <= N <= b."""
+        pass
 
-        if a == b:
-            return a  # Only one possible value
-
-        # Calculate range size
-        range_size = b - a + 1
-
-        # Find number of bits needed to represent range_size
-        # We need ceil(log2(range_size)) bits
-        bits_needed = (range_size - 1).bit_length()
-        bytes_needed = (bits_needed + 7) // 8  # Round up to bytes
-
-        # Mask to extract only the bits we need
-        # e.g., for range_size=100, bits_needed=7, mask=0x7F (127)
-        mask = (1 << bits_needed) - 1
-
-        # Rejection sampling loop
-        # We keep generating random values until we get one in range
-        # Expected number of iterations is < 2 on average
-        while True:
-            # Extract random bytes
-            raw_bytes = self._pool.extract(bytes_needed)
-
-            # Pad to 8 bytes for unpacking (big-endian)
-            padded = raw_bytes.rjust(8, b"\x00")
-
-            # Unpack as unsigned 64-bit integer
-            value = struct.unpack("!Q", padded)[0]
-
-            # Apply mask to get only needed bits
-            value = value & mask
-
-            # Check if value is in valid range
-            if value < range_size:
-                return a + value
+    @abstractmethod
+    def randbytes(self, n: int) -> bytes:
+        """Generate n random bytes."""
+        pass
 
     def randbool(self) -> bool:
         """
         Generate a random boolean (True or False).
 
-        Each value has exactly 50% probability - a fair coin flip.
-
-        Returns:
-            True or False with equal probability
-
-        How it works:
-            1. Extract 1 byte from the pool
-            2. Check the least significant bit
-            3. Return True if bit is 1, False if 0
+        Default implementation uses random(). Can be overridden for efficiency.
         """
-        # Extract 1 byte of entropy
-        raw_byte = self._pool.extract(1)
-
-        # Check least significant bit
-        return (raw_byte[0] & 1) == 1
-
-    def randbytes(self, n: int) -> bytes:
-        """
-        Generate n random bytes.
-
-        Args:
-            n: Number of bytes to generate (must be positive)
-
-        Returns:
-            A bytes object of length n
-
-        Raises:
-            ValueError: If n is not positive
-        """
-        if n <= 0:
-            raise ValueError(f"randbytes: n ({n}) must be positive")
-
-        return self._pool.extract(n)
+        return self.random() < 0.5
 
     def choice(self, seq: Sequence[T]) -> T:
         """
@@ -586,6 +460,165 @@ def random_password(
         # Generate password by choosing random characters
         return "".join(self.choice(chars) for _ in range(length))
 
+
+class EntropyTap(BaseTap):
+    """
+    Extracts and formats random values from an entropy pool.
+
+    The tap is responsible for converting raw entropy bytes into
+    various formats like floats, integers, and booleans. It ensures
+    that all generated values are uniformly distributed.
+
+    Example:
+        >>> pool = EntropyPool()
+        >>> tap = EntropyTap(pool)
+        >>> value = tap.random()
+        >>> print(f"Random: {value}")
+    """
+
+    # -------------------------------------------------------------------------
+    # Initialization
+    # -------------------------------------------------------------------------
+
+    def __init__(self, pool: EntropyPool) -> None:
+        """
+        Initialize the tap with an entropy pool.
+
+        Args:
+            pool: The EntropyPool instance to extract entropy from
+        """
+        self._pool = pool
+
+    # -------------------------------------------------------------------------
+    # Random Value Generation
+    # -------------------------------------------------------------------------
+
+    def random(self) -> float:
+        """
+        Generate a random float in the range [0.0, 1.0).
+
+        Uses 64 bits of entropy to generate a uniformly distributed
+        floating-point number. The result is always less than 1.0.
+
+        Returns:
+            A float value where 0.0 <= value < 1.0
+
+        How it works:
+            1. Extract 8 bytes (64 bits) from the pool
+            2. Interpret as unsigned 64-bit integer
+            3. Divide by 2^64 to get value in [0, 1)
+        """
+        # Extract 8 bytes of entropy
+        raw_bytes = self._pool.extract(8)
+
+        # Unpack as unsigned 64-bit integer (big-endian)
+        # We use big-endian for consistency across platforms
+        value = struct.unpack("!Q", raw_bytes)[0]
+
+        # Convert to float in range [0.0, 1.0)
+        # 2^64 = 18446744073709551616
+        return value / 18446744073709551616.0
+
+    def randint(self, a: int, b: int) -> int:
+        """
+        Generate a random integer N such that a <= N <= b.
+
+        Uses rejection sampling to ensure uniform distribution.
+        This avoids modulo bias that would occur with simple modulo.
+
+        Args:
+            a: Lower bound (inclusive)
+            b: Upper bound (inclusive)
+
+        Returns:
+            Random integer in [a, b]
+
+        Raises:
+            ValueError: If a > b
+
+        How it works:
+            1. Calculate the range size (b - a + 1)
+            2. Find the smallest number of bits needed to represent range
+            3. Generate random bits and check if value < range
+            4. If not, reject and try again (rejection sampling)
+            5. This ensures perfectly uniform distribution
+        """
+        if a > b:
+            raise ValueError(f"randint: a ({a}) must be <= b ({b})")
+
+        if a == b:
+            return a  # Only one possible value
+
+        # Calculate range size
+        range_size = b - a + 1
+
+        # Find number of bits needed to represent range_size
+        # We need ceil(log2(range_size)) bits
+        bits_needed = (range_size - 1).bit_length()
+        bytes_needed = (bits_needed + 7) // 8  # Round up to bytes
+
+        # Mask to extract only the bits we need
+        # e.g., for range_size=100, bits_needed=7, mask=0x7F (127)
+        mask = (1 << bits_needed) - 1
+
+        # Rejection sampling loop
+        # We keep generating random values until we get one in range
+        # Expected number of iterations is < 2 on average
+        while True:
+            # Extract random bytes
+            raw_bytes = self._pool.extract(bytes_needed)
+
+            # Pad to 8 bytes for unpacking (big-endian)
+            padded = raw_bytes.rjust(8, b"\x00")
+
+            # Unpack as unsigned 64-bit integer
+            value = struct.unpack("!Q", padded)[0]
+
+            # Apply mask to get only needed bits
+            value = value & mask
+
+            # Check if value is in valid range
+            if value < range_size:
+                return a + value
+
+    def randbool(self) -> bool:
+        """
+        Generate a random boolean (True or False).
+
+        Each value has exactly 50% probability - a fair coin flip.
+
+        Returns:
+            True or False with equal probability
+
+        How it works:
+            1. Extract 1 byte from the pool
+            2. Check the least significant bit
+            3. Return True if bit is 1, False if 0
+        """
+        # Extract 1 byte of entropy
+        raw_byte = self._pool.extract(1)
+
+        # Check least significant bit
+        return (raw_byte[0] & 1) == 1
+
+    def randbytes(self, n: int) -> bytes:
+        """
+        Generate n random bytes.
+
+        Args:
+            n: Number of bytes to generate (must be positive)
+
+        Returns:
+            A bytes object of length n
+
+        Raises:
+            ValueError: If n is not positive
+        """
+        if n <= 0:
+            raise ValueError(f"randbytes: n ({n}) must be positive")
+
+        return self._pool.extract(n)
+
     # -------------------------------------------------------------------------
     # String Representation
     # -------------------------------------------------------------------------