valid8r 0.2.0__py3-none-any.whl

valid8r/core/validators.py

@@ -0,0 +1,200 @@
+"""Core validators for validating values against specific criteria.
+
+This module provides a collection of validator functions for common validation scenarios.
+All validators follow the same pattern - they take a value and return a Maybe object
+that either contains the validated value or an error message.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Generic,
+    Protocol,
+    TypeVar,
+)
+
+from valid8r.core.combinators import (
+    and_then,
+    not_validator,
+    or_else,
+)
+from valid8r.core.maybe import Maybe
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class SupportsComparison(Protocol):  # noqa: D101
+    def __le__(self, other: object, /) -> bool: ...  # noqa: D105
+    def __lt__(self, other: object, /) -> bool: ...  # noqa: D105
+    def __ge__(self, other: object, /) -> bool: ...  # noqa: D105
+    def __gt__(self, other: object, /) -> bool: ...  # noqa: D105
+    def __eq__(self, other: object, /) -> bool: ...  # noqa: D105
+    def __ne__(self, other: object, /) -> bool: ...  # noqa: D105
+    def __hash__(self, /) -> int: ...  # noqa: D105
+
+
+T = TypeVar('T')
+U = TypeVar('U')
+N = TypeVar('N', bound=SupportsComparison)
+
+
+class Validator(Generic[T]):
+    """A wrapper class for validator functions that supports operator overloading."""
+
+    def __init__(self, func: Callable[[T], Maybe[T]]) -> None:
+        """Initialize a validator with a validation function.
+
+        Args:
+            func: A function that takes a value and returns a Maybe
+
+        """
+        self.func = func
+
+    def __call__(self, value: T) -> Maybe[T]:
+        """Apply the validator to a value.
+
+        Args:
+            value: The value to validate
+
+        Returns:
+            A Maybe containing either the validated value or an error
+
+        """
+        return self.func(value)
+
+    def __and__(self, other: Validator[T]) -> Validator[T]:
+        """Combine with another validator using logical AND.
+
+        Args:
+            other: Another validator to combine with
+
+        Returns:
+            A new validator that passes only if both validators pass
+
+        """
+        return Validator(lambda value: and_then(self.func, other.func)(value))
+
+    def __or__(self, other: Validator[T]) -> Validator[T]:
+        """Combine with another validator using logical OR.
+
+        Args:
+            other: Another validator to combine with
+
+        Returns:
+            A new validator that passes if either validator passes
+
+        """
+        return Validator(lambda value: or_else(self.func, other.func)(value))
+
+    def __invert__(self) -> Validator[T]:
+        """Negate this validator.
+
+        Returns:
+            A new validator that passes if this validator fails
+
+        """
+        return Validator(lambda value: not_validator(self.func, 'Negated validation failed')(value))
+
+
+def minimum(min_value: N, error_message: str | None = None) -> Validator[N]:
+    """Create a validator that ensures a value is at least the minimum.
+
+    Args:
+        min_value: The minimum allowed value
+        error_message: Optional custom error message
+
+    Returns:
+        A validator function
+
+    """
+
+    def validator(value: N) -> Maybe[N]:
+        if value >= min_value:
+            return Maybe.success(value)
+        return Maybe.failure(error_message or f'Value must be at least {min_value}')
+
+    return Validator(validator)
+
+
+def maximum(max_value: N, error_message: str | None = None) -> Validator[N]:
+    """Create a validator that ensures a value is at most the maximum.
+
+    Args:
+        max_value: The maximum allowed value
+        error_message: Optional custom error message
+
+    Returns:
+        A validator function
+
+    """
+
+    def validator(value: N) -> Maybe[N]:
+        if value <= max_value:
+            return Maybe.success(value)
+        return Maybe.failure(error_message or f'Value must be at most {max_value}')
+
+    return Validator(validator)
+
+
+def between(min_value: N, max_value: N, error_message: str | None = None) -> Validator[N]:
+    """Create a validator that ensures a value is between minimum and maximum (inclusive).
+
+    Args:
+        min_value: The minimum allowed value
+        max_value: The maximum allowed value
+        error_message: Optional custom error message
+
+    Returns:
+        A validator function
+
+    """
+
+    def validator(value: N) -> Maybe[N]:
+        if min_value <= value <= max_value:
+            return Maybe.success(value)
+        return Maybe.failure(error_message or f'Value must be between {min_value} and {max_value}')
+
+    return Validator(validator)
+
+
+def predicate(pred: Callable[[T], bool], error_message: str) -> Validator[T]:
+    """Create a validator using a custom predicate function.
+
+    Args:
+        pred: A function that takes a value and returns a boolean
+        error_message: Error message when validation fails
+
+    Returns:
+        A validator function
+
+    """
+
+    def validator(value: T) -> Maybe[T]:
+        if pred(value):
+            return Maybe.success(value)
+        return Maybe.failure(error_message)
+
+    return Validator(validator)
+
+
+def length(min_length: int, max_length: int, error_message: str | None = None) -> Validator[str]:
+    """Create a validator that ensures a string's length is within bounds.
+
+    Args:
+        min_length: Minimum length of the string
+        max_length: Maximum length of the string
+        error_message: Optional custom error message
+
+    Returns:
+        A validator function
+
+    """
+
+    def validator(value: str) -> Maybe[str]:
+        if min_length <= len(value) <= max_length:
+            return Maybe.success(value)
+        return Maybe.failure(error_message or f'String length must be between {min_length} and {max_length}')
+
+    return Validator(validator)

valid8r/prompt/__init__.py

@@ -0,0 +1,8 @@
+# valid8r/prompt/__init__.py
+"""Input prompting functionality for command-line applications."""
+
+from __future__ import annotations
+
+from .basic import ask
+
+__all__ = ['ask']

valid8r/prompt/basic.py

@@ -0,0 +1,190 @@
+"""Basic input prompting functions with validation support.
+
+This module provides functionality for prompting users for input via the command line
+with built-in parsing, validation, and retry logic.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    Generic,
+    TypeVar,
+    cast,
+)
+
+from valid8r.core.maybe import (
+    Failure,
+    Maybe,
+    Success,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+T = TypeVar('T')
+
+
+@dataclass
+class PromptConfig(Generic[T]):
+    """Configuration for the ask function."""
+
+    parser: Callable[[str], Maybe[T]] | None = None
+    validator: Callable[[T], Maybe[T]] | None = None
+    error_message: str | None = None
+    default: T | None = None
+    retry: bool | int = False
+    _test_mode: bool = False
+
+
+def _handle_user_input(prompt_text: str, default: T | None) -> tuple[str, bool]:
+    """Handle getting user input and displaying the prompt.
+
+    Returns:
+        A tuple of (user_input, use_default) where use_default is True if the
+        default value should be used.
+
+    """
+    # Build prompt text with default if available
+    display_prompt = prompt_text
+    if default is not None:
+        display_prompt = f'{prompt_text} [{default}]: '
+
+    # Get user input
+    user_input = input(display_prompt)
+
+    # Check if we should use the default value
+    use_default = not user_input and default is not None
+
+    return user_input, use_default
+
+
+def _process_input(user_input: str, parser: Callable[[str], Maybe[T]], validator: Callable[[T], Maybe[T]]) -> Maybe[T]:
+    """Process user input by parsing and validating."""
+    # Parse input
+    result = parser(user_input)
+
+    # Validate if parsing was successful
+    match result:
+        case Success(value):
+            return validator(value)
+        case Failure(_):
+            return result
+
+    return result  # This line is unreachable but keeps type checkers happy  pragma: no cover
+
+
+def ask(  # noqa: PLR0913
+    prompt_text: str,
+    *,  # Force all other parameters to be keyword-only
+    parser: Callable[[str], Maybe[T]] | None = None,
+    validator: Callable[[T], Maybe[T]] | None = None,
+    error_message: str | None = None,
+    default: T | None = None,
+    retry: bool | int = False,
+    _test_mode: bool = False,
+) -> Maybe[T]:
+    """Prompt the user for input with validation.
+
+    Args:
+        prompt_text: The prompt to display to the user
+        parser: Function to convert string to desired type
+        validator: Function to validate the parsed value
+        error_message: Custom error message for invalid input
+        default: Default value to use if input is empty
+        retry: If True or an integer, retry on invalid input
+        _test_mode: Hidden parameter for testing the final return path
+
+    Returns:
+        A Maybe containing the validated input or an error
+
+    Examples:
+        >>> # This would prompt the user and validate their input
+        >>> from valid8r.core import parsers, validators
+        >>> age = ask(
+        ...     "Enter your age: ",
+        ...     parser=parsers.parse_int,
+        ...     validator=validators.minimum(0),
+        ...     retry=True
+        ... )
+
+    """
+    # Create a config object from the parameters
+    config = PromptConfig(
+        parser=parser,
+        validator=validator,
+        error_message=error_message,
+        default=default,
+        retry=retry,
+        _test_mode=_test_mode,
+    )
+
+    return _ask_with_config(prompt_text, config)
+
+
+def _ask_with_config(prompt_text: str, config: PromptConfig[T]) -> Maybe[T]:
+    """Implement ask using a PromptConfig object."""
+    # For testing the final return path
+    if config._test_mode:  # noqa: SLF001
+        return Maybe.failure(config.error_message or 'Maximum retry attempts reached')
+
+    # Set default parser and validator if not provided
+    def default_parser(s: str) -> Maybe[T]:
+        return Maybe.success(cast('T', s))
+
+    parser: Callable[[str], Maybe[T]] = config.parser if config.parser is not None else default_parser
+    validator = config.validator or (lambda v: Maybe.success(v))
+
+    # Calculate max retries
+    max_retries = config.retry if isinstance(config.retry, int) else float('inf') if config.retry else 0
+
+    return _run_prompt_loop(prompt_text, parser, validator, config.default, max_retries, config.error_message)
+
+
+def _run_prompt_loop(  # noqa: PLR0913
+    prompt_text: str,
+    parser: Callable[[str], Maybe[T]],
+    validator: Callable[[T], Maybe[T]],
+    default: T | None,
+    max_retries: float,
+    error_message: str | None,
+) -> Maybe[T]:
+    """Run the prompt loop with retries."""
+    attempt = 0
+
+    while attempt <= max_retries:
+        # Get user input
+        user_input, use_default = _handle_user_input(prompt_text, default)
+
+        # Use default if requested
+        if use_default:
+            if default is None:
+                return Maybe.failure('No default value provided')
+            return Maybe.success(default)
+        # Process the input
+        result = _process_input(user_input, parser, validator)
+
+        match result:
+            case Success(_):
+                return result
+            case Failure(error):
+                # Handle invalid input
+                attempt += 1
+                if attempt <= max_retries:
+                    _display_error(error, error_message, max_retries, attempt)
+                else:
+                    return result  # Return the failed result after max retries
+
+    return Maybe.failure(error_message or 'Maximum retry attempts reached')
+
+
+def _display_error(result_error: str, custom_error: str | None, max_retries: float, attempt: int) -> None:
+    """Display error message to the user."""
+    err_msg = custom_error or result_error
+    remaining = max_retries - attempt if max_retries < float('inf') else None
+
+    if remaining is not None:
+        print(f'Error: {err_msg} ({remaining} attempt(s) remaining)')
+    else:
+        print(f'Error: {err_msg}')

valid8r/testing/__init__.py

@@ -0,0 +1,32 @@
+# valid8r/testing/__init__.py
+"""Testing utilities for Valid8r.
+
+This module provides tools for testing applications that use Valid8r,
+making it easier to test validation logic, user prompts, and Maybe monads.
+"""
+
+from __future__ import annotations
+
+from valid8r.testing.assertions import (
+    assert_maybe_failure,
+    assert_maybe_success,
+)
+from valid8r.testing.generators import (
+    generate_random_inputs,
+    generate_test_cases,
+    test_validator_composition,
+)
+from valid8r.testing.mock_input import (
+    MockInputContext,
+    configure_mock_input,
+)
+
+__all__ = [
+    'MockInputContext',
+    'assert_maybe_failure',
+    'assert_maybe_success',
+    'configure_mock_input',
+    'generate_random_inputs',
+    'generate_test_cases',
+    'test_validator_composition',
+]

valid8r/testing/assertions.py

@@ -0,0 +1,67 @@
+"""Assertion helpers for testing with Maybe monads."""
+
+from __future__ import annotations
+
+from typing import (
+    Any,
+    TypeVar,
+)
+
+from valid8r.core.maybe import (
+    Failure,
+    Maybe,
+    Success,
+)
+
+T = TypeVar('T')
+
+
+def assert_maybe_success(result: Maybe[T], expected_value: Any) -> bool:  # noqa: ANN401
+    """Assert that a Maybe is a Success with the expected value.
+
+    Args:
+        result: The Maybe instance to check
+        expected_value: The expected value inside the Maybe
+
+    Returns:
+        True if result is a Success with the expected value, False otherwise
+
+    Examples:
+        >>> result = Maybe.success(42)
+        >>> assert_maybe_success(result, 42)  # Returns True
+        >>> assert_maybe_success(result, 43)  # Returns False
+
+    """
+    match result:
+        case Success(value):
+            return bool(value == expected_value)
+        case _:
+            return False
+
+
+def assert_maybe_failure(result: Maybe[T], expected_error: str) -> bool:
+    """Assert that a Maybe is a Failure with the expected error message.
+
+    Args:
+        result: The Maybe instance to check
+        expected_error: The expected error message inside the Maybe
+
+    Returns:
+        True if result is a Failure with the expected error, False otherwise
+
+    Examples:
+        >>> result = Maybe.failure("Invalid input")
+        >>> assert_maybe_failure(result, "Invalid input")  # Returns True
+        >>> assert_maybe_failure(result, "Other error")  # Returns False
+
+    """
+    match result:
+        case Failure(error):
+            return error == expected_error
+        case _:
+            return False
+
+
+def assert_error_equals(result: Maybe[T], expected_error: str, default: str = '') -> bool:
+    """Assert error via error_or helper."""
+    return result.error_or(default) == expected_error