tigrbl_model 0.4.5__py3-none-any.whl

tigrbl_model/__init__.py

@@ -0,0 +1,35 @@
+"""Pydantic-independent models for Tigrbl."""
+
+from .config import ConfigDict, ModelConfig
+from .errors import ErrorDetails, ModelUserError, ValidationError
+from .factory import create_model
+from .fields import AliasChoices, Field, FieldInfo, PydanticUndefined, Undefined
+from .mixins import JsonMixin, SerdeMixin, TomlMixin, YamlMixin
+from .model import BaseModel, Model
+from .root import RootModel
+from .validators import field_validator, model_validator
+
+__version__ = "0.4.5.dev4"
+
+__all__ = [
+    "AliasChoices",
+    "BaseModel",
+    "ConfigDict",
+    "ErrorDetails",
+    "Field",
+    "FieldInfo",
+    "JsonMixin",
+    "Model",
+    "ModelConfig",
+    "ModelUserError",
+    "PydanticUndefined",
+    "RootModel",
+    "SerdeMixin",
+    "TomlMixin",
+    "Undefined",
+    "ValidationError",
+    "YamlMixin",
+    "create_model",
+    "field_validator",
+    "model_validator",
+]

tigrbl_model/config.py

@@ -0,0 +1,36 @@
+"""Model configuration primitives."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ConfigDict(dict[str, Any]):
+    """Dictionary configuration compatible with Tigrbl's Pydantic usage."""
+
+
+ModelConfig = ConfigDict
+
+
+DEFAULT_CONFIG = ConfigDict(
+    extra="ignore",
+    populate_by_name=False,
+    from_attributes=False,
+    arbitrary_types_allowed=False,
+    validate_default=False,
+    use_enum_values=False,
+    json_schema_extra=None,
+)
+
+
+def merge_config(*configs: dict[str, Any] | None) -> ConfigDict:
+    """Merge model configuration from oldest base to newest declaration."""
+
+    merged = ConfigDict(DEFAULT_CONFIG)
+    for config in configs:
+        if config:
+            merged.update(config)
+    return merged
+
+
+__all__ = ["ConfigDict", "ModelConfig"]

tigrbl_model/errors.py

