valid8r 1.6.0__py3-none-any.whl

valid8r/integrations/__init__.py

@@ -0,0 +1,57 @@
+"""Integrations with popular Python frameworks and libraries.
+
+This module provides integrations with popular Python frameworks:
+
+- Click: CLI framework integration via ParamTypeAdapter
+- Pydantic: Field validator integration via validator_from_parser
+- Environment Variables: Schema-based configuration loading via load_env_config
+
+Examples:
+    >>> # Click integration
+    >>> from valid8r.integrations.click import ParamTypeAdapter
+    >>> from valid8r.core import parsers
+    >>> import click
+    >>>
+    >>> @click.command()
+    ... @click.option('--email', type=ParamTypeAdapter(parsers.parse_email))
+    ... def greet(email):
+    ...     click.echo(f"Hello {email.local}@{email.domain}!")
+
+    >>> # Pydantic integration
+    >>> from valid8r.integrations.pydantic import validator_from_parser
+    >>> from pydantic import BaseModel
+    >>>
+    >>> class User(BaseModel):
+    ...     email: str
+    ...     _validate_email = validator_from_parser(parsers.parse_email)
+
+    >>> # Environment variable integration
+    >>> from valid8r.integrations.env import load_env_config, EnvSchema, EnvField
+    >>> from valid8r.core import parsers
+    >>>
+    >>> schema = EnvSchema(fields={
+    ...     'port': EnvField(parser=parsers.parse_int, default=8080),
+    ...     'debug': EnvField(parser=parsers.parse_bool, default=False),
+    ... })
+    >>> result = load_env_config(schema, prefix='APP_')
+
+"""
+
+from __future__ import annotations
+
+from valid8r.integrations.env import (
+    EnvField,
+    EnvSchema,
+    load_env_config,
+)
+from valid8r.integrations.pydantic import validator_from_parser
+
+__all__ = ['EnvField', 'EnvSchema', 'load_env_config', 'validator_from_parser']
+
+# Click integration is optional, only import if click is available
+try:
+    from valid8r.integrations.click import ParamTypeAdapter
+
+    __all__ += ['ParamTypeAdapter']
+except ImportError:
+    pass

valid8r/integrations/click.py

