structtype 0.14.0__tar.gz → 0.15.0__tar.gz

{structtype-0.14.0 → structtype-0.15.0}/AGENTS.md

@@ -34,7 +34,11 @@ Use `make` targets where available. Targeted tests can be run directly with
 | Static checks | `make check` |
 
 Benchmark targets: `make bench`, `make bench-validators`, `make bench-codecs`,
-`make bench-csv-1m`, `make bench-strings` (run sequentially; CPU-bound).
+`make bench-field-types`, `make bench-csv-1m`, `make bench-strings`
+(run sequentially; CPU-bound; never in parallel).
+
+Benchmarks run on free-threaded CPython (3.15t) via `BENCH_PYTHON` (override
+with `make bench BENCH_PYTHON=3.15`); see `docs/benchmarks.rst`.
 
 ## Conventions
 
@@ -48,12 +52,14 @@ Benchmark targets: `make bench`, `make bench-validators`, `make bench-codecs`,
 - Sentinel values: `NODEFAULT`, `UNSET`, `_NoDefault`, `UnsetType`
 - never do git commit
 - check for performance regressions, speed is a goal
+- no parallel benchmarks
+- keep C code simple, fast, readable and compatible to freethreading
 
 ## Key API
 
 - `structtype.Struct` — base class with config options (frozen, tag, rename, etc.)
 - `structtype.Field` — field metadata (alias, title, description, examples, deprecated, json_schema_extra)
-- `structtype.Constraint` — base constraint (callable `fn`); subclasses: `NumericConstraint`, `StrConstraint`, `BytesConstraint`, `CollectionConstraint`, `TimezoneConstraint`
+- `structtype.Constraint` — base constraint (callable `_fn`, positional-only in the constructor); subclasses: `NumericConstraint`, `StrConstraint`, `BytesConstraint`, `CollectionConstraint`, `TimezoneConstraint`
 - `structtype.Serializer` — load/dump codecs for supported custom and native types
 - `structtype.fields(type_or_instance)` — get FieldInfo tuple for a struct type/instance
 - `structtype._inspect.type_info()` / `multi_type_info()` — type introspection

{structtype-0.14.0 → structtype-0.15.0}/MANIFEST.in

@@ -1,4 +1,3 @@
-prune .devcontainer
 prune .github
 prune benchmarks
 prune docs

{structtype-0.14.0 → structtype-0.15.0}/Makefile

@@ -6,7 +6,8 @@ export UV_MANAGED_PYTHON ?= 1
 ##@ Build
 .PHONY: build
 build: ## Build
-	uv build
+	uv build --sdist
+	uv build --wheel
 
 .PHONY: docs
 docs: ## build docs
@@ -107,9 +108,7 @@ test-debug: ## Build core with Py_DEBUG + ASan/UBSan + debug allocator and run a
 		$(DEBUG_VENV)/bin/python -m pytest
 
 .PHONY: check
-check: ## Run all checks
-	-uvx ty check ${SOURCE_DIR}
-	uvx ruff check ${SOURCE_DIR}
+check: ruff-check type-check ## Run all checks
 
 .PHONY: ruff-check
 ruff-check: ## Lint using ruff
@@ -117,8 +116,7 @@ ruff-check: ## Lint using ruff
 
 .PHONY: type-check
 type-check: ## Type check with
-	-uvx ty check ${SOURCE_DIR}
-	uvx pyrefly check ${SOURCE_DIR}
+	uvx ty check ${SOURCE_DIR}
 
 .PHONY: typecheck-tests
 typecheck-tests: ## Type check tests/typecheck fixtures (skipped when tools unavailable)
@@ -131,25 +129,34 @@ format: ## Format files using ruff format
 	uvx ruff format ${SOURCE_DIR}
 
 ##@ Benchmark