@@ -0,0 +1,98 @@
+"""Structured model validation errors."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Iterable
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorDetails:
+    """One validation failure with a stable location and machine-readable type."""
+
+    type: str
+    loc: tuple[str | int, ...]
+    msg: str
+    input: Any = None
+    ctx: dict[str, Any] | None = None
+
+    def as_dict(self, *, include_url: bool = True) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "type": self.type,
+            "loc": self.loc,
+            "msg": self.msg,
+            "input": self.input,
+        }
+        if self.ctx:
+            result["ctx"] = dict(self.ctx)
+        if include_url:
+            result["url"] = f"https://errors.tigrbl.dev/model/{self.type}"
+        return result
+
+
+class ValidationError(ValueError):
+    """Aggregate validation failures for a model operation."""
+
+    def __init__(self, title: str, errors: Iterable[ErrorDetails | dict[str, Any]]):
+        self.title = title
+        self._errors = tuple(
+            error
+            if isinstance(error, ErrorDetails)
+            else ErrorDetails(
+                type=str(error.get("type", "value_error")),
+                loc=tuple(error.get("loc", ())),
+                msg=str(error.get("msg", "Invalid value")),
+                input=error.get("input"),
+                ctx=error.get("ctx"),
+            )
+            for error in errors
+        )
+        super().__init__(str(self))
+
+    @classmethod
+    def from_exception_data(
+        cls, title: str, line_errors: Iterable[dict[str, Any]]
+    ) -> "ValidationError":
+        return cls(title, line_errors)
+
+    def error_count(self) -> int:
+        return len(self._errors)
+
+    def errors(
+        self,
+        *,
+        include_url: bool = True,
+        include_context: bool = True,
+        include_input: bool = True,
+    ) -> list[dict[str, Any]]:
+        values = [error.as_dict(include_url=include_url) for error in self._errors]
+        for value in values:
+            if not include_context:
+                value.pop("ctx", None)
+            if not include_input:
+                value.pop("input", None)
+        return values
+
+    def json(self, *, indent: int | None = None, **_: Any) -> str:
+        return json.dumps(self.errors(), indent=indent, default=str)
+
+    def __str__(self) -> str:
+        count = len(self._errors)
+        heading = f"{count} validation error{'s' if count != 1 else ''} for {self.title}"
+        lines = [heading]
+        for error in self._errors:
+            location = ".".join(str(item) for item in error.loc) or "__root__"
+            lines.extend((location, f"  {error.msg} [type={error.type}]"))
+        return "\n".join(lines)
+
+
+class ModelUserError(TypeError):
+    """Raised when a declaration uses a removed or unsupported model option."""
+
+    def __init__(self, message: str, *, code: str = "model-user-error") -> None:
+        self.code = code
+        super().__init__(message)
+
+
+__all__ = ["ErrorDetails", "ModelUserError", "ValidationError"]

tigrbl_model/factory.py

@@ -0,0 +1,53 @@
+"""Dynamic model construction."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from .config import ConfigDict
+from .fields import FieldInfo, PydanticUndefined
+from .model import Model
+
+
+def create_model(
+    model_name: str,
+    *,
+    __config__: ConfigDict | dict[str, Any] | None = None,
+    __base__: type[Model] | tuple[type[Model], ...] | None = None,
+    __module__: str | None = None,
+    __validators__: dict[str, Any] | None = None,
+    __doc__: str | None = None,
+    **field_definitions: Any,
+) -> type[Model]:
+    """Create a model class from `(annotation, default)` field definitions."""
+
+    bases = __base__ or Model
+    if not isinstance(bases, tuple):
+        bases = (bases,)
+    annotations: dict[str, Any] = {}
+    namespace: dict[str, Any] = {
+        "__annotations__": annotations,
+        "__module__": __module__ or sys._getframe(1).f_globals.get("__name__", "__main__"),
+    }
+    if __doc__ is not None:
+        namespace["__doc__"] = __doc__
+    if __config__ is not None:
+        namespace["model_config"] = ConfigDict(__config__)
+    namespace.update(__validators__ or {})
+    for name, definition in field_definitions.items():
+        if isinstance(definition, tuple) and len(definition) == 2:
+            annotation, default = definition
+        else:
+            annotation, default = definition, PydanticUndefined
+        annotations[name] = annotation
+        if default is Ellipsis:
+            default = PydanticUndefined
+        if isinstance(default, FieldInfo):
+            namespace[name] = default
+        elif default is not PydanticUndefined:
+            namespace[name] = default
+    return type(model_name, bases, namespace)
+
+
+__all__ = ["create_model"]

tigrbl_model/fields.py

