haiway 0.19.5__py3-none-any.whl → 0.20.0__py3-none-any.whl

haiway/state/validation.py

@@ -18,6 +18,13 @@ __all__ = (
 
 
 class AttributeValidation[Type](Protocol):
+    """
+    Protocol defining the interface for attribute validation functions.
+
+    These functions validate and potentially transform input values to
+    ensure they conform to the expected type or format.
+    """
+
     def __call__(
         self,
         value: Any,
@@ -26,11 +33,26 @@ class AttributeValidation[Type](Protocol):
 
 
 class AttributeValidationError(Exception):
+    """
+    Exception raised when attribute validation fails.
+
+    This exception indicates that a value failed to meet the
+    validation requirements for an attribute.
+    """
+
     pass
 
 
 @final
 class AttributeValidator[Type]:
+    """
+    Creates and manages validation functions for attribute types.
+
+    This class is responsible for creating appropriate validation functions
+    based on type annotations. It handles various types including primitives,
+    containers, unions, and custom types like State classes.
+    """
+
     @classmethod
     def of(
         cls,
@@ -39,6 +61,30 @@ class AttributeValidator[Type]:
         *,
         recursion_guard: MutableMapping[str, AttributeValidation[Any]],
     ) -> AttributeValidation[Any]:
+        """
+        Create a validation function for the given type annotation.
+
+        This method analyzes the type annotation and creates an appropriate
+        validation function that can validate and transform values to match
+        the expected type.
+
+        Parameters
+        ----------
+        annotation : AttributeAnnotation
+            The type annotation to create a validator for
+        recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+            A mapping used to detect and handle recursive types
+
+        Returns
+        -------
+        AttributeValidation[Any]
+            A validation function for the given type
+
+        Raises
+        ------
+        TypeError
+            If the annotation represents an unsupported type
+        """
         if isinstance(annotation.origin, NotImplementedError | RuntimeError):
             raise annotation.origin  # raise an error if origin was not properly resolved
 
@@ -101,6 +147,16 @@ class AttributeValidator[Type]:
         annotation: AttributeAnnotation,
         validation: AttributeValidation[Type] | Missing,
     ) -> None:
+        """
+        Initialize a new attribute validator.
+
+        Parameters
+        ----------
+        annotation : AttributeAnnotation
+            The type annotation this validator is for
+        validation : AttributeValidation[Type] | Missing
+            The validation function, or MISSING if not yet set
+        """
         self.annotation: AttributeAnnotation
         object.__setattr__(
             self,
@@ -138,6 +194,26 @@ class AttributeValidator[Type]:
         value: Any,
         /,
     ) -> Any:
+        """
+        Validate a value against this validator's type annotation.
+
+        Parameters
+        ----------
+        value : Any
+            The value to validate
+
+        Returns
+        -------
+        Any
+            The validated and potentially transformed value
+
+        Raises
+        ------
+        AssertionError
+            If the validation function is not set
+        Exception
+            If validation fails
+        """
         assert self.validation is not MISSING  # nosec: B101
         return self.validation(value)  # pyright: ignore[reportCallIssue, reportUnknownVariableType]
 
@@ -153,6 +229,24 @@ def _prepare_validator_of_any(
     /,
     recursion_guard: MutableMapping[str, AttributeValidation[Any]],
 ) -> AttributeValidation[Any]:
+    """
+    Create a validator for the Any type.
+
+    Since Any accepts any value, this validator simply returns the input value unchanged.
+
+    Parameters
+    ----------
+    annotation : AttributeAnnotation
+        The Any type annotation
+    recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+        Mapping to prevent infinite recursion (unused for Any)
+
+    Returns
+    -------
+    AttributeValidation[Any]
+        A validator that accepts any value
+    """
+
     def validator(
         value: Any,
         /,
@@ -167,6 +261,24 @@ def _prepare_validator_of_none(
     /,
     recursion_guard: MutableMapping[str, AttributeValidation[Any]],
 ) -> AttributeValidation[Any]:
+    """
+    Create a validator for the None type.
+
+    This validator only accepts None values.
+
+    Parameters
+    ----------
+    annotation : AttributeAnnotation
+        The None type annotation
+    recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+        Mapping to prevent infinite recursion (unused for None)
+
+    Returns
+    -------
+    AttributeValidation[Any]
+        A validator that accepts only None
+    """
+
     def validator(
         value: Any,
         /,
@@ -185,6 +297,24 @@ def _prepare_validator_of_missing(
     /,
     recursion_guard: MutableMapping[str, AttributeValidation[Any]],
 ) -> AttributeValidation[Any]:
+    """
+    Create a validator for the Missing type.
+
+    This validator only accepts the MISSING sentinel value.
+
+    Parameters
+    ----------
+    annotation : AttributeAnnotation
+        The Missing type annotation
+    recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+        Mapping to prevent infinite recursion (unused for Missing)
+
+    Returns
+    -------
+    AttributeValidation[Any]
+        A validator that accepts only the MISSING sentinel
+    """
+
     def validator(
         value: Any,
         /,
@@ -203,6 +333,24 @@ def _prepare_validator_of_literal(
     /,
     recursion_guard: MutableMapping[str, AttributeValidation[Any]],
 ) -> AttributeValidation[Any]:
+    """
+    Create a validator for Literal types.
+
+    This validator checks if the value is one of the literal values
+    specified in the type annotation.
+
+    Parameters
+    ----------
+    annotation : AttributeAnnotation
+        The Literal type annotation containing allowed values
+    recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+        Mapping to prevent infinite recursion (unused for Literal)
+
+    Returns
+    -------
+    AttributeValidation[Any]
+        A validator that accepts only the specified literal values
+    """
     elements: Sequence[Any] = annotation.arguments
     formatted_type: str = str(annotation)
 
@@ -224,6 +372,24 @@ def _prepare_validator_of_type(
     /,
     recursion_guard: MutableMapping[str, AttributeValidation[Any]],
 ) -> AttributeValidation[Any]:
+    """
+    Create a validator for simple types.
+
+    This validator checks if the value is an instance of the specified type.
+    Used for primitive types, enums, and custom classes.
+
+    Parameters
+    ----------
+    annotation : AttributeAnnotation
+        The type annotation
+    recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+        Mapping to prevent infinite recursion (unused for simple types)
+
+    Returns
+    -------
+    AttributeValidation[Any]
+        A validator that checks instance type
+    """
     validated_type: type[Any] = annotation.origin
     formatted_type: str = str(annotation)
 
@@ -246,6 +412,24 @@ def _prepare_validator_of_set(
     /,
     recursion_guard: MutableMapping[str, AttributeValidation[Any]],
 ) -> AttributeValidation[Any]:
+    """
+    Create a validator for set and frozenset types.
+
+    This validator checks if the value is a set and validates each element
+    according to the set's element type.
+
+    Parameters
+    ----------
+    annotation : AttributeAnnotation
+        The set type annotation
+    recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+        Mapping to prevent infinite recursion for recursive types
+
+    Returns
+    -------
+    AttributeValidation[Any]
+        A validator that validates sets and their elements
+    """
     element_validator: AttributeValidation[Any] = AttributeValidator.of(
         annotation.arguments[0],
         recursion_guard=recursion_guard,
@@ -270,6 +454,24 @@ def _prepare_validator_of_sequence(
     /,
     recursion_guard: MutableMapping[str, AttributeValidation[Any]],
 ) -> AttributeValidation[Any]:
+    """
+    Create a validator for sequence types.
+
+    This validator checks if the value is a sequence and validates each element
+    according to the sequence's element type. Sequences are converted to tuples.
+
+    Parameters
+    ----------
+    annotation : AttributeAnnotation
+        The sequence type annotation
+    recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+        Mapping to prevent infinite recursion for recursive types
+
+    Returns
+    -------
+    AttributeValidation[Any]
+        A validator that validates sequences and their elements
+    """
     element_validator: AttributeValidation[Any] = AttributeValidator.of(
         annotation.arguments[0],
         recursion_guard=recursion_guard,
@@ -295,6 +497,24 @@ def _prepare_validator_of_mapping(
     /,
     recursion_guard: MutableMapping[str, AttributeValidation[Any]],
 ) -> AttributeValidation[Any]:
+    """
+    Create a validator for mapping types.
+
+    This validator checks if the value is a mapping and validates each key and value
+    according to their respective types.
+
+    Parameters
+    ----------
+    annotation : AttributeAnnotation
+        The mapping type annotation
+    recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+        Mapping to prevent infinite recursion for recursive types
+
+    Returns
+    -------
+    AttributeValidation[Any]
+        A validator that validates mappings with their keys and values
+    """
     key_validator: AttributeValidation[Any] = AttributeValidator.of(
         annotation.arguments[0],
         recursion_guard=recursion_guard,
@@ -328,6 +548,24 @@ def _prepare_validator_of_tuple(
     /,
     recursion_guard: MutableMapping[str, AttributeValidation[Any]],
 ) -> AttributeValidation[Any]:
+    """
+    Create a validator for tuple types.
+
+    This validator handles both fixed-length tuples (with specific types for each position)
+    and variable-length tuples (with a repeating element type and Ellipsis).
+
+    Parameters
+    ----------
+    annotation : AttributeAnnotation
+        The tuple type annotation
+    recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+        Mapping to prevent infinite recursion for recursive types
+
+    Returns
+    -------
+    AttributeValidation[Any]
+        A validator that validates tuples based on their type specification
+    """
     if (
         annotation.arguments[-1].origin == Ellipsis
         or annotation.arguments[-1].origin == EllipsisType
@@ -389,6 +627,24 @@ def _prepare_validator_of_union(
     /,
     recursion_guard: MutableMapping[str, AttributeValidation[Any]],
 ) -> AttributeValidation[Any]:
+    """
+    Create a validator for union types.
+
+    This validator tries to validate the value against each type in the union,
+    and succeeds if any validation succeeds.
+
+    Parameters
+    ----------
+    annotation : AttributeAnnotation
+        The union type annotation
+    recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+        Mapping to prevent infinite recursion for recursive types
+
+    Returns
+    -------
+    AttributeValidation[Any]
+        A validator that validates against any type in the union
+    """
     validators: list[AttributeValidation[Any]] = [
         AttributeValidator.of(alternative, recursion_guard=recursion_guard)
         for alternative in annotation.arguments
@@ -420,6 +676,24 @@ def _prepare_validator_of_callable(
     /,
     recursion_guard: MutableMapping[str, AttributeValidation[Any]],
 ) -> AttributeValidation[Any]:
+    """
+    Create a validator for callable types.
+
+    This validator checks if the value is callable, but does not
+    validate the callable's signature.
+
+    Parameters
+    ----------
+    annotation : AttributeAnnotation
+        The callable type annotation
+    recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+        Mapping to prevent infinite recursion (unused for callable)
+
+    Returns
+    -------
+    AttributeValidation[Any]
+        A validator that checks if values are callable
+    """
     formatted_type: str = str(annotation)
 
     def validator(
@@ -441,6 +715,25 @@ def _prepare_validator_of_typed_dict(
     /,
     recursion_guard: MutableMapping[str, AttributeValidation[Any]],
 ) -> AttributeValidation[Any]:
+    """
+    Create a validator for TypedDict types.
+
+    This validator checks if the value is a mapping with keys and values
+    matching the TypedDict specification. Required keys must be present.
+
+    Parameters
+    ----------
+    annotation : AttributeAnnotation
+        The TypedDict type annotation
+    recursion_guard : MutableMapping[str, AttributeValidation[Any]]
+        Mapping to prevent infinite recursion for recursive types
+
+    Returns
+    -------
+    AttributeValidation[Any]
+        A validator that validates TypedDict structures
+    """
+
     def key_validator(
         value: Any,
         /,

haiway/types/default.py

@@ -12,6 +12,16 @@ __all__ = (
 
 @final
 class DefaultValue[Value]:
+    """
+    Container for a default value or a factory function that produces a default value.
+
+    This class stores either a direct default value or a factory function that can
+    produce a default value when needed. It ensures the value or factory cannot be
+    modified after initialization.
+
+    The value can be retrieved by calling the instance like a function.
+    """
+
     __slots__ = ("_value",)
 
     @overload
@@ -45,6 +55,21 @@ class DefaultValue[Value]:
         *,
         factory: Callable[[], Value] | Missing = MISSING,
     ) -> None:
+        """
+        Initialize with either a default value or a factory function.
+
+        Parameters
+        ----------
+        value : Value | Missing
+            The default value to store, or MISSING if using a factory
+        factory : Callable[[], Value] | Missing
+            A function that returns the default value when called, or MISSING if using a direct value
+
+        Raises
+        ------
+        AssertionError
+            If both value and factory are provided
+        """  # noqa: E501
         assert (  # nosec: B101
             value is MISSING or factory is MISSING
         ), "Can't specify both default value and factory"
@@ -65,6 +90,14 @@ class DefaultValue[Value]:
             )
 
     def __call__(self) -> Value | Missing:
+        """
+        Get the default value.
+
+        Returns
+        -------
+        Value | Missing
+            The stored default value, or the result of calling the factory function
+        """
         return self._value()
 
     def __setattr__(
@@ -101,6 +134,29 @@ def Default[Value](
     *,
     factory: Callable[[], Value] | Missing = MISSING,
 ) -> Value:  # it is actually a DefaultValue, but type checker has to be fooled most some cases
+    """
+    Create a default value container that appears as the actual value type.
+
+    This function creates a DefaultValue instance but returns it typed as the actual
+    value type it contains. This allows type checkers to treat it as if it were the
+    actual value while still maintaining the lazy evaluation behavior.
+
+    Parameters
+    ----------
+    value : Value | Missing
+        The default value to store, or MISSING if using a factory
+    factory : Callable[[], Value] | Missing
+        A function that returns the default value when called, or MISSING if using a direct value
+
+    Returns
+    -------
+    Value
+        A DefaultValue instance that appears to be of type Value for type checking purposes
+
+    Notes
+    -----
+    Only one of value or factory should be provided. If both are provided, an exception will be raised.
+    """  # noqa: E501
     return cast(
         Value,
         DefaultValue(

haiway/types/frozen.py

@@ -1,3 +1,21 @@
 __all__ = ("frozenlist",)
 
 type frozenlist[Value] = tuple[Value, ...]
+"""
+A type alias for an immutable sequence of values.
+
+This type represents an immutable list-like structure (implemented as a tuple)
+that can be used when an immutable sequence is required. It provides the same
+indexing and iteration capabilities as a list, but cannot be modified after creation.
+
+The generic parameter Value specifies the type of elements stored in the sequence.
+
+Examples
+--------
+```python
+items: frozenlist[int] = (1, 2, 3)  # Create a frozen list of integers
+first_item = items[0]               # Access elements by index
+for item in items:                  # Iterate over elements
+    process(item)
+```
+"""

haiway/types/missing.py

@@ -10,6 +10,13 @@ __all__ = (
 
 
 class MissingType(type):
+    """
+    Metaclass for the Missing type implementing the singleton pattern.
+
+    Ensures that only one instance of the Missing class ever exists,
+    allowing for identity comparison using the 'is' operator.
+    """
+
     _instance: Any = None
 
     def __call__(cls) -> Any:
@@ -25,6 +32,13 @@ class MissingType(type):
 class Missing(metaclass=MissingType):
     """
     Type representing absence of a value. Use MISSING constant for its value.
+
+    This is a singleton class that represents the absence of a value, similar to
+    None but semantically different. Where None represents "no value", MISSING
+    represents "no value provided" or "value intentionally omitted".
+
+    The MISSING constant is the only instance of this class and should be used
+    for all comparisons using the 'is' operator, not equality testing.
     """
 
     __slots__ = ()
@@ -72,6 +86,30 @@ def is_missing(
     check: Any | Missing,
     /,
 ) -> TypeGuard[Missing]:
+    """
+    Check if a value is the MISSING sentinel.
+
+    This function implements a TypeGuard that helps static type checkers
+    understand when a value is confirmed to be the MISSING sentinel.
+
+    Parameters
+    ----------
+    check : Any | Missing
+        The value to check
+
+    Returns
+    -------
+    TypeGuard[Missing]
+        True if the value is MISSING, False otherwise
+
+    Examples
+    --------
+    ```python
+    if is_missing(value):
+        # Here, type checkers know that value is Missing
+        provide_default()
+    ```
+    """
     return check is MISSING
 
 
@@ -79,6 +117,30 @@ def not_missing[Value](
     check: Value | Missing,
     /,
 ) -> TypeGuard[Value]:
+    """
+    Check if a value is not the MISSING sentinel.
+
+    This function implements a TypeGuard that helps static type checkers
+    understand when a value is confirmed not to be the MISSING sentinel.
+
+    Parameters
+    ----------
+    check : Value | Missing
+        The value to check
+
+    Returns
+    -------
+    TypeGuard[Value]
+        True if the value is not MISSING, False otherwise
+
+    Examples
+    --------
+    ```python
+    if not_missing(value):
+        # Here, type checkers know that value is of type Value
+        process_value(value)
+    ```
+    """
     return check is not MISSING
 
 
@@ -88,6 +150,33 @@ def when_missing[Value](
     *,
     value: Value,
 ) -> Value:
+    """
+    Substitute a default value when the input is MISSING.
+
+    This function provides a convenient way to replace the MISSING
+    sentinel with a default value, similar to how the or operator
+    works with None but specifically for the MISSING sentinel.
+
+    Parameters
+    ----------
+    check : Value | Missing
+        The value to check
+    value : Value
+        The default value to use if check is MISSING
+
+    Returns
+    -------
+    Value
+        The original value if not MISSING, otherwise the provided default
+
+    Examples
+    --------
+    ```python
+    result = when_missing(optional_value, value=default_value)
+    # result will be default_value if optional_value is MISSING
+    # otherwise it will be optional_value
+    ```
+    """
     if check is MISSING:
         return value