structtype 0.3.0__cp315-cp315-win_amd64.whl

structtype/__init__.py

@@ -0,0 +1,17 @@
+from ._adapter import StrAdapter, StructAdapter
+from ._core import (
+    NODEFAULT,
+    UNSET,
+    DecodeError,
+    EncodeError,
+    Field,
+    Raw,
+    Struct,
+    StructConfig,
+    StructMeta,
+    UnsetType,
+    ValidationError,
+)
+from ._inspect import FieldInfo, fields
+from ._json_schema import json_schema, json_schema_components, json_schema_dump
+from ._version import __version__

structtype/__init__.pyi

@@ -0,0 +1,350 @@
+import enum
+from collections.abc import Callable, Iterable, Iterator, Mapping
+from inspect import Signature
+from typing import Any, ClassVar, Final, Literal, TypeAlias, TypeVar, final, overload
+
+from typing_extensions import Buffer, Self, dataclass_transform
+
+from . import StructConfig
+
+# PEP 673 explicitly rejects using Self in metaclass definitions:
+# https://peps.python.org/pep-0673/#valid-locations-for-self
+#
+# Typeshed works around this by using a type variable as well:
+# https://github.com/python/typeshed/blob/17bde1bd5e556de001adde3c2f340ba1c3581bd2/stdlib/abc.pyi#L14-L19
+_SM = TypeVar("_SM", bound="StructMeta")
+
+class StructMeta(type):
+    __struct_fields__: ClassVar[tuple[str, ...]]
+    __struct_defaults__: ClassVar[tuple[Any, ...]]
+    __struct_encode_fields__: ClassVar[tuple[str, ...]]
+    __match_args__: ClassVar[tuple[str, ...]]
+    @property
+    def __signature__(self) -> Signature: ...
+    @property
+    def __struct_config__(self) -> StructConfig: ...
+    def __new__(
+        mcls: type[_SM],
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        /,
+        *,
+        tag: bool | str | int | Callable[[str], str | int] | None = None,
+        tag_field: str | None = None,
+        rename: (
+            None
+            | Literal["lower", "upper", "camel", "pascal", "kebab"]
+            | Callable[[str], str | None]
+            | Mapping[str, str]
+        ) = None,
+        omit_defaults: bool = False,
+        forbid_unknown_fields: bool = False,
+        frozen: bool = False,
+        eq: bool = True,
+        order: bool = False,
+        kw_only: bool = False,
+        repr_omit_defaults: bool = False,
+        array_like: bool = False,
+        gc: bool = True,
+        weakref: bool = False,
+        dict: bool = False,
+        cache_hash: bool = False,
+        validate_on_init: bool = False,
+    ) -> _SM: ...
+
+_T = TypeVar("_T")
+
+@final
+class UnsetType(enum.Enum):
+    UNSET = "UNSET"
+    def __bool__(self) -> Literal[False]: ...
+
+UNSET: Final = UnsetType.UNSET
+
+@final
+class _NoDefault(enum.Enum):
+    NODEFAULT = "NODEFAULT"
+
+NODEFAULT: Final = _NoDefault.NODEFAULT
+
+@dataclass_transform(field_specifiers=(Field,))
+class Struct(metaclass=StructMeta):
+    __struct_fields__: ClassVar[tuple[str, ...]]
+    __struct_config__: ClassVar[StructConfig]
+    __struct_encode_fields__: ClassVar[tuple[str, ...]]
+    __struct_defaults__: ClassVar[tuple[Any, ...]]
+    __match_args__: ClassVar[tuple[str, ...]]
+    # A default __init__ so that Structs with unknown field types
+    # won't error on every call to `__init__`
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+    def __init_subclass__(
+        cls,
+        tag: bool | str | int | Callable[[str], str | int] | None = None,
+        tag_field: str | None = None,
+        rename: (
+            None
+            | Literal["lower", "upper", "camel", "pascal", "kebab"]
+            | Callable[[str], str | None]
+            | Mapping[str, str]
+        ) = None,
+        omit_defaults: bool = False,
+        forbid_unknown_fields: bool = False,
+        frozen: bool = False,
+        eq: bool = True,
+        order: bool = False,
+        kw_only: bool = False,
+        repr_omit_defaults: bool = False,
+        array_like: bool = False,
+        gc: bool = True,
+        weakref: bool = False,
+        dict: bool = False,
+        cache_hash: bool = False,
+        validate_on_init: bool = False,
+    ) -> None: ...
+    def __rich_repr__(self) -> list[tuple[str, Any]]: ...
+    def __copy__(self) -> Self: ...
+    def __reduce__(self) -> tuple: ...
+    def __replace__(self, **changes: Any) -> Self: ...
+    def __iter__(self) -> Iterator[tuple[str, Any]]: ...
+    def struct_dump_json(
+        self,
+        *,
+        enc_hook: Callable[[Any], Any] | None = None,
+        decimal_format: Literal["string", "number"]
+        | Callable[[Any], Any]
+        | None = None,
+        uuid_format: Literal["canonical", "hex"] | None = None,
+        order: Literal["deterministic", "sorted"] | None = None,
+    ) -> bytes: ...
+    def struct_dump(
+        self,
+        *,
+        enc_hook: Callable[[Any], Any] | None = None,
+        order: Literal["deterministic", "sorted"] | None = None,
+        str_keys: bool = False,
+        builtin_types: Iterable[type] | None = None,
+    ) -> dict[str, Any] | list[Any]: ...
+    def struct_force_setattr(self, name: str, value: Any) -> None: ...
+    def struct_validate_self(self) -> None: ...
+    @classmethod
+    def struct_validate_json(
+        cls: type[_T],
+        buf: str | Buffer,
+        *,
+        strict: bool = True,
+        dec_hook: Callable[[type[Any], Any], Any] | None = None,
+    ) -> _T: ...
+    @classmethod
+    def struct_validate(
+        cls: type[_T],
+        obj: Any,
+        *,
+        strict: bool = True,
+        from_attributes: bool = False,
+        dec_hook: Callable[[type[Any], Any], Any] | None = None,
+    ) -> _T: ...
+
+# Lie and say `Raw` is a subclass of `bytes`, so mypy will accept it in most
+# places where an object that implements the buffer protocol is valid
+@final
+class Raw(bytes):
+    @overload
+    def __new__(cls) -> "Raw": ...
+    @overload
+    def __new__(cls, msg: Buffer | str) -> "Raw": ...
+    def copy(self) -> "Raw": ...
+
+#: We can't represent this in types, only via a name:
+_NonNegativeInt: TypeAlias = int
+
+@final
+class Field:
+    # Numeric:
+    @overload
+    def __init__(
+        self,
+        *,
+        gt: int | float | None = None,
+        lt: int | float | None = None,
+        multiple_of: int | float | None = None,
+        default: Any = NODEFAULT,
+        default_factory: Callable[[], Any] | None = None,
+        alias: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        json_schema_extra: dict[str, Any] | None = None,
+        examples: list[Any] | None = None,
+    ) -> None: ...
+    @overload
+    def __init__(
+        self,
+        *,
+        gt: int | float | None = None,
+        le: int | float | None = None,
+        multiple_of: int | float | None = None,
+        default: Any = NODEFAULT,
+        default_factory: Callable[[], Any] | None = None,
+        alias: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        json_schema_extra: dict[str, Any] | None = None,
+        examples: list[Any] | None = None,
+    ) -> None: ...
+    @overload
+    def __init__(
+        self,
+        *,
+        ge: int | float | None = None,
+        lt: int | float | None = None,
+        multiple_of: int | float | None = None,
+        default: Any = NODEFAULT,
+        default_factory: Callable[[], Any] | None = None,
+        alias: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        json_schema_extra: dict[str, Any] | None = None,
+        examples: list[Any] | None = None,
+    ) -> None: ...
+    @overload
+    def __init__(
+        self,
+        *,
+        ge: int | float | None = None,
+        le: int | float | None = None,
+        multiple_of: int | float | None = None,
+        default: Any = NODEFAULT,
+        default_factory: Callable[[], Any] | None = None,
+        alias: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        json_schema_extra: dict[str, Any] | None = None,
+        examples: list[Any] | None = None,
+    ) -> None: ...
+    # Other (string/datetime):
+    @overload
+    def __init__(
+        self,
+        *,
+        pattern: str | None = None,
+        min_length: _NonNegativeInt | None = None,
+        max_length: _NonNegativeInt | None = None,
+        tz: bool | None = None,
+        default: Any = NODEFAULT,
+        default_factory: Callable[[], Any] | None = None,
+        alias: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        json_schema_extra: dict[str, Any] | None = None,
+        examples: list[Any] | None = None,
+    ) -> None: ...
+    default: Final[Any]
+    default_factory: Final[Callable[[], Any] | None]
+    alias: Final[str | None]
+    gt: Final[int | float | None]
+    ge: Final[int | float | None]
+    lt: Final[int | float | None]
+    le: Final[int | float | None]
+    multiple_of: Final[int | float | None]
+    pattern: Final[str | None]
+    min_length: Final[int | None]
+    max_length: Final[int | None]
+    tz: Final[int | None]
+    title: Final[str | None]
+    description: Final[str | None]
+    examples: Final[list[Any] | None]
+    json_schema_extra: Final[dict[str, Any] | None]
+    def __rich_repr__(self) -> list[tuple[str, Any]]: ...
+
+class StructConfig:
+    frozen: bool
+    eq: bool
+    order: bool
+    array_like: bool
+    gc: bool
+    repr_omit_defaults: bool
+    omit_defaults: bool
+    forbid_unknown_fields: bool
+    validate_on_init: bool
+    weakref: bool
+    dict: bool
+    cache_hash: bool
+    tag: str | int | None
+    tag_field: str | None
+
+class FieldInfo(Struct):
+    name: str
+    encode_name: str
+    type: Any
+    default: Any = NODEFAULT
+    default_factory: Any = NODEFAULT
+
+    @property
+    def required(self) -> bool: ...
+
+def fields(type_or_instance: Struct | type[Struct]) -> tuple[FieldInfo, ...]: ...
+def json_schema(
+    type: Any,
+    *,
+    schema_hook: Callable[[type[Any]], dict[str, Any]] | None = None,
+    ref_template: str = "#/$defs/{name}",
+) -> dict[str, Any]: ...
+def json_schema_dump(
+    type: Any,
+    *,
+    schema_hook: Callable[[type[Any]], dict[str, Any]] | None = None,
+    ref_template: str = "#/$defs/{name}",
+) -> bytes: ...
+def json_schema_components(
+    types: Iterable[Any],
+    *,
+    schema_hook: Callable[[type[Any]], dict[str, Any]] | None = None,
+    ref_template: str = "#/$defs/{name}",
+) -> tuple[tuple[dict[str, Any], ...], dict[str, Any]]: ...
+
+class StructAdapter:
+    def __init__(self, type: Any): ...
+    def struct_validate_json(
+        self,
+        buf: str | Buffer,
+        *,
+        strict: bool = True,
+        dec_hook: Callable[[type[Any], Any], Any] | None = None,
+    ) -> Any: ...
+    def struct_dump_json(
+        self,
+        obj: Any,
+        *,
+        enc_hook: Callable[[Any], Any] | None = None,
+        decimal_format: Literal["string", "number"]
+        | Callable[[Any], Any]
+        | None = None,
+        uuid_format: Literal["canonical", "hex"] | None = None,
+        order: Literal["deterministic", "sorted"] | None = None,
+    ) -> bytes: ...
+    def struct_validate(
+        self,
+        obj: Any,
+        *,
+        strict: bool = True,
+        dec_hook: Callable[[type[Any], Any], Any] | None = None,
+        from_attributes: bool = False,
+    ) -> Any: ...
+    def struct_dump(
+        self,
+        obj: Any,
+        *,
+        enc_hook: Callable[[Any], Any] | None = None,
+        order: Literal["deterministic", "sorted"] | None = None,
+        str_keys: bool = False,
+        builtin_types: Iterable[type] | None = None,
+    ) -> Any: ...
+
+class StrAdapter:
+    def __new__(cls, type: type[Any]) -> type[str]: ...
+
+class EncodeError(ValueError): ...
+class DecodeError(ValueError): ...
+class ValidationError(ValueError): ...
+
+__version__: str

