structtype 0.6.0__tar.gz → 0.8.0__tar.gz

{structtype-0.6.0 → structtype-0.8.0}/Makefile

@@ -93,7 +93,11 @@ format: ## Format files using ruff format
 ##@ Benchmark
 .PHONY: bench
 bench: ## run benchmarks
-	uv run benchmarks/bench_libs.py
+	uv run -p 3.15 benchmarks/bench_libs.py
+
+.PHONY: bench-validators
+bench-validators: ## run Serializer/Validator benchmarks
+	uv run -p 3.15 benchmarks/bench_validators.py
 
 ##@ Utility
 .PHONY: clean

{structtype-0.6.0/src/structtype.egg-info → structtype-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structtype
-Version: 0.6.0
+Version: 0.8.0
 Summary: Fast Struct type with validation and JSON serialization for Python.
 Maintainer-email: Wolfgang Langner <tds333@mailbox.org>
 License-Expression: BSD-3-Clause

{structtype-0.6.0 → structtype-0.8.0}/src/structtype/__init__.py

@@ -1,18 +1,25 @@
 from ._adapter import StructAdapter
+from ._config import StructConfig
 from ._core import (  # type: ignore
     ALL_BUILTIN_TYPES,
     NODEFAULT,
     UNSET,
+    BytesValidator,
+    CollectionValidator,
     DecodeError,
     EncodeError,
     Factory,
     Field,
+    NumericValidator,
     Raw,
+    Serializer,
     Struct,
-    StructConfig,
     StructMeta,
+    StrValidator,
+    TimezoneValidator,
     UnsetType,
     ValidationError,
+    Validator,
 )
 from ._inspect import FieldInfo, fields
 from ._json_schema import json_schema, json_schema_components, json_schema_dump
@@ -22,18 +29,25 @@ __all__ = [
     "ALL_BUILTIN_TYPES",
     "NODEFAULT",
     "UNSET",
+    "BytesValidator",
+    "CollectionValidator",
     "DecodeError",
     "EncodeError",
     "Factory",
     "Field",
     "FieldInfo",
+    "NumericValidator",
     "Raw",
+    "Serializer",
+    "StrValidator",
     "Struct",
     "StructAdapter",
     "StructConfig",
     "StructMeta",
+    "TimezoneValidator",
     "UnsetType",
     "ValidationError",
+    "Validator",
     "__version__",
     "fields",
     "json_schema",

{structtype-0.6.0 → structtype-0.8.0}/src/structtype/__init__.pyi

@@ -8,17 +8,31 @@ from typing import (
     Final,
     Literal,
     TypeAlias,
-    TypeVar,
+    TypedDict,
     final,
     overload,
 )
 
 from typing_extensions import Buffer, Self, dataclass_transform
 
-class StructConfig:
+@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
+
+class StructConfig(TypedDict, total=False):
     frozen: bool
     eq: bool
     order: bool
+    kw_only: bool
     array_like: bool
     repr_omit_defaults: bool
     omit_defaults: bool
@@ -27,15 +41,14 @@ class StructConfig:
     weakref: bool
     dict: bool
     cache_hash: bool
-    tag: str | int | None
+    tag: bool | str | int | Callable[[str], str | int] | None
     tag_field: str | None
-
-# 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")
+    rename: (
+        None
+        | Literal["lower", "upper", "camel", "pascal", "kebab"]
+        | Callable[[str], str | None]
+        | Mapping[str, str]
+    )
 
 class StructMeta(type):
     __struct_fields__: ClassVar[tuple[str, ...]]
@@ -46,81 +59,20 @@ class StructMeta(type):
     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,
-        weakref: bool = False,
-        dict: bool = False,
-        cache_hash: bool = False,
-        validate_on_init: bool = False,
-    ) -> _SM: ...
-
-@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
+    @property
+    def struct_config(self) -> StructConfig: ...
 
 @dataclass_transform(field_specifiers=("Field",))  # type: ignore
 class Struct(metaclass=StructMeta):
     __struct_fields__: ClassVar[tuple[str, ...]]
     __struct_config__: ClassVar[StructConfig]
+    struct_config: ClassVar[StructConfig]
     __struct_alias_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,
-        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: ...
@@ -179,107 +131,95 @@ class Factory:
 
 @final
 class Field:
-    # Numeric:
-    @overload
     def __init__(
         self,
         *,
-        gt: int | float | None = None,
-        lt: int | float | None = None,
-        multiple_of: int | float | 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,
         deprecated: bool | None = None,
-        dump: Callable[[Any], Any] | None = None,
-        validate: Callable[[Any], Any] | None = None,
     ) -> None: ...
-    @overload
+    alias: Final[str | None]
+    title: Final[str | None]
+    description: Final[str | None]
+    examples: Final[list[Any] | None]
+    deprecated: Final[bool | None]
+    json_schema_extra: Final[dict[str, Any] | None]
+    def __rich_repr__(self) -> list[tuple[str, Any]]: ...
+
+@final
+class Serializer:
     def __init__(
         self,
         *,
-        gt: int | float | None = None,
-        le: int | float | None = None,
-        multiple_of: int | float | 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,
-        deprecated: bool | None = None,
+        load: Callable[[Any], Any] | None = None,
         dump: Callable[[Any], Any] | None = None,
-        validate: Callable[[Any], Any] | None = None,
     ) -> None: ...
-    @overload
+    load: Final[Callable[[Any], Any] | None]
+    dump: Final[Callable[[Any], Any] | None]
+
+class Validator:
+    def __init__(self, fn: Callable[[Any], Any] | None = None) -> None: ...
+    def __call__(self, value: Any) -> None: ...
+
+@final
+class NumericValidator(Validator):
     def __init__(
         self,
         *,
+        gt: int | float | None = None,
         ge: int | float | None = None,
         lt: int | float | None = None,
+        le: int | float | None = None,
         multiple_of: int | float | 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,
-        deprecated: bool | None = None,
-        dump: Callable[[Any], Any] | None = None,
-        validate: Callable[[Any], Any] | None = None,
     ) -> None: ...
-    @overload
+    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]
+
+@final
+class StrValidator(Validator):
     def __init__(
         self,
         *,
-        ge: int | float | None = None,
-        le: int | float | None = None,
-        multiple_of: int | float | 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,
-        deprecated: bool | None = None,
-        dump: Callable[[Any], Any] | None = None,
-        validate: Callable[[Any], Any] | None = None,
+        pattern: str | None = None,
+        min_length: _NonNegativeInt | None = None,
+        max_length: _NonNegativeInt | None = None,
     ) -> None: ...
