valid8r 1.6.0__py3-none-any.whl

valid8r/prompt/basic.py

@@ -0,0 +1,229 @@
+"""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 parsing and validation.
+
+    Displays a prompt to the user, parses their input using the provided parser,
+    validates the result, and optionally retries on failure. Returns a Maybe monad
+    containing either the validated input or an error message.
+
+    Args:
+        prompt_text: The prompt message to display to the user
+        parser: Function to convert string input to desired type (default: returns string as-is)
+        validator: Function to validate the parsed value (default: accepts any value)
+        error_message: Custom error message to display on validation failure
+        default: Default value to use if user provides empty input (displays in prompt)
+        retry: Enable retry on failure - True for unlimited, integer for max attempts, False to disable
+        _test_mode: Internal testing parameter (do not use)
+
+    Returns:
+        Maybe[T]: Success with validated input, or Failure with error message
+
+    Examples:
+        >>> from valid8r.core import parsers, validators
+        >>> from valid8r.prompt import ask
+        >>>
+        >>> # Basic integer input with validation
+        >>> result = ask(
+        ...     "Enter your age: ",
+        ...     parser=parsers.parse_int,
+        ...     validator=validators.between(0, 120),
+        ...     retry=True
+        ... )
+        >>> # User enters "25" -> Success(25)
+        >>> # User enters "invalid" -> prompts again with error message
+        >>>
+        >>> # Input with default value
+        >>> result = ask(
+        ...     "Enter port: ",
+        ...     parser=parsers.parse_int,
+        ...     default=8080
+        ... )
+        >>> # User presses Enter -> Success(8080)
+        >>> # User enters "3000" -> Success(3000)
+        >>>
+        >>> # Limited retries with custom error
+        >>> result = ask(
+        ...     "Email: ",
+        ...     parser=parsers.parse_email,
+        ...     error_message="Invalid email format",
+        ...     retry=3
+        ... )
+        >>> # User has 3 attempts to enter valid email
+        >>>
+        >>> # Boolean input with retry
+        >>> result = ask(
+        ...     "Continue? (yes/no): ",
+        ...     parser=parsers.parse_bool,
+        ...     retry=True
+        ... )
+        >>> # User enters "yes" -> Success(True)
+        >>> # User enters "maybe" -> error, retry prompt
+
+    Note:
+        The returned Maybe must be unwrapped to access the value.
+        Use pattern matching or .value_or() to extract the result.
+
+    """
+    # 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

valid8r/testing/generators.py