@@ -0,0 +1,172 @@
+"""Field declarations and metadata."""
+
+from __future__ import annotations
+
+import copy
+import re
+from dataclasses import dataclass, field as dataclass_field
+from typing import Any, Callable
+
+
+class _UndefinedType:
+    def __repr__(self) -> str:
+        return "PydanticUndefined"
+
+    def __copy__(self) -> "_UndefinedType":
+        return self
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> "_UndefinedType":
+        return self
+
+
+PydanticUndefined = _UndefinedType()
+Undefined = PydanticUndefined
+
+
+@dataclass(frozen=True, slots=True)
+class AliasChoices:
+    """Ordered validation aliases; the first present alias wins."""
+
+    choices: tuple[str, ...]
+
+    def __init__(self, first: str, *choices: str):
+        object.__setattr__(self, "choices", (first, *choices))
+
+
+@dataclass(slots=True)
+class FieldInfo:
+    """Runtime metadata for one declared model field."""
+
+    annotation: Any = Any
+    default: Any = PydanticUndefined
+    default_factory: Callable[[], Any] | None = None
+    alias: str | None = None
+    validation_alias: str | AliasChoices | None = None
+    serialization_alias: str | None = None
+    title: str | None = None
+    description: str | None = None
+    examples: list[Any] | None = None
+    json_schema_extra: dict[str, Any] | Callable[[dict[str, Any]], None] | None = None
+    gt: Any = None
+    ge: Any = None
+    lt: Any = None
+    le: Any = None
+    multiple_of: Any = None
+    min_length: int | None = None
+    max_length: int | None = None
+    pattern: str | re.Pattern[str] | None = None
+    min_items: int | None = None
+    max_items: int | None = None
+    exclude: bool = False
+    repr: bool = True
+    metadata: list[Any] = dataclass_field(default_factory=list)
+
+    def is_required(self) -> bool:
+        return self.default is PydanticUndefined and self.default_factory is None
+
+    def get_default(self, *, call_default_factory: bool = False) -> Any:
+        if self.default_factory is not None:
+            return self.default_factory() if call_default_factory else None
+        if self.default is PydanticUndefined:
+            return PydanticUndefined
+        return copy.deepcopy(self.default)
+
+    def validation_names(self, name: str) -> tuple[str, ...]:
+        alias = self.validation_alias or self.alias
+        if isinstance(alias, AliasChoices):
+            return alias.choices
+        if isinstance(alias, str):
+            return (alias,)
+        return (name,)
+
+    def serialization_name(self, name: str) -> str:
+        return self.serialization_alias or self.alias or name
+
+    def schema_name(self, name: str, *, mode: str) -> str:
+        if mode == "serialization":
+            return self.serialization_name(name)
+        alias = self.validation_alias or self.alias
+        if isinstance(alias, AliasChoices):
+            return alias.choices[0]
+        return alias if isinstance(alias, str) else name
+
+
+def Field(
+    default: Any = PydanticUndefined,
+    *,
+    default_factory: Callable[[], Any] | None = None,
+    alias: str | None = None,
+    validation_alias: str | AliasChoices | None = None,
+    serialization_alias: str | None = None,
+    title: str | None = None,
+    description: str | None = None,
+    examples: list[Any] | None = None,
+    json_schema_extra: dict[str, Any] | Callable[[dict[str, Any]], None] | None = None,
+    gt: Any = None,
+    ge: Any = None,
+    lt: Any = None,
+    le: Any = None,
+    multiple_of: Any = None,
+    min_length: int | None = None,
+    max_length: int | None = None,
+    pattern: str | re.Pattern[str] | None = None,
+    min_items: int | None = None,
+    max_items: int | None = None,
+    exclude: bool = False,
+    repr: bool = True,
+    **extra: Any,
+) -> FieldInfo:
+    """Declare field defaults, aliases, constraints, and schema metadata."""
+
+    if default is Ellipsis:
+        default = PydanticUndefined
+    if "regex" in extra:
+        from .errors import ModelUserError
+
+        raise ModelUserError(
+            "`regex` is removed; use `pattern` instead",
+            code="removed-kwargs",
+        )
+    if "unique_items" in extra:
+        from .errors import ModelUserError
+
+        raise ModelUserError(
+            "`unique_items` is removed; use a set annotation instead",
+            code="removed-kwargs",
+        )
+    if default is not PydanticUndefined and default_factory is not None:
+        raise TypeError("cannot specify both default and default_factory")
+    info = FieldInfo(
+        default=default,
+        default_factory=default_factory,
+        alias=alias,
+        validation_alias=validation_alias,
+        serialization_alias=serialization_alias,
+        title=title,
+        description=description,
+        examples=examples,
+        json_schema_extra=json_schema_extra,
+        gt=gt,
+        ge=ge,
+        lt=lt,
+        le=le,
+        multiple_of=multiple_of,
+        min_length=min_length,
+        max_length=max_length,
+        pattern=pattern,
+        min_items=min_items,
+        max_items=max_items,
+        exclude=exclude,
+        repr=repr,
+    )
+    info.metadata.extend((key, value) for key, value in extra.items())
+    return info
+
+
+__all__ = [
+    "AliasChoices",
+    "Field",
+    "FieldInfo",
+    "PydanticUndefined",
+    "Undefined",
+]

tigrbl_model/mixins/__init__.py

@@ -0,0 +1,8 @@
+"""Composable serialization capabilities."""
+
+from .json import JsonMixin
+from .serde import SerdeMixin
+from .toml import TomlMixin
+from .yaml import YamlMixin
+
+__all__ = ["JsonMixin", "SerdeMixin", "TomlMixin", "YamlMixin"]

tigrbl_model/mixins/json.py