structtype/_adapter.py

@@ -0,0 +1,128 @@
+from typing import Any
+
+from ._core import _dump, _json_decode, _json_encode, _validate
+
+
+class StructAdapter:
+    """Adapter for validating and serializing types without subclassing ``Struct``.
+
+    Useful when you want to validate or serialize plain Python types
+    (e.g. ``list[int]``) without defining a full ``Struct`` subclass.
+
+    >>> from structtype import StructAdapter
+    >>> adapter = StructAdapter(list[int])
+    >>> adapter.struct_validate_json(b"[1, 2, 3]")
+    [1, 2, 3]
+    """
+
+    __slots__ = ("_type",)
+
+    def __init__(self, type: Any):
+        self._type = type
+
+    def struct_validate_json(self, buf, *, strict=True, dec_hook=None):
+        """Validate JSON bytes and decode into the adapter's type.
+
+        Parameters
+        ----------
+        buf : str or bytes
+            The JSON message to decode.
+        strict : bool, optional
+            If True (default), unmatched fields cause an error.
+        dec_hook : callable, optional
+            A callback for customizing decoding of specific types.
+        """
+        return _json_decode(buf, type=self._type, strict=strict, dec_hook=dec_hook)
+
+    def struct_dump_json(
+        self, obj, *, enc_hook=None, decimal_format=None, uuid_format=None, order=None
+    ):
+        """Encode a validated object to JSON bytes.
+
+        Parameters
+        ----------
+        obj : Any
+            A value to encode. Must match the adapter's type.
+        enc_hook : callable, optional
+            A callback for customizing encoding of specific types.
+        decimal_format : str or callable, optional
+            Controls how ``Decimal`` values are encoded.
+        uuid_format : str, optional
+            Controls how ``UUID`` values are encoded.
+        order : str, optional
+            Determines key ordering in JSON objects.
+        """
+        return _json_encode(
+            obj,
+            enc_hook=enc_hook,
+            decimal_format=decimal_format,
+            uuid_format=uuid_format,
+            order=order,
+        )
+
+    def struct_validate(
+        self, obj, *, strict=True, dec_hook=None, from_attributes=False
+    ):
+        """Validate a Python object against the adapter's type.
+
+        Parameters
+        ----------
+        obj : Any
+            A Python object to validate and convert.
+        strict : bool, optional
+            If True (default), unmatched fields cause an error.
+        dec_hook : callable, optional
+            A callback for customizing decoding of specific types.
+        from_attributes : bool, optional
+            If True, accept objects with attributes instead of dict keys.
+        """
+        return _validate(
+            obj,
+            self._type,
+            strict=strict,
+            dec_hook=dec_hook,
+            from_attributes=from_attributes,
+        )
+
+    def struct_dump(
+        self, obj, *, enc_hook=None, order=None, str_keys=False, builtin_types=None
+    ):
+        """Convert a validated object to built-in Python types (``dict``, ``list``, etc.)."""
+        return _dump(
+            obj,
+            builtin_types=builtin_types,
+            str_keys=str_keys,
+            enc_hook=enc_hook,
+            order=order,
+        )
+
+
+class StrAdapter:
+    """Create a ``str`` subclass wrapper for validating a type during
+    structtype serialization.
+
+    Wraps a type that has a single-argument string constructor
+    (e.g. ``HttpUrl``, ``EmailStr``, ``IPv4Address``) into a ``str``
+    subclass. The wrapped value is stored as a string but validated by
+    calling ``typ(value)`` on construction. During structtype
+    validation and serialization, the wrapper is treated as a native
+    ``str``.
+
+    >>> from structtype import StrAdapter, Struct
+    >>> from ipaddress import IPv4Address
+    >>>
+    >>> class Config(Struct):
+    ...     ip: StrAdapter(IPv4Address)
+    """
+
+    __slots__ = ()
+
+    def __new__(cls, typ):
+        return type(
+            f"_Wrapped_{typ.__name__}",
+            (str,),
+            {
+                "__slots__": (),
+                "__new__": lambda self, v: str.__new__(self, str(typ(v))),
+            },
+        )