+# Published comparisons use free-threaded CPython (see docs/benchmarks.rst).
+# Benchmark scripts are PEP 723 scripts, so this builds an isolated per-script
+# environment and does not touch the project `.venv`.
+BENCH_PYTHON ?= 3.15t
+
 .PHONY: bench
 bench: ## run benchmarks
-	uv run -p 3.15 benchmarks/bench_libs.py
+	uv run -p $(BENCH_PYTHON) benchmarks/bench_libs.py
 
 .PHONY: bench-validators
 bench-validators: ## run Serializer/Validator benchmarks
-	uv run -p 3.15 benchmarks/bench_validators.py
+	uv run -p $(BENCH_PYTHON) benchmarks/bench_validators.py
 
 .PHONY: bench-codecs
 bench-codecs: ## run Constraint + Serializer heavy benchmarks
-	uv run -p 3.15 benchmarks/bench_codecs.py
+	uv run -p $(BENCH_PYTHON) benchmarks/bench_codecs.py
+
+.PHONY: bench-field-types
+bench-field-types: ## run per-field-type benchmarks
+	uv run -p $(BENCH_PYTHON) benchmarks/bench_field_types.py
 
 .PHONY: bench-csv-1m
 bench-csv-1m: ## run 1M-row on-disk CSV benchmark
-	uv run -p 3.15 benchmarks/bench_csv_1m.py
+	uv run -p $(BENCH_PYTHON) benchmarks/bench_csv_1m.py
 
 .PHONY: bench-strings
 bench-strings: ## run long-string JSON codec benchmark
-	uv run -p 3.15 benchmarks/bench_strings.py
+	uv run -p $(BENCH_PYTHON) benchmarks/bench_strings.py
 
 ##@ Utility
 .PHONY: clean
@@ -192,4 +199,4 @@ update-python: ## Reinstall managed Python versions to latest release
 
 .PHONY: help
 help:  ## Display this help