@@ -0,0 +1,283 @@
+"""Generators for test cases and test input data."""
+
+from __future__ import annotations
+
+import random
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    TypeVar,
+)
+
+from valid8r.core.maybe import Success
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+    from types import CellType
+
+    from valid8r.core.validators import Validator
+
+T = TypeVar('T')
+
+# Constants for test case generation
+OFFSET_SMALL = 1
+OFFSET_MEDIUM = 5
+OFFSET_LARGE = 10
+OFFSET_XLARGE = 100
+MULTIPLIER_FAR = 2
+
+
+def _extract_numeric_value_from_closure(closure: Iterable[CellType]) -> Any | None:  # noqa: ANN401
+    """Extract a numeric value from a closure."""
+    for cell in closure:
+        value = cell.cell_contents
+        if isinstance(value, int | float):
+            return value
+    return None
+
+
+def _generate_minimum_validator_cases(min_value: float) -> tuple[list[Any], list[Any]]:
+    """Generate test cases for a minimum validator."""
+    valid_cases = [
+        min_value,  # Boundary
+        min_value + OFFSET_SMALL,  # Just above
+        min_value + OFFSET_MEDIUM,  # Above
+        min_value + OFFSET_LARGE,  # Well above
+        min_value * OFFSET_LARGE if min_value > 0 else OFFSET_XLARGE,  # Far above
+    ]
+
+    invalid_cases = [
+        min_value - OFFSET_SMALL,  # Just below
+        min_value - OFFSET_MEDIUM if min_value >= OFFSET_MEDIUM else 0,  # Below
+        min_value - OFFSET_LARGE if min_value >= OFFSET_LARGE else -1,  # Well below
+        -10 if min_value > 0 else min_value - 10,  # Far below
+    ]
+
+    return valid_cases, invalid_cases
+
+
+def _generate_maximum_validator_cases(max_value: float) -> tuple[list[Any], list[Any]]:
+    """Generate test cases for a maximum validator."""
+    valid_cases = [
+        max_value,  # Boundary
+        max_value - OFFSET_SMALL,  # Just below
+        max_value - OFFSET_MEDIUM if max_value >= OFFSET_MEDIUM else 0,  # Below
+        max_value - OFFSET_LARGE if max_value >= OFFSET_LARGE else 0,  # Well below
+        0 if max_value > 0 else max_value // MULTIPLIER_FAR,  # Far below
+    ]
+
+    invalid_cases = [
+        max_value + OFFSET_SMALL,  # Just above
+        max_value + OFFSET_MEDIUM,  # Above
+        max_value + OFFSET_LARGE,  # Well above
+        max_value * MULTIPLIER_FAR,  # Far above
+    ]
+
+    return valid_cases, invalid_cases
+
+
+def _generate_between_validator_cases(min_val: float, max_val: float) -> tuple[list[Any], list[Any]]:
+    """Generate test cases for a between validator."""
+    range_size = max_val - min_val
+    valid_cases = [
+        min_val,  # Min boundary
+        max_val,  # Max boundary
+        (min_val + max_val) // 2,  # Middle
+        min_val + range_size // 4,  # First quarter
+        max_val - range_size // 4,  # Last quarter
+    ]
+
+    invalid_cases = [
+        min_val - 1,  # Just below min
+        max_val + 1,  # Just above max
+        min_val - 10,  # Well below min
+        max_val + 10,  # Well above max
+    ]
+
+    return valid_cases, invalid_cases
+
+
+def _identify_validator_type(validator: Validator[T]) -> tuple[str, Any, Any]:
+    """Identify the type of validator and extract its parameters.
+
+    Returns:
+        A tuple of (validator_type, first_param, second_param)
+
+    """
+    if not hasattr(validator.func, '__closure__') or not validator.func.__closure__:
+        return 'unknown', None, None
+
+    func_str = str(validator.func)
+
+    if 'minimum' in func_str:
+        min_value = _extract_numeric_value_from_closure(validator.func.__closure__)
+        return 'minimum', min_value, None
+
+    if 'maximum' in func_str:
+        max_value = _extract_numeric_value_from_closure(validator.func.__closure__)
+        return 'maximum', max_value, None
+
+    if 'between' in func_str:
+        values = _extract_two_numeric_values(validator.func.__closure__)
+        return 'between', values[0], values[1]
+
+    return 'unknown', None, None
+
+
+def _extract_two_numeric_values(closure: Iterable[CellType]) -> tuple[Any, Any]:
+    """Extract two numeric values from a closure."""
+    values = []
+    for cell in closure:
+        value = cell.cell_contents
+        if isinstance(value, int | float):
+            values.append(value)
+            if len(values) >= 2:  # noqa: PLR2004
+                break
+
+    if len(values) < 2:  # noqa: PLR2004
+        return None, None
+    return values[0], values[1]
+
+
+def generate_test_cases(validator: Validator[T]) -> dict[str, list[Any]]:
+    """Generate test cases for a validator.
+
+    This function analyzes the validator and generates appropriate test cases
+    that should pass and fail the validation.
+
+    Args:
+        validator: The validator to generate test cases for
+
+    Returns:
+        A dictionary with 'valid' and 'invalid' lists of test cases
+
+    Examples:
+        >>> test_cases = generate_test_cases(minimum(10))
+        >>> test_cases
+        {'valid': [10, 11, 15, 20, 100], 'invalid': [9, 5, 0, -10]}
+
+    """
+    # Identify validator type and extract parameters
+    validator_type, param1, param2 = _identify_validator_type(validator)
+
+    # Generate test cases based on validator type
+    valid_cases: list[Any] = []
+    invalid_cases: list[Any] = []
+
+    if validator_type == 'minimum' and param1 is not None:
+        valid_cases, invalid_cases = _generate_minimum_validator_cases(param1)
+
+    elif validator_type == 'maximum' and param1 is not None:
+        valid_cases, invalid_cases = _generate_maximum_validator_cases(param1)
+
+    elif validator_type == 'between' and param1 is not None and param2 is not None:
+        valid_cases, invalid_cases = _generate_between_validator_cases(param1, param2)
+
+    # Use generic cases if we couldn't determine specific ones
+    if not valid_cases:
+        valid_cases = [0, 1, 10, 42, 100]
+    if not invalid_cases:
+        invalid_cases = [-1, -10, -100]
+
+    # Verify categorization against the actual validator
+    actual_valid = []
+    actual_invalid = []
+
+    for case in valid_cases + invalid_cases:
+        result = validator(case)
+        if result.is_success():
+            actual_valid.append(case)
+        else:
+            actual_invalid.append(case)
+
+    return {'valid': actual_valid, 'invalid': actual_invalid}
+
+
+def generate_random_inputs(
+    validator: Validator[T], count: int = 20, range_min: int = -100, range_max: int = 100
+) -> list[T]:
+    """Generate random inputs that include both valid and invalid cases.
+
+    Args:
+        validator: The validator to test against
+        count: Number of inputs to generate
+        range_min: Minimum value for generated integers
+        range_max: Maximum value for generated integers
+
+    Returns:
+        A list of random integers
+
+    Examples:
+        >>> inputs = generate_random_inputs(minimum(0), count=10)
+        >>> len(inputs)
+        10
+
+    """
+    inputs: list[Any] = []
+
+    # Try to make sure we get both valid and invalid cases
+    for _ in range(count):
+        value = random.randint(range_min, range_max)  # noqa: S311
+        inputs.append(value)
+
+    # Verify we have at least one valid and one invalid case
+    has_valid = False
+    has_invalid = False
+
+    for input_val in inputs:
+        result = validator(input_val)
+        match result:
+            case Success(_):
+                has_valid = True
+            case _:
+                has_invalid = True
+
+        if has_valid and has_invalid:
+            break
+
+    # If we're missing either valid or invalid cases, add them explicitly
+    if not has_valid or not has_invalid:
+        # Get test cases that are known to be valid/invalid
+        test_cases = generate_test_cases(validator)
+
+        if not has_valid and test_cases['valid']:
+            # Replace the first item with a valid case
+            inputs[0] = test_cases['valid'][0]
+
+        if not has_invalid and test_cases['invalid']:
+            # Replace the second item with an invalid case
+            inputs[1 if len(inputs) > 1 else 0] = test_cases['invalid'][0]
+
+    return inputs
+
+
+def test_validator_composition(validator: Validator[T]) -> bool:
+    """Test a composed validator with various inputs to verify it works correctly.
+
+    Args:
+        validator: The composed validator to test
+
+    Returns:
+        True if the validator behaves as expected, False otherwise
+
+    Examples:
+        >>> is_valid_age = minimum(0) & maximum(120)
+        >>> test_validator_composition(is_valid_age)  # Returns True
+
+    """
+    # Generate test cases
+    test_cases = generate_test_cases(validator)
+
+    # Check that all valid cases pass
+    for case in test_cases['valid']:
+        result = validator(case)
+        if not result.is_success():
+            return False
+
+    # Check that all invalid cases fail
+    for case in test_cases['invalid']:
+        result = validator(case)
+        if not result.is_failure():
+            return False
+
+    return True