@@ -0,0 +1,75 @@
+"""JSON serialization and validation capability."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+try:
+    from typing import Self
+except ImportError:  # pragma: no cover - Python 3.10 compatibility
+    from typing_extensions import Self
+
+
+class JsonMixin:
+    def model_dump_json(
+        self,
+        *,
+        indent: int | None = None,
+        include: Any = None,
+        exclude: Any = None,
+        by_alias: bool = False,
+        exclude_unset: bool = False,
+        exclude_defaults: bool = False,
+        exclude_none: bool = False,
+        fallback: Any = None,
+        **_: Any,
+    ) -> str:
+        payload = self.model_dump(  # type: ignore[attr-defined]
+            mode="json",
+            include=include,
+            exclude=exclude,
+            by_alias=by_alias,
+            exclude_unset=exclude_unset,
+            exclude_defaults=exclude_defaults,
+            exclude_none=exclude_none,
+            fallback=fallback,
+        )
+        separators = None if indent is not None else (",", ":")
+        return json.dumps(payload, indent=indent, separators=separators, ensure_ascii=False)
+
+    @classmethod
+    def model_validate_json(
+        cls,
+        json_data: str | bytes | bytearray,
+        *,
+        strict: bool | None = None,
+        context: Any = None,
+        by_alias: bool | None = None,
+        by_name: bool | None = None,
+    ) -> Self:
+        try:
+            payload = json.loads(json_data)
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            from ..errors import ErrorDetails, ValidationError
+
+            raise ValidationError(
+                cls.__name__,
+                [ErrorDetails("json_invalid", (), f"Invalid JSON: {exc}", json_data)],
+            ) from exc
+        return cls.model_validate(  # type: ignore[attr-defined]
+            payload,
+            strict=bool(strict),
+            context=context,
+            by_alias=by_alias,
+            by_name=by_name,
+        )
+
+    def to_json(self, *, indent: int | None = None, **options: Any) -> str:
+        return self.model_dump_json(indent=indent, **options)
+
+    @classmethod
+    def from_json(cls, payload: str | bytes | bytearray, **options: Any) -> Self:
+        return cls.model_validate_json(payload, **options)
+
+
+__all__ = ["JsonMixin"]

tigrbl_model/mixins/serde.py

@@ -0,0 +1,142 @@
+"""Aggregate Python, JSON, YAML, and TOML serialization capability."""
+
+from __future__ import annotations
+
+from dataclasses import fields as dataclass_fields, is_dataclass
+from typing import Any, Callable, Literal
+try:
+    from typing import Self
+except ImportError:  # pragma: no cover - Python 3.10 compatibility
+    from typing_extensions import Self
+
+from ..fields import PydanticUndefined
+from ..serialization import excluded, nested_selection, selected, serialize_value
+from .json import JsonMixin
+from .toml import TomlMixin
+from .yaml import YamlMixin
+
+
+class SerdeMixin(JsonMixin, YamlMixin, TomlMixin):
+    def model_dump(
+        self,
+        *,
+        mode: Literal["python", "json"] = "python",
+        include: Any = None,
+        exclude: Any = None,
+        context: Any = None,
+        by_alias: bool | None = None,
+        exclude_unset: bool = False,
+        exclude_defaults: bool = False,
+        exclude_none: bool = False,
+        round_trip: bool = False,
+        warnings: Any = True,
+        fallback: Callable[[Any], Any] | None = None,
+        serialize_as_any: bool = False,
+    ) -> dict[str, Any]:
+        del context, round_trip, warnings, serialize_as_any
+        by_alias = bool(by_alias)
+        model_fields = getattr(type(self), "model_fields", None)
+        fields_set = getattr(self, "model_fields_set", set())
+        if isinstance(model_fields, dict):
+            source = ((name, info, getattr(self, name, PydanticUndefined)) for name, info in model_fields.items())
+        elif is_dataclass(self):
+            source = (
+                (item.name, None, getattr(self, item.name, PydanticUndefined))
+                for item in dataclass_fields(self)
+            )
+        else:
+            source = (
+                (name, None, value)
+                for name, value in vars(self).items()
+                if not name.startswith("_")
+            )
+        result: dict[str, Any] = {}
+        for name, info, value in source:
+            if value is PydanticUndefined or (info is not None and info.exclude):
+                continue
+            if not selected(include, name, default=include is None):
+                continue
+            if excluded(exclude, name):
+                continue
+            if exclude_unset and name not in fields_set:
+                continue
+            if exclude_none and value is None:
+                continue
+            if exclude_defaults and info is not None and not info.is_required():
+                default = info.get_default(call_default_factory=True)
+                if value == default:
+                    continue
+            output_name = info.serialization_name(name) if by_alias and info is not None else name
+            result[output_name] = serialize_value(
+                value,
+                mode=mode,
+                include=nested_selection(include, name),
+                exclude=nested_selection(exclude, name),
+                by_alias=by_alias,
+                exclude_none=exclude_none,
+                exclude_unset=exclude_unset,
+                exclude_defaults=exclude_defaults,
+                fallback=fallback,
+            )
+        extra = getattr(self, "__model_extra__", None)
+        if extra:
+            result.update(
+                serialize_value(
+                    extra,
+                    mode=mode,
+                    by_alias=by_alias,
+                    exclude_none=exclude_none,
+                    fallback=fallback,
+                )
+            )
+        return result
+
+    @classmethod
+    def model_validate(
+        cls,
+        obj: Any,
+        *,
+        strict: bool | None = None,
+        extra: str | None = None,
+        from_attributes: bool | None = None,
+        context: Any = None,
+        by_alias: bool | None = None,
+        by_name: bool | None = None,
+    ) -> Self:
+        del context, by_alias, by_name
+        if isinstance(obj, cls):
+            return obj
+        if not isinstance(obj, dict):
+            use_attributes = bool(from_attributes) or bool(
+                getattr(cls, "model_config", {}).get("from_attributes", False)
+            )
+            if use_attributes:
+                obj = {
+                    name: getattr(obj, name)
+                    for name in getattr(cls, "model_fields", {})
+                    if hasattr(obj, name)
+                }
+            else:
+                from ..errors import ErrorDetails, ValidationError
+
+                raise ValidationError(
+                    cls.__name__,
+                    [ErrorDetails("model_type", (), "Input should be a valid mapping", obj)],
+                )
+        try:
+            return cls(__tigrbl_strict__=bool(strict), __tigrbl_extra__=extra, **obj)
+        except TypeError as exc:
+            # Dataclass and simple-class Serde consumers do not accept engine options.
+            if "__tigrbl_" not in str(exc):
+                raise
+            return cls(**obj)
+
+    def to_dict(self, **options: Any) -> dict[str, Any]:
+        return self.model_dump(**options)
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any], **options: Any) -> Self:
+        return cls.model_validate(payload, **options)
+
+
+__all__ = ["SerdeMixin"]

tigrbl_model/mixins/toml.py

@@ -0,0 +1,48 @@
+"""TOML serialization and validation capability."""
+
+from __future__ import annotations
+
+from typing import Any
+try:
+    from typing import Self
+except ImportError:  # pragma: no cover - Python 3.10 compatibility
+    from typing_extensions import Self
+
+from ..serialization import strip_toml_nulls
+
+
+class TomlMixin:
+    def model_dump_toml(self, **options: Any) -> str:
+        import tomli_w
+
+        payload = self.model_dump(mode="json", **options)  # type: ignore[attr-defined]
+        return tomli_w.dumps(strip_toml_nulls(payload))
+
+    @classmethod
+    def model_validate_toml(cls, toml_data: str | bytes, **options: Any) -> Self:
+        try:
+            import tomllib
+        except ModuleNotFoundError:  # pragma: no cover - Python 3.10
+            import tomli as tomllib  # type: ignore[no-redef]
+
+        text = toml_data.decode("utf-8") if isinstance(toml_data, bytes) else toml_data
+        try:
+            payload = tomllib.loads(text)
+        except tomllib.TOMLDecodeError as exc:
+            from ..errors import ErrorDetails, ValidationError
+
+            raise ValidationError(
+                cls.__name__,
+                [ErrorDetails("toml_invalid", (), f"Invalid TOML: {exc}", text)],
+            ) from exc
+        return cls.model_validate(payload, **options)  # type: ignore[attr-defined]
+
+    def to_toml(self, **options: Any) -> str:
+        return self.model_dump_toml(**options)
+
+    @classmethod
+    def from_toml(cls, payload: str | bytes, **options: Any) -> Self:
+        return cls.model_validate_toml(payload, **options)
+
+
+__all__ = ["TomlMixin"]