-	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make <target>\033[36m\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make <target>\033[36m\033[0m\n"} /^[a-zA-Z0-9_-]+:.*?##/ { printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

{structtype-0.14.0 → structtype-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structtype
-Version: 0.14.0
+Version: 0.15.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.14.0 → structtype-0.15.0}/src/structtype/__init__.pyi

@@ -1,5 +1,4 @@
 # ruff: noqa: PYI041, PYI015
-import enum
 from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
 from inspect import Signature
 from typing import (
@@ -16,17 +15,15 @@ from typing import (
 from typing_extensions import Buffer, Self, dataclass_transform
 
 @final
-class UnsetType(enum.Enum):
-    UNSET = "UNSET"
+class UnsetType:
     def __bool__(self) -> Literal[False]: ...
 
-UNSET: Final = UnsetType.UNSET
+UNSET: Final[UnsetType]
 
 @final
-class _NoDefault(enum.Enum):
-    NODEFAULT = "NODEFAULT"
+class _NoDefaultType: ...
 
-NODEFAULT: Final = _NoDefault.NODEFAULT
+NODEFAULT: Final[_NoDefaultType]
 
 class StructConfig(TypedDict, total=False):
     frozen: bool
@@ -59,8 +56,6 @@ class StructMeta(type):
     def __signature__(self) -> Signature: ...
     @property
     def __struct_config__(self) -> StructConfig: ...
-    @property
-    def struct_config(self) -> StructConfig: ...
 
 @dataclass_transform(field_specifiers=("Field",))  # type: ignore
 class Struct(metaclass=StructMeta):
@@ -70,6 +65,7 @@ class Struct(metaclass=StructMeta):
     __struct_alias_fields__: ClassVar[tuple[str, ...]]
     __struct_defaults__: ClassVar[tuple[Any, ...]]
     __match_args__: ClassVar[tuple[str, ...]] = ...
+    __slots__: 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: ...
@@ -78,6 +74,14 @@ class Struct(metaclass=StructMeta):
     def __reduce__(self) -> tuple: ...
     def __replace__(self, **changes: Any) -> Self: ...
     def __iter__(self) -> Iterator[tuple[str, Any]]: ...
+    # Generated only when `struct_config = StructConfig(order=True)`. They are
+    # declared unconditionally because the class-body config dict is invisible
+    # to `@dataclass_transform`. A different struct type is never orderable
+    # against this one, hence `Self`.
+    def __lt__(self, other: Self) -> bool: ...
+    def __le__(self, other: Self) -> bool: ...
+    def __gt__(self, other: Self) -> bool: ...
+    def __ge__(self, other: Self) -> bool: ...
     def struct_dump_json(
         self,
         *,
@@ -122,7 +126,7 @@ _NonNegativeInt: TypeAlias = int
 
 @final
 class Factory:
-    def __new__(cls, factory: Callable[[], Any]) -> Any: ...
+    def __new__(cls, factory: Callable[[], Any], /) -> Any: ...
     factory: Final[Callable[[], Any]]
 
 @final
@@ -157,7 +161,12 @@ class Serializer:
     dump: Final[Callable[[Any], Any] | None]
 
 class Constraint:
-    def __init__(self, fn: Callable[[Any], Any] | None = None) -> None: ...
+    # `_fn` is positional-only and stored privately: it is not part of the
+    # public interface. The callable follows the `Constraint.__call__`
+    # protocol — it receives the value and signals failure by raising, so its
+    # return type is `None`.
+    def __init__(self, fn: Callable[[Any], None] | None = None, /) -> None: ...
+    _fn: Final[Callable[[Any], None] | None]
     def __call__(self, value: Any) -> None: ...
 
 @final
@@ -243,7 +252,7 @@ class CollectionConstraint(Constraint):
 
 @final
 class TimezoneConstraint(Constraint):
-    def __init__(self, *, tz: bool) -> None: ...
+    def __init__(self, tz: bool) -> None: ...
     tz: Final[bool]
 
 class FieldInfo(Struct):

{structtype-0.14.0 → structtype-0.15.0}/src/structtype/_adapter.py

@@ -62,6 +62,22 @@ def _has_constraint_on_union(ann):
     return any(_has_constraint_on_union(arg) for arg in get_args(ann))
 
 
+def _has_constraint(ann):
+    """True if the annotation carries a ``Constraint`` anywhere."""
+    metadata = getattr(ann, "__metadata__", None)
+    if metadata is not None:
+        for meta in metadata:
+            if isinstance(meta, _Constraint):
+                return True
+    supertype = getattr(ann, "__supertype__", None)  # NewType
+    if supertype is not None and _has_constraint(supertype):
+        return True
+    value = getattr(ann, "__value__", None)  # PEP 695 type alias
+    if value is not None and _has_constraint(value):
+        return True
+    return any(_has_constraint(arg) for arg in get_args(ann))
+
+
 class StructAdapter:
     """Adapter for validating and serializing types without subclassing ``Struct``.
 
@@ -101,6 +117,10 @@ class StructAdapter:
                 "for optional fields"
             )
         self._type = type
+        # Validate constraint/type compatibility eagerly, matching `Struct`
+        # class creation, without disturbing the lazy decoder cache below.
+        if _has_constraint(type):
+            _JSONDecoder(type, strict=True)
         self._decoder_loose = None
         self._decoder_strict = None
 

{structtype-0.14.0 → structtype-0.15.0}/src/structtype/_config.py

@@ -7,7 +7,8 @@ class StructConfig(TypedDict, total=False):
 
     Used as a class-body ``struct_config`` attribute. Keys not present inherit
     from the base class; ``__struct_config__`` returns the fully-resolved dict.
-    ``struct_config`` returns exactly what the user wrote (sparse dict).
+    ``struct_config`` returns exactly what the user wrote (sparse dict), and is
+    always present — it defaults to ``{}`` when never declared.
     """
 
     frozen: bool