valid8r/testing/mock_input.py

@@ -0,0 +1,84 @@
+"""Utilities for mocking user input during tests."""
+
+from __future__ import annotations
+
+import builtins
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+# Store the original input function
+_original_input = builtins.input
+
+
+@contextmanager
+def MockInputContext(inputs: list[str] | None = None) -> Iterator[None]:  # noqa: N802
+    """Context manager for mocking user input.
+
+    Args:
+        inputs: A list of strings to be returned sequentially by input().
+
+    Yields:
+        None
+
+    Examples:
+        >>> with MockInputContext(["yes", "42"]):
+        ...     answer = input("Continue? ")  # returns "yes"
+        ...     number = input("Enter number: ")  # returns "42"
+
+    """
+    input_values = [] if inputs is None else list(inputs)
+
+    def mock_input(prompt: object = '') -> str:  # noqa: ARG001
+        """Mock implementation of input function.
+
+        Args:
+            prompt: The input prompt (ignored in mock)
+
+        Returns:
+            The next string from the predefined inputs list
+
+        Raises:
+            IndexError: If there are no more inputs available
+
+        """
+        if not input_values:
+            raise IndexError('No more mock inputs available')
+        return input_values.pop(0)
+
+    # Replace the builtin input function
+    builtins.input = mock_input
+
+    try:
+        yield
+    finally:
+        # Restore the original input function
+        builtins.input = _original_input
+
+
+def configure_mock_input(inputs: list[str]) -> None:
+    """Configure input to be mocked globally.
+
+    Unlike MockInputContext, this function replaces the input function
+    globally without restoring it automatically. Use for simple tests
+    where cleanup isn't critical.
+
+    Args:
+        inputs: A list of strings to be returned sequentially by input().
+
+    Examples:
+        >>> configure_mock_input(["yes", "42"])
+        >>> answer = input("Continue? ")  # returns "yes"
+        >>> number = input("Enter number: ")  # returns "42"
+
+    """
+    input_values = list(inputs)  # Create a copy
+
+    def mock_input(prompt: object = '') -> str:  # noqa: ARG001
+        if not input_values:
+            raise IndexError('No more mock inputs available')
+        return input_values.pop(0)
+
+    builtins.input = mock_input