-    # Other (string/datetime):
-    @overload
+    pattern: Final[str | None]
+    min_length: Final[int | None]
+    max_length: Final[int | None]
+
+@final
+class BytesValidator(Validator):
     def __init__(
         self,
         *,
-        pattern: str | None = None,
         min_length: _NonNegativeInt | None = None,
         max_length: _NonNegativeInt | None = None,
-        tz: bool | 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,
-        deprecated: bool | None = None,
-        dump: Callable[[Any], Any] | None = None,
-        validate: Callable[[Any], Any] | None = None,
     ) -> 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]
-    deprecated: Final[bool | None]
-    json_schema_extra: Final[dict[str, Any] | None]
-    dump: Final[Callable[[Any], Any] | None]
-    validate: Final[Callable[[Any], Any] | None]
-    def __rich_repr__(self) -> list[tuple[str, Any]]: ...
+
+@final
+class CollectionValidator(Validator):
+    def __init__(
+        self,
+        *,
+        min_length: _NonNegativeInt | None = None,
+        max_length: _NonNegativeInt | None = None,
+    ) -> None: ...
+    min_length: Final[int | None]
+    max_length: Final[int | None]
+
+@final
+class TimezoneValidator(Validator):
+    def __init__(self, *, tz: bool) -> None: ...
+    tz: Final[bool]
 
 class FieldInfo(Struct):
     name: str

