types: add Boolean type and tests (leanEthereum#40)

Author: tcoratger

src/lean_spec/types/boolean.py

@@ -0,0 +1,166 @@
+"""Boolean Type Specification."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic.annotated_handlers import GetCoreSchemaHandler
+from pydantic_core import CoreSchema, core_schema
+from typing_extensions import Self
+
+
+class Boolean(int):
+    """
+    A strict SSZ Boolean type that inherits from `int` for `True`/`False` representation.
+
+    This class provides a distinct type for SSZ booleans (`True` as `1`, `False` as `0`).
+
+    It integrates with Pydantic for strict validation.
+
+    It explicitly disallows standard integer arithmetic to prevent ambiguous operations.
+    """
+
+    __slots__ = ()
+
+    def __new__(cls, value: bool | int) -> Self:
+        """
+        Create and validate a new Boolean instance.
+
+        Accepts only `True`, `False`, `1`, or `0`.
+
+        Raises:
+            TypeError: If `value` is not a bool or int.
+            ValueError: If `value` is an integer other than 0 or 1.
+        """
+        if not isinstance(value, int):
+            raise TypeError(f"Expected bool or int, got {type(value).__name__}")
+
+        int_value = int(value)
+        if int_value not in (0, 1):
+            raise ValueError(f"Boolean value must be 0 or 1, not {int_value}")
+
+        return super().__new__(cls, int_value)
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        """
+        Hook into Pydantic's validation system for strict boolean validation.
+
+        This schema ensures that only `True` or `False` are accepted during
+        Pydantic model validation.
+        """
+        # Validator that takes a standard bool and returns an instance of our class.
+        from_bool_validator = core_schema.no_info_plain_validator_function(cls)
+
+        # Schema that first validates the input is a strict bool, then calls our validator.
+        python_schema = core_schema.chain_schema(
+            [core_schema.bool_schema(strict=True), from_bool_validator]
+        )
+
+        return core_schema.union_schema(
+            [
+                # Case 1: The value is already our custom Boolean type.
+                core_schema.is_instance_schema(cls),
+                # Case 2: The value is a standard bool and needs to be validated and wrapped.
+                python_schema,
+            ],
+            # For serialization (e.g., to JSON), convert the instance back to a plain bool.
+            serialization=core_schema.plain_serializer_function_ser_schema(bool),
+        )
+
+    def encode_bytes(self) -> bytes:
+        r"""
+        Serializes the boolean to its SSZ byte representation.
+        - `True` -> `b'\\x01'`
+        - `False` -> `b'\\x00'`
+        """
+        return b"\x01" if self else b"\x00"
+
+    def _raise_type_error(self, other: Any, op_symbol: str) -> None:
+        """Helper to raise a consistent TypeError for unsupported operations."""
+        raise TypeError(
+            f"Unsupported operand type(s) for {op_symbol}: "
+            f"'{type(self).__name__}' and '{type(other).__name__}'"
+        )
+
+    def __add__(self, other: Any) -> Self:
+        """Disable the addition operator (`+`)."""
+        raise TypeError("Arithmetic operations are not supported for Boolean.")
+
+    def __radd__(self, other: Any) -> Self:
+        """Disable the reverse addition operator (`+`)."""
+        raise TypeError("Arithmetic operations are not supported for Boolean.")
+
+    def __sub__(self, other: Any) -> Self:
+        """Disable the subtraction operator (`-`)."""
+        raise TypeError("Arithmetic operations are not supported for Boolean.")
+
+    def __rsub__(self, other: Any) -> Self:
+        """Disable the reverse subtraction operator (`-`)."""
+        raise TypeError("Arithmetic operations are not supported for Boolean.")
+
+    def __and__(self, other: Any) -> Self:
+        """Handle the bitwise AND operator (`&`) strictly."""
+        if not isinstance(other, type(self)):
+            self._raise_type_error(other, "&")
+        return type(self)(super().__and__(other))
+
+    def __rand__(self, other: Any) -> Self:
+        """Handle the reverse bitwise AND operator (`&`) strictly."""
+        return self.__and__(other)
+
+    def __or__(self, other: Any) -> Self:
+        """Handle the bitwise OR operator (`|`) strictly."""
+        if not isinstance(other, type(self)):
+            self._raise_type_error(other, "|")
+        return type(self)(super().__or__(other))
+
+    def __ror__(self, other: Any) -> Self:
+        """Handle the reverse bitwise OR operator (`|`) strictly."""
+        return self.__or__(other)
+
+    def __xor__(self, other: Any) -> Self:
+        """Handle the bitwise XOR operator (`^`) strictly."""
+        if not isinstance(other, type(self)):
+            self._raise_type_error(other, "^")
+        return type(self)(super().__xor__(other))
+
+    def __rxor__(self, other: Any) -> Self:
+        """Handle the reverse bitwise XOR operator (`^`) strictly."""
+        return self.__xor__(other)
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Handle the equality operator (`==`).
+
+        Allows comparison with native `bool` and `int` types (0 or 1).
+
+        It returns `False` for all other types.
+        """
+        if isinstance(other, int):
+            return int(self) == int(other)
+        return False
+
+    def __ne__(self, other: object) -> bool:
+        """
+        Handle the inequality operator (`!=`).
+
+        Allows comparison with native `bool` and `int` types (0 or 1).
+
+         It returns `True` for all other types.
+        """
+        return not self.__eq__(other)
+
+    def __repr__(self) -> str:
+        """Return the official string representation of the object."""
+        return f"Boolean({bool(self)})"
+
+    def __str__(self) -> str:
+        """Return the informal, user-friendly string representation."""
+        return str(bool(self))
+
+    def __hash__(self) -> int:
+        """Return a distinct hash for the object."""
+        return hash((type(self), int(self)))

tests/lean_spec/types/test_boolean.py

@@ -0,0 +1,181 @@
+"""Tests for the Boolean Type."""
+
+from typing import Any, Callable
+
+import pytest
+from pydantic import ValidationError, create_model
+
+from lean_spec.types.boolean import Boolean
+
+
+@pytest.mark.parametrize("valid_value", [True, False])
+def test_pydantic_validation_accepts_valid_bool(valid_value: bool) -> None:
+    """Tests that Pydantic validation correctly accepts a valid boolean."""
+    model = create_model("Model", value=(Boolean, ...))
+    instance: Any = model(value=valid_value)
+    assert isinstance(instance.value, Boolean)
+    assert instance.value == Boolean(valid_value)
+
+
+@pytest.mark.parametrize("invalid_value", [1, 0, 1.0, "True"])
+def test_pydantic_strict_mode_rejects_invalid_types(invalid_value: Any) -> None:
+    """Tests that Pydantic's strict mode rejects types that are not `bool`."""
+    model = create_model("Model", value=(Boolean, ...))
+    with pytest.raises(ValidationError):
+        model(value=invalid_value)
+
+
+@pytest.mark.parametrize("valid_value", [True, False, 1, 0])
+def test_instantiation_from_valid_types(valid_value: bool | int) -> None:
+    """Tests that a Boolean can be instantiated from valid bools and ints."""
+    boolean_instance = Boolean(valid_value)
+    assert int(boolean_instance) == int(valid_value)
+
+
+@pytest.mark.parametrize("invalid_int", [-1, 2, 100])
+def test_instantiation_from_invalid_int_raises_error(invalid_int: int) -> None:
+    """Tests that instantiating with an int other than 0 or 1 raises ValueError."""
+    with pytest.raises(ValueError, match="Boolean value must be 0 or 1"):
+        Boolean(invalid_int)
+
+
+@pytest.mark.parametrize("invalid_type", [1.0, "True", b"\x01", None])
+def test_instantiation_from_invalid_types_raises_error(invalid_type: Any) -> None:
+    """Tests that instantiating with non-bool/non-int types raises a TypeError."""
+    with pytest.raises(TypeError, match="Expected bool or int"):
+        Boolean(invalid_type)
+
+
+def test_instantiation_and_type() -> None:
+    """Tests that a Boolean is an instance of `int` and its own class."""
+    value = Boolean(True)
+    assert isinstance(value, int)
+    assert isinstance(value, Boolean)
+
+
+def test_to_bytes() -> None:
+    r"""Tests that serialization to bytes matches the SSZ spec."""
+    assert Boolean(True).to_bytes() == b"\x01"
+    assert Boolean(False).to_bytes() == b"\x00"
+
+
+@pytest.mark.parametrize(
+    "op",
+    [
+        lambda a, b: a + b,
+        lambda a, b: a - b,
+        lambda a, b: 1 + b,
+        lambda a, b: 1 - b,
+    ],
+)
+def test_arithmetic_operators_raise_error(op: Callable[[Any, Any], Any]) -> None:
+    """Tests that all arithmetic operators are disabled and raise TypeError."""
+    with pytest.raises(TypeError, match="Arithmetic operations are not supported"):
+        op(Boolean(True), Boolean(False))
+
+
+def test_bitwise_operators() -> None:
+    """Tests all standard bitwise operators between Boolean instances."""
+    b_true = Boolean(True)
+    b_false = Boolean(False)
+
+    assert b_true & b_true == b_true
+    assert b_true & b_false == b_false
+    assert b_true | b_false == b_true
+    assert b_false | b_false == b_false
+    assert b_true ^ b_true == b_false
+    assert b_true ^ b_false == b_true
+
+
+@pytest.mark.parametrize("invalid_operand", [1, True, 0.0, "a"])
+def test_bitwise_operators_with_other_types_raise_error(invalid_operand: Any) -> None:
+    """Tests that bitwise operations with non-Boolean types raise TypeError."""
+    with pytest.raises(TypeError):
+        _ = Boolean(True) & invalid_operand
+    with pytest.raises(TypeError):
+        _ = Boolean(True) | invalid_operand
+    with pytest.raises(TypeError):
+        _ = Boolean(True) ^ invalid_operand
+
+
+def test_strict_equality_with_same_type() -> None:
+    """Tests the strict `==` and `!=` operators between two Boolean instances."""
+    assert Boolean(True) == Boolean(True)
+    assert Boolean(False) == Boolean(False)
+    assert Boolean(True) != Boolean(False)
+
+
+@pytest.mark.parametrize(
+    "left_operand, right_operand, expected_result",
+    [
+        # --- Comparisons between two Boolean instances ---
+        (Boolean(True), Boolean(False), False),
+        (Boolean(True), Boolean(True), True),
+        (Boolean(False), Boolean(False), True),
+        # --- Comparisons with compatible native types (Boolean on the left) ---
+        (Boolean(True), True, True),
+        (Boolean(True), 1, True),
+        (Boolean(True), False, False),
+        (Boolean(True), 0, False),
+        # --- Comparisons with compatible native types (Boolean on the right) ---
+        (True, Boolean(True), True),
+        (1, Boolean(True), True),
+        (False, Boolean(True), False),
+        (0, Boolean(True), False),
+        # --- Comparisons with incompatible types ---
+        (Boolean(True), "a string", False),
+        ("a string", Boolean(True), False),
+        (Boolean(True), 1.0, False),
+        (Boolean(True), None, False),
+        (None, Boolean(True), False),
+    ],
+)
+def test_equality_operator(left_operand: Any, right_operand: Any, expected_result: bool) -> None:
+    """Tests the `__eq__` equality operator (`==`) for various type combinations."""
+    assert (left_operand == right_operand) is expected_result
+
+
+@pytest.mark.parametrize(
+    "left_operand, right_operand, expected_result",
+    [
+        # --- Comparisons between two Boolean instances ---
+        (Boolean(True), Boolean(False), True),
+        (Boolean(True), Boolean(True), False),
+        (Boolean(False), Boolean(False), False),
+        # --- Comparisons with compatible native types (Boolean on the left) ---
+        (Boolean(True), True, False),
+        (Boolean(True), 1, False),
+        (Boolean(True), False, True),
+        (Boolean(True), 0, True),
+        # --- Comparisons with compatible native types (Boolean on the right) ---
+        (True, Boolean(True), False),
+        (1, Boolean(True), False),
+        (False, Boolean(True), True),
+        (0, Boolean(True), True),
+        # --- Comparisons with incompatible types ---
+        (Boolean(True), "a string", True),
+        ("a string", Boolean(True), True),
+        (Boolean(True), 1.0, True),
+        (Boolean(True), None, True),
+        (None, Boolean(True), True),
+    ],
+)
+def test_inequality_operator(left_operand: Any, right_operand: Any, expected_result: bool) -> None:
+    """Tests the `__ne__` inequality operator (`!=`) for various type combinations."""
+    assert (left_operand != right_operand) is expected_result
+
+
+def test_repr_and_str() -> None:
+    """Tests the string and official representations."""
+    assert str(Boolean(True)) == "True"
+    assert repr(Boolean(True)) == "Boolean(True)"
+    assert str(Boolean(False)) == "False"
+    assert repr(Boolean(False)) == "Boolean(False)"
+
+
+def test_hash() -> None:
+    """Tests that the hash is distinct from a raw bool."""
+    assert hash(Boolean(True)) != hash(True)
+    assert hash(Boolean(False)) != hash(False)
+    assert hash(Boolean(True)) == hash(Boolean(1))
+    assert hash(Boolean(True)) != hash(Boolean(False))

tests/lean_spec/types/test_uint.py

@@ -1,9 +1,9 @@
 """Unsigned Integer Type Tests."""
 
-from typing import Any, Protocol, Type
+from typing import Any, Type
 
 import pytest
-from pydantic import BaseModel, ValidationError, create_model
+from pydantic import ValidationError, create_model
 
 from lean_spec.types.uint import (
     BaseUint,