pydantic-marshmallow 1.0.0__py3-none-any.whl

pydantic_marshmallow/errors.py

@@ -0,0 +1,154 @@
+"""
+Error handling utilities for the Marshmallow-Pydantic bridge.
+
+This module provides:
+- BridgeValidationError: Exception with valid_data tracking for partial success
+- Error path building and formatting utilities for Pydantic→Marshmallow conversion
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from marshmallow.exceptions import ValidationError as MarshmallowValidationError
+from pydantic import BaseModel, ValidationError as PydanticValidationError
+from pydantic_core import ErrorDetails
+
+
+class BridgeValidationError(MarshmallowValidationError):
+    """
+    Validation error that bridges Marshmallow and Pydantic error formats.
+
+    Extends Marshmallow's ValidationError to track partially valid data,
+    enabling graceful handling of multi-field validation failures.
+
+    Attributes:
+        messages: Dict of field -> error messages (Marshmallow format)
+        valid_data: Dict of successfully validated fields
+        data: Original input data
+    """
+
+    def __init__(
+        self,
+        message: str | list[Any] | dict[str, Any],
+        field_name: str = "_schema",
+        data: Any | None = None,
+        valid_data: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.data = data
+        self.valid_data = valid_data or {}
+        super().__init__(message, field_name, data, valid_data=valid_data or {}, **kwargs)
+
+
+def build_error_path(loc: tuple[Any, ...]) -> str:
+    """
+    Build a dotted error path from Pydantic's location tuple.
+
+    Converts Pydantic's error location format to Marshmallow's dotted path format.
+    Handles collection indices like ("items", 0, "name") -> "items.0.name".
+
+    Args:
+        loc: Pydantic error location tuple (e.g., ('addresses', 0, 'zip_code'))
+
+    Returns:
+        Dotted path string (e.g., 'addresses.0.zip_code')
+    """
+    if len(loc) == 1:
+        return str(loc[0])
+    return ".".join(str(part) for part in loc)
+
+
+def format_pydantic_error(
+    error: ErrorDetails,
+    model_class: type[BaseModel] | None = None,
+) -> str:
+    """
+    Format a Pydantic error dict into a user-friendly message.
+
+    Checks for custom error messages in field metadata when model_class is provided.
+
+    Args:
+        error: Pydantic ErrorDetails with 'msg', 'type', 'loc' keys
+        model_class: Optional Pydantic model for custom message lookup
+
+    Returns:
+        Formatted error message string
+    """
+    msg: str = error.get("msg", "Validation error")
+    error_type: str = error.get("type", "")
+    loc = error.get("loc", ())
+
+    # Check for custom error message in model field metadata
+    if model_class and loc:
+        field_name = str(loc[0])
+        field_info = model_class.model_fields.get(field_name)
+        if field_info and field_info.json_schema_extra:
+            extra = field_info.json_schema_extra
+            if isinstance(extra, dict):
+                custom_messages = extra.get("error_messages")
+                if isinstance(custom_messages, dict):
+                    if error_type in custom_messages:
+                        custom_msg = custom_messages[error_type]
+                        if isinstance(custom_msg, str):
+                            return custom_msg
+                    if "default" in custom_messages:
+                        default_msg = custom_messages["default"]
+                        if isinstance(default_msg, str):
+                            return default_msg
+
+    return msg
+
+
+def convert_pydantic_errors(
+    pydantic_error: PydanticValidationError,
+    model_class: type[BaseModel] | None = None,
+    original_data: dict[str, Any] | None = None,
+) -> BridgeValidationError:
+    """
+    Convert a Pydantic ValidationError to BridgeValidationError.
+
+    Transforms Pydantic's error format to Marshmallow-compatible format,
+    tracking which fields failed and which succeeded.
+
+    Args:
+        pydantic_error: The Pydantic ValidationError to convert
+        model_class: The Pydantic model class (for custom messages)
+        original_data: The original input data
+
+    Returns:
+        BridgeValidationError with Marshmallow-formatted messages and valid_data
+    """
+    errors: dict[str, Any] = {}
+    failed_fields: set[str] = set()
+
+    for error in pydantic_error.errors():
+        loc = error.get("loc", ())
+        msg = format_pydantic_error(error, model_class)
+
+        if loc:
+            field_path = build_error_path(loc)
+            failed_fields.add(str(loc[0]))  # Track top-level field
+
+            if field_path in errors:
+                if isinstance(errors[field_path], list):
+                    errors[field_path].append(msg)
+                else:
+                    errors[field_path] = [errors[field_path], msg]
+            else:
+                errors[field_path] = [msg]
+        else:
+            errors["_schema"] = [*errors.get("_schema", []), msg]
+
+    # Build valid_data: fields that weren't in the error list
+    valid_data: dict[str, Any] = {}
+    if original_data and model_class:
+        for field_name in original_data:
+            if field_name not in failed_fields and field_name in model_class.model_fields:
+                valid_data[field_name] = original_data[field_name]
+
+    return BridgeValidationError(
+        errors,
+        data=original_data,
+        valid_data=valid_data,
+    )

pydantic_marshmallow/field_conversion.py

@@ -0,0 +1,137 @@
+"""
+Field conversion utilities for Pydantic to Marshmallow field mapping.
+
+This module centralizes the conversion of Pydantic model fields to Marshmallow fields,
+eliminating duplication between the metaclass, instance setup, and factory methods.
+"""
+
+from __future__ import annotations
+
+from types import UnionType
+from typing import Any, Union, get_args, get_origin
+
+from marshmallow import fields as ma_fields
+from pydantic import BaseModel
+from pydantic_core import PydanticUndefined
+
+from .type_mapping import type_to_marshmallow_field
+
+
+def convert_pydantic_field(
+    field_name: str,
+    field_info: Any,
+) -> ma_fields.Field:
+    """
+    Convert a single Pydantic FieldInfo to a Marshmallow Field.
+
+    Handles:
+    - Type conversion via type_mapping
+    - Required status (fields without defaults are required)
+    - Default values (static and factory)
+    - Field aliases (data_key)
+    - Optional/None handling (allow_none)
+
+    Args:
+        field_name: Name of the field
+        field_info: Pydantic FieldInfo object
+
+    Returns:
+        Configured Marshmallow field instance
+    """
+    annotation = field_info.annotation
+    ma_field = type_to_marshmallow_field(annotation)
+
+    # Apply default values and set required status
+    if field_info.default is not PydanticUndefined:
+        ma_field.load_default = field_info.default
+        ma_field.dump_default = field_info.default
+        ma_field.required = False
+    elif field_info.default_factory is not None:
+        ma_field.load_default = field_info.default_factory
+        ma_field.required = False
+    else:
+        # No default - field is required
+        ma_field.required = True
+
+    # Handle alias → data_key
+    if field_info.alias:
+        ma_field.data_key = field_info.alias
+
+    # Handle Optional types (X | None or Optional[X]) → allow_none
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+    is_union = origin is Union or origin is UnionType
+    if origin is type(None) or (is_union and type(None) in args):
+        ma_field.allow_none = True
+
+    return ma_field
+
+
+def convert_computed_field(
+    field_name: str,
+    computed_info: Any,
+) -> ma_fields.Field:
+    """
+    Convert a Pydantic computed_field to a dump-only Marshmallow Field.
+
+    Args:
+        field_name: Name of the computed field
+        computed_info: Pydantic ComputedFieldInfo object
+
+    Returns:
+        Dump-only Marshmallow field instance
+    """
+    return_type = getattr(computed_info, 'return_type', Any)
+    ma_field = type_to_marshmallow_field(return_type)
+    ma_field.dump_only = True
+    return ma_field
+
+
+def convert_model_fields(
+    model: type[BaseModel],
+    *,
+    include: set[str] | None = None,
+    exclude: set[str] | None = None,
+    include_computed: bool = True,
+) -> dict[str, ma_fields.Field]:
+    """
+    Convert all fields from a Pydantic model to Marshmallow fields.
+
+    This is the main entry point for field conversion, used by:
+    - PydanticSchemaMeta.__new__()
+    - PydanticSchema._setup_fields_from_model()
+    - PydanticSchema.from_model()
+
+    Args:
+        model: Pydantic model class
+        include: Optional whitelist of field names to include
+        exclude: Optional blacklist of field names to exclude
+        include_computed: Whether to include @computed_field properties
+
+    Returns:
+        Dict mapping field names to Marshmallow field instances
+    """
+    fields: dict[str, ma_fields.Field] = {}
+    exclude_set = exclude or set()
+
+    # Convert regular model fields
+    for field_name, field_info in model.model_fields.items():
+        # Apply filtering
+        if field_name in exclude_set:
+            continue
+        if include is not None and field_name not in include:
+            continue
+
+        fields[field_name] = convert_pydantic_field(field_name, field_info)
+
+    # Convert computed fields (dump-only)
+    if include_computed and hasattr(model, 'model_computed_fields'):
+        for field_name, computed_info in model.model_computed_fields.items():
+            if field_name in exclude_set:
+                continue
+            if include is not None and field_name not in include:
+                continue
+
+            fields[field_name] = convert_computed_field(field_name, computed_info)
+
+    return fields

pydantic_marshmallow/py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561.
+# The marshmallow-pydantic package uses inline type hints.

pydantic_marshmallow/type_mapping.py

@@ -0,0 +1,138 @@
+"""
+Type mapping utilities for converting Python/Pydantic types to Marshmallow fields.
+
+This module provides type-to-field conversions, leveraging Marshmallow's native
+TYPE_MAPPING for basic types and adding support for generic collections.
+"""
+from enum import Enum as PyEnum
+from types import UnionType
+from typing import Any, Literal, Union, get_args, get_origin
+
+from marshmallow import Schema, fields as ma_fields
+from pydantic import BaseModel
+
+# Track models being processed to detect recursion
+_processing_models: set[type[Any]] = set()
+
+
+def type_to_marshmallow_field(type_hint: Any) -> ma_fields.Field:
+    """
+    Map a Python type to a Marshmallow field instance.
+
+    Uses Marshmallow's native TYPE_MAPPING for basic types (str, int, datetime, etc.)
+    and adds support for:
+    - Generic collections (list[T], dict[K, V], set[T], frozenset[T])
+    - Optional types (T | None)
+    - Union types (X | Y)
+    - Tuple types
+    - Nested Pydantic models
+    - Enums
+    - Literal types
+    - Pydantic special types (EmailStr, AnyUrl, etc.)
+
+    Args:
+        type_hint: A Python type annotation
+
+    Returns:
+        An appropriate Marshmallow field instance
+    """
+    origin = get_origin(type_hint)
+    args = get_args(type_hint)
+
+    # Handle NoneType
+    if type_hint is type(None):
+        return ma_fields.Raw(allow_none=True)
+
+    # Handle Literal types
+    if origin is Literal:
+        # For single-value Literal, could be a constant
+        if args and len(args) == 1:
+            # Use Raw with validation - Pydantic will enforce the literal
+            return ma_fields.Raw()
+        return ma_fields.Raw()
+
+    # Handle Union (including Optional) - supports both Union[X, Y] and X | Y syntax
+    if origin is Union or origin is UnionType:
+        non_none_args = [a for a in args if a is not type(None)]
+        if len(non_none_args) == 1:
+            field = type_to_marshmallow_field(non_none_args[0])
+            field.allow_none = True
+            return field
+        return ma_fields.Raw(allow_none=True)
+
+    # Handle Enum types
+    if isinstance(type_hint, type) and issubclass(type_hint, PyEnum):
+        return ma_fields.Enum(type_hint)
+
+    # Handle nested Pydantic models - use Nested with a dynamically created schema
+    if isinstance(type_hint, type) and issubclass(type_hint, BaseModel):
+        # Import here to avoid circular imports
+        from pydantic_marshmallow.bridge import PydanticSchema
+
+        # Check if we're already processing this model (recursion detection)
+        # Use a module-level set to track models being processed
+        if type_hint in _processing_models:
+            # Self-referential model - use Raw to avoid infinite recursion
+            # Pydantic will still handle the validation correctly
+            return ma_fields.Raw()
+
+        try:
+            _processing_models.add(type_hint)
+            # Create a nested schema class for this model
+            nested_schema = PydanticSchema.from_model(type_hint)
+            return ma_fields.Nested(nested_schema)
+        finally:
+            _processing_models.discard(type_hint)
+
+    # Handle list[T]
+    if origin is list:
+        inner: ma_fields.Field = ma_fields.Raw()
+        if args:
+            inner = type_to_marshmallow_field(args[0])
+        return ma_fields.List(inner)
+
+    # Handle dict[K, V]
+    if origin is dict:
+        key_field: ma_fields.Field = ma_fields.String()
+        value_field: ma_fields.Field = ma_fields.Raw()
+        if args and len(args) >= 2:
+            key_field = type_to_marshmallow_field(args[0])
+            value_field = type_to_marshmallow_field(args[1])
+        return ma_fields.Dict(keys=key_field, values=value_field)
+
+    # Handle set[T] and frozenset[T] - convert to List in Marshmallow
+    if origin in (set, frozenset):
+        inner_set: ma_fields.Field = ma_fields.Raw()
+        if args:
+            inner_set = type_to_marshmallow_field(args[0])
+        return ma_fields.List(inner_set)
+
+    # Handle Tuple - use Marshmallow's Tuple field if available
+    if origin is tuple:
+        if args:
+            # Fixed-length tuple with specific types
+            tuple_fields = [type_to_marshmallow_field(arg) for arg in args if arg is not ...]
+            if tuple_fields:
+                return ma_fields.Tuple(tuple_fields=tuple(tuple_fields))
+        return ma_fields.List(ma_fields.Raw())
+
+    # Check for Pydantic special types by module
+    type_module = getattr(type_hint, '__module__', '')
+    type_name = getattr(type_hint, '__name__', str(type_hint))
+
+    # Handle Pydantic networking types
+    if 'pydantic' in type_module:
+        if 'EmailStr' in type_name or type_name == 'EmailStr':
+            return ma_fields.Email()
+        url_types = ('Url', 'URL', 'HttpUrl', 'AnyUrl')
+        if any(ut in type_name for ut in url_types):
+            return ma_fields.URL()
+        if 'IP' in type_name:
+            # IP field exists in marshmallow but may not have type stubs
+            return ma_fields.IP()  # type: ignore[no-untyped-call]
+
+    # Use Marshmallow's native TYPE_MAPPING for basic types
+    # This ensures we stay in sync with Marshmallow's type handling
+    resolved = origin if origin else type_hint
+    field_cls = Schema.TYPE_MAPPING.get(resolved, ma_fields.Raw)
+    return field_cls()

pydantic_marshmallow/validators.py

@@ -0,0 +1,207 @@
+"""
+Custom validator decorators for PydanticSchema.
+
+These provide backwards-compatible validators that work alongside Marshmallow's
+native @validates and @validates_schema decorators. In most cases, users should
+prefer Marshmallow's native decorators (from marshmallow import validates).
+
+Note: These custom decorators are provided for scenarios where additional
+functionality beyond Marshmallow's native validators is needed.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, TypeVar, cast, overload
+
+F = TypeVar("F", bound="ValidatorFunc")
+
+
+class ValidatorFunc(Protocol):
+    """Protocol for validator functions with metadata attributes."""
+
+    _validates_field: str
+    _validates_schema: bool
+    _pass_many: bool
+    _skip_on_field_errors: bool
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Call the validator function."""
+        ...
+
+
+class FieldValidatorFunc(Protocol):
+    """Protocol for field validator functions."""
+
+    _validates_field: str
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Call the field validator."""
+        ...
+
+
+class SchemaValidatorFunc(Protocol):
+    """Protocol for schema validator functions."""
+
+    _validates_schema: bool
+    _pass_many: bool
+    _skip_on_field_errors: bool
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Call the schema validator."""
+        ...
+
+
+# Registry for custom validators (used for backwards compatibility)
+_field_validators: dict[tuple[type[Any], str], list[FieldValidatorFunc]] = {}
+_schema_validators: dict[type[Any], list[SchemaValidatorFunc]] = {}
+
+
+def validates(field_name: str) -> ValidatesDecorator:
+    """
+    Decorator to register a field validator on a PydanticSchema.
+
+    The decorated method receives the field value and should raise
+    ValidationError if validation fails. Compatible with Marshmallow's
+    @validates decorator.
+
+    Note: In most cases, prefer `from marshmallow import validates` which
+    works natively with PydanticSchema via Marshmallow's hook system.
+
+    Example:
+        class UserSchema(PydanticSchema[User]):
+            class Meta:
+                model = User
+
+            @validates("name")
+            def validate_name(self, value):
+                if value.lower() == "admin":
+                    raise ValidationError("Cannot use 'admin' as name")
+    """
+    return ValidatesDecorator(field_name)
+
+
+class ValidatesDecorator:
+    """Decorator class for @validates that preserves function types."""
+
+    def __init__(self, field_name: str) -> None:
+        self.field_name = field_name
+
+    def __call__(self, fn: F) -> F:
+        """Decorate a function as a field validator."""
+        # Use object.__setattr__ to set attributes on the function
+        object.__setattr__(fn, "_validates_field", self.field_name)
+        return fn
+
+
+@overload
+def validates_schema(fn: F) -> F:
+    ...
+
+
+@overload
+def validates_schema(
+    fn: None = None,
+    *,
+    pass_many: bool = False,
+    skip_on_field_errors: bool = True,
+) -> ValidatesSchemaDecorator:
+    ...
+
+
+def validates_schema(
+    fn: F | None = None,
+    *,
+    pass_many: bool = False,
+    skip_on_field_errors: bool = True,
+) -> F | ValidatesSchemaDecorator:
+    """
+    Decorator to register a schema-level validator on a PydanticSchema.
+
+    The decorated method receives the full data dict and should raise
+    ValidationError if validation fails. Compatible with Marshmallow's
+    @validates_schema decorator.
+
+    Note: In most cases, prefer `from marshmallow import validates_schema`
+    which works natively with PydanticSchema via Marshmallow's hook system.
+
+    Args:
+        fn: The validator function (when used without parentheses)
+        pass_many: Whether to pass the full collection when many=True
+        skip_on_field_errors: Skip this validator if field errors exist
+
+    Example:
+        class UserSchema(PydanticSchema[User]):
+            class Meta:
+                model = User
+
+            @validates_schema
+            def validate_user(self, data, **kwargs):
+                if data.get("password") != data.get("confirm_password"):
+                    raise ValidationError("Passwords must match", "_schema")
+    """
+    decorator = ValidatesSchemaDecorator(pass_many, skip_on_field_errors)
+    if fn is not None:
+        return decorator(fn)
+    return decorator
+
+
+class ValidatesSchemaDecorator:
+    """Decorator class for @validates_schema that preserves function types."""
+
+    def __init__(self, pass_many: bool, skip_on_field_errors: bool) -> None:
+        self.pass_many = pass_many
+        self.skip_on_field_errors = skip_on_field_errors
+
+    def __call__(self, func: F) -> F:
+        """Decorate a function as a schema validator."""
+        object.__setattr__(func, "_validates_schema", True)
+        object.__setattr__(func, "_pass_many", self.pass_many)
+        object.__setattr__(func, "_skip_on_field_errors", self.skip_on_field_errors)
+        return func
+
+
+class SchemaWithValidatorCache(Protocol):
+    """Protocol for schema classes that have validator caches."""
+
+    _field_validators_cache: dict[str, list[str]]
+    _schema_validators_cache: list[str]
+
+
+def cache_validators(cls: type[Any]) -> None:
+    """
+    Cache custom validators at class creation time.
+
+    Scans the class for methods decorated with @validates and @validates_schema
+    and caches them for efficient lookup during validation.
+
+    Args:
+        cls: The schema class to cache validators for (must have validator cache attrs)
+    """
+    # Set cache attributes on the class
+    field_cache: dict[str, list[str]] = {}
+    schema_cache: list[str] = []
+
+    for attr_name in dir(cls):
+        if attr_name.startswith('_'):
+            continue
+        try:
+            attr = getattr(cls, attr_name, None)
+        except AttributeError:
+            continue
+
+        if callable(attr):
+            if hasattr(attr, "_validates_field"):
+                # Cast to protocol type since hasattr confirmed the attribute exists
+                field_validator = cast(FieldValidatorFunc, attr)
+                field: str = field_validator._validates_field
+                if field not in field_cache:
+                    field_cache[field] = []
+                field_cache[field].append(attr_name)
+            elif hasattr(attr, "_validates_schema"):
+                schema_cache.append(attr_name)
+
+    # Assign to class - cast to type that has the cache attributes
+    # PydanticSchema defines these as ClassVar, so they exist at runtime
+    schema_cls = cast(type[SchemaWithValidatorCache], cls)
+    schema_cls._field_validators_cache = field_cache
+    schema_cls._schema_validators_cache = schema_cache