{structtype-0.6.0 → structtype-0.8.0}/src/structtype/_adapter.py

@@ -1,7 +1,7 @@
 from typing import Any, get_args
 
 from ._core import (  # type: ignore
-    Field as _Field,
+    Serializer as _Serializer,
 )
 from ._core import (  # type: ignore
     _dump,
@@ -11,22 +11,22 @@ from ._core import (  # type: ignore
 )
 
 
-def _has_codec(ann):
-    """True if the annotation carries a ``Field`` with ``dump``/``validate``."""
+def _has_serializer(ann):
+    """True if the annotation carries a ``Serializer`` with ``load``/``dump``."""
     metadata = getattr(ann, "__metadata__", None)
     if metadata is not None:
         for meta in metadata:
-            if isinstance(meta, _Field) and (
-                meta.dump is not None or meta.validate is not None
+            if isinstance(meta, _Serializer) and (
+                meta.load is not None or meta.dump is not None
             ):
                 return True
     supertype = getattr(ann, "__supertype__", None)  # NewType
-    if supertype is not None and _has_codec(supertype):
+    if supertype is not None and _has_serializer(supertype):
         return True
     value = getattr(ann, "__value__", None)  # PEP 695 type alias
-    if value is not None and _has_codec(value):
+    if value is not None and _has_serializer(value):
         return True
-    return any(_has_codec(arg) for arg in get_args(ann))
+    return any(_has_serializer(arg) for arg in get_args(ann))
 
 
 class StructAdapter:
@@ -35,8 +35,8 @@ class StructAdapter:
     Useful when you want to validate or serialize plain Python types
     (e.g. ``list[int]``) without defining a full ``Struct`` subclass.
 
-    ``Field(dump=...)`` / ``Field(validate=...)`` codecs are not supported on
-    ``StructAdapter`` — annotations carrying one are rejected. Implement the
+    ``Serializer(load=...)`` / ``Serializer(dump=...)`` codecs are not supported
+    on ``StructAdapter`` — annotations carrying one are rejected. Implement the
     ``struct_dump`` / ``struct_validate`` protocol methods on the custom type,
     or use a ``Struct``.
 
@@ -49,11 +49,12 @@ class StructAdapter:
     __slots__ = ("_type",)
 
     def __init__(self, type: Any):
-        if _has_codec(type):
+        if _has_serializer(type):
             raise TypeError(
-                "`Field(dump=...)`/`Field(validate=...)` codecs are not supported "
-                "on StructAdapter; define `struct_dump`/`struct_validate` methods "
-                "on the custom type, or use a `Struct` instead"
+                "`Serializer(load=...)`/`Serializer(dump=...)` codecs are not "
+                "supported on StructAdapter; define `struct_dump`/"
+                "`struct_validate` methods on the custom type, or use a "
+                "`Struct` instead"
             )
         self._type = type
 

structtype-0.8.0/src/structtype/_config.py

@@ -0,0 +1,31 @@
+from collections.abc import Callable, Mapping
+from typing import Literal, TypedDict
+
+
+class StructConfig(TypedDict, total=False):
+    """Configuration for a Struct type, mirroring the Struct config options.
+
+    Used as a class-body ``struct_config`` attribute. Keys not present inherit
+    from the base class; ``__struct_config__`` returns the fully-resolved dict.
+    """
+
+    frozen: bool
+    eq: bool
+    order: bool
+    kw_only: bool
+    repr_omit_defaults: bool
+    array_like: bool
+    omit_defaults: bool
+    forbid_unknown_fields: bool
+    validate_on_init: bool
+    weakref: bool
+    dict: bool
+    cache_hash: bool
+    tag: bool | str | int | Callable[[str], str | int] | None
+    tag_field: str | None
+    rename: (
+        None
+        | Literal["lower", "upper", "camel", "pascal", "kebab"]
+        | Callable[[str], str | None]
+        | Mapping[str, str]
+    )