@@ -0,0 +1,143 @@
+"""Click integration for valid8r parsers.
+
+This module provides ParamTypeAdapter to use valid8r parsers as Click ParamTypes.
+
+Examples:
+    >>> import click
+    >>> from valid8r.core import parsers, validators
+    >>> from valid8r.integrations.click import ParamTypeAdapter
+    >>>
+    >>> # Basic usage with email parser
+    >>> @click.command()
+    ... @click.option('--email', type=ParamTypeAdapter(parsers.parse_email))
+    ... def create_user(email):
+    ...     click.echo(f"Creating user: {email.local}@{email.domain}")
+    >>>
+    >>> # With chained validators for port validation
+    >>> port_parser = parsers.parse_int_with_validation(
+    ...     validators.minimum(1) & validators.maximum(65535)
+    ... )
+    >>> @click.command()
+    ... @click.option('--port', type=ParamTypeAdapter(port_parser, name='port'))
+    ... def start_server(port):
+    ...     click.echo(f"Starting server on port {port}")
+
+"""
+
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from valid8r.core.maybe import Maybe
+
+import click
+
+from valid8r.core.maybe import (
+    Failure,
+    Success,
+)
+
+
+class ParamTypeAdapter(click.ParamType):
+    """Click ParamType adapter for valid8r parsers.
+
+    This class wraps a valid8r parser function (returning Maybe[T]) into a Click ParamType,
+    enabling seamless integration of valid8r's rich validation ecosystem with Click CLIs.
+
+    Args:
+        parser: A function that takes a string and returns Maybe[T]
+        name: Optional custom name for the type (defaults to parser.__name__)
+        error_prefix: Optional prefix for error messages (e.g., "Email address")
+
+    Examples:
+        >>> from valid8r.core import parsers
+        >>> from valid8r.integrations.click import ParamTypeAdapter
+        >>>
+        >>> # Simple email validation
+        >>> email_type = ParamTypeAdapter(parsers.parse_email)
+        >>> email_type.name
+        'parse_email'
+        >>>
+        >>> # With custom name
+        >>> port_type = ParamTypeAdapter(parsers.parse_int, name='port')
+        >>> port_type.name
+        'port'
+        >>>
+        >>> # With custom error prefix
+        >>> email_type = ParamTypeAdapter(
+        ...     parsers.parse_email,
+        ...     error_prefix='Email address'
+        ... )
+
+    """
+
+    def __init__(
+        self,
+        parser: Callable[[str], Maybe[Any]],
+        name: str | None = None,
+        error_prefix: str | None = None,
+    ) -> None:
+        """Initialize the ParamTypeAdapter.
+
+        Args:
+            parser: A valid8r parser function
+            name: Custom name for the type (defaults to parser.__name__)
+            error_prefix: Custom prefix for error messages
+
+        """
+        self.parser = parser
+        self.name = name or parser.__name__
+        self.error_prefix = error_prefix
+
+    def convert(
+        self,
+        value: Any,  # noqa: ANN401
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> Any:  # noqa: ANN401
+        """Convert and validate the input value using the parser.
+
+        Args:
+            value: The input value to convert
+            param: The Click parameter being processed
+            ctx: The Click context
+
+        Returns:
+            The successfully parsed and validated value
+
+        Raises:
+            click.exceptions.BadParameter: If validation fails
+
+        """
+        # If value is not a string, it's already been converted (e.g., from a callback)
+        # In this case, just pass it through
+        if not isinstance(value, str):
+            return value
+
+        # Parse the value using the valid8r parser
+        result = self.parser(value)
+
+        # Handle the Maybe result
+        match result:
+            case Success(val):
+                return val
+            case Failure(err):
+                # Prepend error prefix if provided
+                message = f'{self.error_prefix}: {err}' if self.error_prefix else err
+
+                # Call Click's fail method to raise BadParameter
+                self.fail(message, param, ctx)
+
+        # This should never be reached due to exhaustive pattern matching
+        # but mypy doesn't know that
+        msg = 'Unexpected Maybe state'
+        raise RuntimeError(msg)
+
+
+__all__ = ['ParamTypeAdapter']

valid8r/integrations/env.py

@@ -0,0 +1,220 @@
+"""Environment variable integration module for valid8r.
+
+This module provides utilities for loading typed, validated configuration
+from environment variables using valid8r parsers.
+
+Example:
+    >>> from valid8r.integrations.env import load_env_config, EnvSchema, EnvField
+    >>> from valid8r.core.parsers import parse_int, parse_bool
+    >>> schema = EnvSchema(fields={
+    ...     'port': EnvField(parser=parse_int, default=8080),
+    ...     'debug': EnvField(parser=parse_bool, default=False),
+    ... })
+    >>> env = {'APP_PORT': '3000', 'APP_DEBUG': 'true'}
+    >>> result = load_env_config(schema, prefix='APP_', environ=env)
+    >>> result.value_or({})
+    {'port': 3000, 'debug': True}
+
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+from valid8r.core.maybe import (
+    Failure,
+    Maybe,
+    Success,
+)
+
+
+@dataclass
+class EnvField:
+    """Represents a field in an environment variable schema.
+
+    Args:
+        parser: A function that parses a string into a Maybe[T]
+        default: Optional default value if environment variable is not set
+        required: Whether this field must be present in the environment
+        nested: Optional nested schema for hierarchical configuration
+
+    """
+
+    parser: Callable[[str | None], Maybe[Any]] | None
+    default: Any = None
+    required: bool = False
+    nested: EnvSchema | None = None
+
+
+@dataclass
+class EnvSchema:
+    """Represents a schema for environment variable configuration.
+
+    Args:
+        fields: Dictionary mapping field names to EnvField objects
+
+    """
+
+    fields: dict[str, EnvField]
+
+
+def _process_nested_field(
+    field_name: str,
+    field_spec: EnvField,
+    prefix: str,
+    delimiter: str,
+    environ: dict[str, str],
+) -> tuple[dict[str, Any], list[str]]:
+    """Process a nested schema field.
+
+    Args:
+        field_name: Name of the field
+        field_spec: Field specification with nested schema
+        prefix: Current prefix for environment variables
+        delimiter: Delimiter for nested configuration
+        environ: Environment variables dictionary
+
+    Returns:
+        Tuple of (config dict, error list)
+
+    """
+    config: dict[str, Any] = {}
+    errors: list[str] = []
+
+    if field_spec.nested is not None:
+        nested_prefix = f'{prefix}{field_name.upper()}{delimiter}'
+        nested_result = load_env_config(field_spec.nested, prefix=nested_prefix, delimiter=delimiter, environ=environ)
+
+        match nested_result:
+            case Success(value):
+                config[field_name] = value
+            case Failure(error):
+                errors.append(f'{field_name}: {error}')
+
+    return config, errors
+
+
+def _process_missing_field(field_name: str, field_spec: EnvField) -> tuple[dict[str, Any], list[str], bool]:
+    """Handle missing environment variable field.
+
+    Args:
+        field_name: Name of the field
+        field_spec: Field specification
+
+    Returns:
+        Tuple of (config dict, error list, should_continue)
+
+    """
+    config: dict[str, Any] = {}
+    errors: list[str] = []
+
+    if field_spec.required:
+        errors.append(f'{field_name}: required field is missing')
+        return config, errors, True
+
+    if field_spec.default is not None:
+        config[field_name] = field_spec.default
+        return config, errors, True
+
+    # Optional field without default - skip it
+    return config, errors, True
+
+
+def _parse_field_value(field_name: str, field_spec: EnvField, env_value: str) -> tuple[dict[str, Any], list[str]]:
+    """Parse a field value from an environment variable.
+
+    Args:
+        field_name: Name of the field
+        field_spec: Field specification with parser
+        env_value: Raw environment variable value
+
+    Returns:
+        Tuple of (config dict, error list)
+
+    """
+    config: dict[str, Any] = {}
+    errors: list[str] = []
+
+    if field_spec.parser is not None:
+        parse_result = field_spec.parser(env_value)
+
+        match parse_result:
+            case Success(value):
+                config[field_name] = value
+            case Failure(error):
+                errors.append(f'{field_name}: {error}')
+
+    return config, errors
+
+
+def load_env_config(
+    schema: EnvSchema,
+    *,
+    prefix: str = '',
+    delimiter: str = '_',
+    environ: dict[str, str] | None = None,
+) -> Maybe[dict[str, Any]]:
+    """Load and validate configuration from environment variables.
+
+    Args:
+        schema: The EnvSchema defining expected fields and their parsers
+        prefix: Optional prefix for environment variable names (e.g., 'APP_')
+        delimiter: Delimiter for nested configuration (default: '_')
+        environ: Optional dict of environment variables (defaults to os.environ)
+
+    Returns:
+        Maybe[dict]: Success with parsed config dict, or Failure with error message
+
+    Example:
+        >>> from valid8r.integrations.env import load_env_config, EnvSchema, EnvField
+        >>> from valid8r.core.parsers import parse_int
+        >>> schema = EnvSchema(fields={'port': EnvField(parser=parse_int, default=8080)})
+        >>> env = {'APP_PORT': '3000'}
+        >>> result = load_env_config(schema, prefix='APP_', environ=env)
+        >>> result.value_or({})
+        {'port': 3000}
+
+    """
+    if environ is None:
+        environ = dict(os.environ)
+
+    config: dict[str, Any] = {}
+    errors: list[str] = []
+
+    for field_name, field_spec in schema.fields.items():
+        # Handle nested schemas
+        if field_spec.nested is not None:
+            nested_config, nested_errors = _process_nested_field(field_name, field_spec, prefix, delimiter, environ)
+            config.update(nested_config)
+            errors.extend(nested_errors)
+            continue
+
+        # Construct environment variable name
+        env_var_name = f'{prefix}{field_name.upper()}'
+        env_value = environ.get(env_var_name)
+
+        # Handle missing fields
+        if env_value is None:
+            field_config, field_errors, _ = _process_missing_field(field_name, field_spec)
+            config.update(field_config)
+            errors.extend(field_errors)
+            continue
+
+        # Parse the environment variable value
+        field_config, field_errors = _parse_field_value(field_name, field_spec, env_value)
+        config.update(field_config)
+        errors.extend(field_errors)
+
+    # Return accumulated errors or success
+    if errors:
+        return Maybe.failure('; '.join(errors))
+
+    return Maybe.success(config)

valid8r/integrations/pydantic.py

@@ -0,0 +1,196 @@
+"""Pydantic integration for valid8r parsers.
+
+This module provides utilities to convert valid8r parsers (which return Maybe[T])
+into Pydantic field validators, enabling seamless integration with FastAPI and
+other Pydantic-based frameworks.
+
+The integration supports:
+- Simple field validation with type parsing and validation
+- Nested model validation with field path error reporting
+- List[Model] validation with per-item error reporting
+- Dict[K, V] validation with per-value validation
+- Optional fields and complex structures
+
+Example - Simple Field Validation:
+    >>> from pydantic import BaseModel, field_validator
+    >>> from valid8r.core import parsers, validators
+    >>> from valid8r.integrations.pydantic import validator_from_parser
+    >>>
+    >>> class User(BaseModel):
+    ...     age: int
+    ...
+    ...     @field_validator('age', mode='before')
+    ...     @classmethod
+    ...     def validate_age(cls, v):
+    ...         return validator_from_parser(
+    ...             parsers.parse_int & validators.between(0, 120)
+    ...         )(v)
+
+Example - Nested Model Validation:
+    >>> from valid8r.core.parsers import PhoneNumber
+    >>>
+    >>> class Address(BaseModel):
+    ...     phone: PhoneNumber
+    ...
+    ...     @field_validator('phone', mode='before')
+    ...     @classmethod
+    ...     def validate_phone(cls, v):
+    ...         return validator_from_parser(parsers.parse_phone)(v)
+    >>>
+    >>> class User(BaseModel):
+    ...     name: str
+    ...     address: Address
+    >>>
+    >>> # Validation errors include full field path (e.g., 'address.phone')
+    >>> user = User(name='Alice', address={'phone': '(206) 234-5678'})
+
+Example - List of Models:
+    >>> class LineItem(BaseModel):
+    ...     quantity: int
+    ...
+    ...     @field_validator('quantity', mode='before')
+    ...     @classmethod
+    ...     def validate_quantity(cls, v):
+    ...         def parser(value):
+    ...             return parsers.parse_int(value).bind(validators.minimum(1))
+    ...         return validator_from_parser(parser)(v)
+    >>>
+    >>> class Order(BaseModel):
+    ...     items: list[LineItem]
+    >>>
+    >>> # Validation errors include list index (e.g., 'items[1].quantity')
+    >>> order = Order(items=[{'quantity': '5'}, {'quantity': '10'}])
+
+Example - Dict Value Validation:
+    >>> class Config(BaseModel):
+    ...     ports: dict[str, int]
+    ...
+    ...     @field_validator('ports', mode='before')
+    ...     @classmethod
+    ...     def validate_ports(cls, v):
+    ...         if not isinstance(v, dict):
+    ...             raise ValueError('ports must be a dict')
+    ...         return {k: validator_from_parser(parsers.parse_int)(val) for k, val in v.items()}
+    >>>
+    >>> config = Config(ports={'http': '80', 'https': '443'})
+
+"""
+
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    TypeVar,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from valid8r.core.maybe import Maybe
+
+T = TypeVar('T')
+
+
+def validator_from_parser(
+    parser: Callable[[Any], Maybe[T]],
+    *,
+    error_prefix: str | None = None,
+) -> Callable[[Any], T]:
+    """Convert a valid8r parser into a Pydantic field validator.
+
+    This function takes a valid8r parser (any callable that returns Maybe[T])
+    and converts it into a function suitable for use with Pydantic's
+    field_validator decorator.
+
+    Works seamlessly with:
+    - Simple fields (str, int, custom types)
+    - Nested models (User -> Address -> phone)
+    - Lists of models (Order with list[LineItem])
+    - Dicts with validated values (Config with dict[str, int])
+    - Optional fields (field: Model | None)
+
+    Pydantic automatically handles field path reporting for nested structures,
+    so validation errors will include the full path (e.g., 'address.phone' or
+    'items[1].quantity').
+
+    Args:
+        parser: A valid8r parser function that returns Maybe[T].
+        error_prefix: Optional prefix to prepend to error messages.
+
+    Returns:
+        A validator function that returns T on success or raises ValueError
+        on failure.
+
+    Raises:
+        ValueError: When the parser returns a Failure with the error message.
+
+    Example:
+        >>> from valid8r.core import parsers
+        >>> validator = validator_from_parser(parsers.parse_int)
+        >>> validator('42')
+        42
+        >>> validator('invalid')  # doctest: +SKIP
+        Traceback (most recent call last):
+            ...
+        ValueError: ...
+
+        >>> # With custom error prefix
+        >>> validator = validator_from_parser(parsers.parse_int, error_prefix='User ID')
+        >>> validator('invalid')  # doctest: +SKIP
+        Traceback (most recent call last):
+            ...
+        ValueError: User ID: ...
+
+        >>> # Nested model validation
+        >>> from pydantic import BaseModel, field_validator
+        >>> from valid8r.core.parsers import EmailAddress
+        >>>
+        >>> class Contact(BaseModel):
+        ...     email: EmailAddress
+        ...
+        ...     @field_validator('email', mode='before')
+        ...     @classmethod
+        ...     def validate_email(cls, v):
+        ...         return validator_from_parser(parsers.parse_email)(v)
+        >>>
+        >>> contact = Contact(email='user@example.com')  # doctest: +SKIP
+
+    """
+    from valid8r.core.maybe import (  # noqa: PLC0415
+        Failure,
+        Success,
+    )
+
+    def validate(value: Any) -> T:  # noqa: ANN401
+        """Validate the value using the parser.
+
+        Args:
+            value: The value to validate.
+
+        Returns:
+            The parsed value if successful.
+
+        Raises:
+            ValueError: If parsing fails.
+
+        """
+        result = parser(value)
+
+        match result:
+            case Success(parsed_value):
+                return parsed_value  # type: ignore[no-any-return]
+            case Failure(error_msg):
+                if error_prefix:
+                    msg = f'{error_prefix}: {error_msg}'
+                    raise ValueError(msg)
+                raise ValueError(error_msg)
+            case _:  # pragma: no cover
+                # This should never happen as Maybe only has Success and Failure
+                msg = f'Unexpected Maybe type: {type(result)}'
+                raise TypeError(msg)
+
+    return validate
+
+
+__all__ = ['validator_from_parser']

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']