structtype 0.11.0__tar.gz → 0.12.0__tar.gz

{structtype-0.11.0 → structtype-0.12.0}/AGENTS.md

@@ -3,7 +3,7 @@
 ## Project
 
 Fast struct validation + JSON serialization for Python.
-Core is a monolithic C extension (`src/structtype/_core.c`, ~19K lines).
+Core is a monolithic C extension (`src/structtype/_core.c`, ~21K lines).
 No runtime deps.
 
 ## Setup
@@ -14,7 +14,8 @@ uv sync --frozen
 
 ## Commands
 
-All commands go through `make`.
+Use `make` targets where available. Targeted tests can be run directly with
+`uv run` as shown below.
 
 | Task | Command |
 |---|---|
@@ -22,12 +23,13 @@ All commands go through `make`.
 | Targeted tests | `uv run --reinstall pytest tests/test_json.py -k test_something` |
 | Coverage (Python) | `make test-cov` |
 | Coverage (Python + C) | `make test-cov-c` |
+| Coverage (Python + C, all Pythons, merged) | `make test-cov-c-all` |
 | Tests in all supported Pythons | `make test-all` |
 | Build docs | `make docs` |
 | Format | `make format` |
 | Lint | `make ruff-check` |
 | Type check | `make type-check` |
-| All checks | `make check` |
+| Static checks | `make check` |
 
 ## Conventions
 
@@ -38,16 +40,17 @@ All commands go through `make`.
 - Type stubs (`.pyi`) alongside public modules
 - Sentinel values: `NODEFAULT`, `UNSET`, `_NoDefault`, `UnsetType`
 - never do git commit
+- check for performance regressions, speed is a goal
 
 ## 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.Serializer` — custom-type load/dump codecs
-- `structtype.Raw` — lazy JSON passthrough
+- `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.StructAdapter` — validate and serialize values against arbitrary types
 
 ### Struct Methods
 
@@ -67,7 +70,10 @@ Struct instances support the mapping protocol:
 
 - `make test-cov` reinstalls the C extension before running. `make test-cov-c` builds an `-O0 --coverage` instrumented extension **in place**; afterwards any reinstalling target (`make test`, `make test-cov`) restores the optimized build.
 - C coverage requires `lcov`/`genhtml`; report lands in `htmlcov-c/`.
+- `make check` runs static type and Ruff checks only; it does not run tests,
+  documentation builds, or formatting.
 - Validation matches keys by the **alias** name only, except `struct_validate(obj, from_attributes=True)` on a **non-dict object**, which matches by both the python field name and the alias. Dict/JSON input (even with `from_attributes=True`) and all dump/serialization use only the alias name.
+- For `Annotated[MyType, Serializer(load=...)]`, an existing `MyType` instance bypasses `load`; other Python values and JSON representations are passed to `load`. Serializers remain rejected on `Any`, `bool`, `int`, `float`, `str`, `list`, `dict`, `tuple`, `TypedDict`, `NamedTuple`, `frozendict`, and `Literal`. `Serializer` and `Constraint` must attach to a concrete type inside `Annotated` — `Annotated[Union[A, B], ...]` and `Annotated[Optional[T], ...]` are rejected; use `Annotated[T, ...] | None` for optional fields.
 
 ## graphify
 

{structtype-0.11.0 → structtype-0.12.0}/Makefile

@@ -19,7 +19,7 @@ docs-serve: ## Open built docs in browser
 
 .PHONY: wheels
 wheels: ## build wheels (musllinux skipped; unset CIBW_SKIP or run cibuildwheel directly to include it)
-	CIBW_SKIP='*-musllinux_*' uvx --from cibuildwheel==4.2.0 cibuildwheel
+	CIBW_SKIP='*-musllinux_*' uvx --from cibuildwheel==4.2.1 cibuildwheel
 
 ##@ Quality
 .PHONY: test-cov
@@ -30,11 +30,41 @@ test-cov: ## Run tests with coverage
 test-cov-c: ## Run tests with Python + C coverage (lcov report in htmlcov-c/)
 	rm -rf build coverage-c.info coverage-c.info.* htmlcov-c
 	STRUCTTYPE_COVERAGE=1 uv run --with setuptools python setup.py build_ext --inplace --force
-	./.venv/bin/python -m pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=structtype
-	lcov --capture --directory build --output-file coverage-c.info
-	lcov --extract coverage-c.info "*/src/structtype/*" --output-file coverage-c.info
-	lcov --summary coverage-c.info
-	genhtml coverage-c.info --output-directory htmlcov-c >/dev/null
+	./.venv/bin/python -m pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=structtype \
+	  --deselect tests/test_json.py::TestEncoderMisc::test_encode_infinite_recursive_object_errors
+	lcov --capture --directory build --output-file coverage-c.info --rc branch_coverage=1 --rc geninfo_unexecuted_blocks=1
+	lcov --extract coverage-c.info "*/src/structtype/*" --output-file coverage-c.info --rc branch_coverage=1
+	lcov --summary coverage-c.info --rc branch_coverage=1
+	genhtml coverage-c.info --output-directory htmlcov-c --branch-coverage >/dev/null
+
+# C coverage is version-dependent: `_core.c` has many `#if PY30x_PLUS` and
+# `#ifdef Py_GIL_DISABLED` regions, so a single build only covers part of the
+# code. This target builds an instrumented extension for every supported
+# Python, runs the suite under each, and merges the lcov data.
+.PHONY: test-cov-c-all
+test-cov-c-all: ## Run C coverage across all supported Pythons, merged (htmlcov-c/)
+	rm -rf build coverage-c.info coverage-c.info.* htmlcov-c
+	@set -e; \
+	for py in $(PY_VERSIONS); do \
+	  tag=$$(echo "$$py" | tr -d '.'); \
+	  venv=".venv-cov-$$tag"; \
+	  echo "=== C coverage: $$py ($$venv) ==="; \
+	  rm -rf build; \
+	  env -u VIRTUAL_ENV UV_PROJECT_ENVIRONMENT="$$venv" STRUCTTYPE_COVERAGE=1 \
+	    uv run -p "$$py" --with setuptools python setup.py build_ext --inplace --force; \
+	  "$$venv/bin/python" -m pytest -q \
+	    --deselect tests/test_json.py::TestEncoderMisc::test_encode_infinite_recursive_object_errors; \
+	  lcov --capture --directory build --output-file "coverage-c.info.$$tag" \
+	    --rc branch_coverage=1 --rc geninfo_unexecuted_blocks=1; \
+	  lcov --extract "coverage-c.info.$$tag" "*/src/structtype/*" \
+	    --output-file "coverage-c.info.$$tag" --rc branch_coverage=1; \
+	done; \
+	lcov $$(for f in coverage-c.info.*; do printf ' -a %s' "$$f"; done) \
+	  --output-file coverage-c.info --rc branch_coverage=1; \
+	lcov --summary coverage-c.info --rc branch_coverage=1; \
+	genhtml coverage-c.info --output-directory htmlcov-c --branch-coverage >/dev/null; \
+	env -u VIRTUAL_ENV uv run --reinstall-package structtype python -c "import structtype" >/dev/null; \
+	echo "Merged C coverage written to htmlcov-c/. Re-run 'make test-all' to restore the other optimized builds."
 
 .PHONY: test
 test: ## Run tests in current Python
@@ -71,7 +101,7 @@ DEBUG_VENV = .venv-debug
 .PHONY: test-debug
 test-debug: ## Build core with Py_DEBUG + ASan/UBSan + debug allocator and run all tests
 	uv venv --clear --python $(DEBUG_PY) $(DEBUG_VENV)
-	STRUCTTYPE_SANITIZE=1 uv pip install --python $(DEBUG_VENV) --reinstall --no-cache --group dev -e .
+	STRUCTTYPE_SANITIZE=1 uv pip install --python $(DEBUG_VENV) --reinstall --no-cache --group dev .
 	$(SANITIZE_PRELOAD) STRUCTTYPE_ASAN_RUNTIME=$(ASAN_RUNTIME) ASAN_OPTIONS=detect_leaks=0 \
 		PYTHONMALLOC=debug PYTHONFAULTHANDLER=1 PYTHONDEVMODE=1 \
 		$(DEBUG_VENV)/bin/python -m pytest
@@ -109,6 +139,10 @@ bench: ## run benchmarks
 bench-validators: ## run Serializer/Validator benchmarks
 	uv run -p 3.15 benchmarks/bench_validators.py
 
+.PHONY: bench-codecs
+bench-codecs: ## run Constraint + Serializer heavy benchmarks
+	uv run -p 3.15 benchmarks/bench_codecs.py
+
 ##@ Utility
 .PHONY: clean
 clean: ## Delete all temporary files

{structtype-0.11.0/src/structtype.egg-info → structtype-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structtype
-Version: 0.11.0
+Version: 0.12.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.11.0 → structtype-0.12.0}/src/structtype/_adapter.py

@@ -1,6 +1,9 @@
+import types
+import typing
 from typing import Any, get_args
 
 from ._core import (  # type: ignore
+    Constraint as _Constraint,
     JSONDecoder as _JSONDecoder,
     Serializer as _Serializer,
     _dump,
@@ -27,6 +30,38 @@ def _has_serializer(ann):
     return any(_has_serializer(arg) for arg in get_args(ann))
 
 
+def _is_union(t):
+    """True if ``t`` is ``typing.Union`` or a ``types.UnionType`` (``X | Y``)."""
+    if getattr(t, "__origin__", None) is typing.Union:
+        return True
+    return isinstance(t, types.UnionType)
+
+
+def _has_constraint_on_union(ann):
+    """True if a ``Constraint`` is attached to a union or optional type.
+
+    ``Struct`` rejects this at class creation; ``StructAdapter`` mirrors the
+    same rule at construction.  A concrete member may still be constrained and
+    then made optional, e.g. ``Annotated[T, Constraint(...)] | None``.
+    """
+    metadata = getattr(ann, "__metadata__", None)
+    if metadata is not None:
+        origin = getattr(ann, "__origin__", None)
+        if (
+            origin is not None
+            and _is_union(origin)
+            and any(isinstance(meta, _Constraint) for meta in metadata)
+        ):
+            return True
+    supertype = getattr(ann, "__supertype__", None)  # NewType
+    if supertype is not None and _has_constraint_on_union(supertype):
+        return True
+    value = getattr(ann, "__value__", None)  # PEP 695 type alias
+    if value is not None and _has_constraint_on_union(value):
+        return True
+    return any(_has_constraint_on_union(arg) for arg in get_args(ann))
+
+
 class StructAdapter:
     """Adapter for validating and serializing types without subclassing ``Struct``.
 
@@ -38,6 +73,11 @@ class StructAdapter:
     ``struct_dump`` / ``struct_validate`` protocol methods on the custom type,
     or use a ``Struct``.
 
+    ``Constraint`` annotations are supported on concrete types. A ``Constraint``
+    attached to a union or optional type is rejected at construction, matching
+    ``Struct`` class creation; make the field optional with
+    ``Annotated[T, Constraint(...)] | None``.
+
     >>> from structtype import StructAdapter
     >>> adapter = StructAdapter(list[int])
     >>> adapter.struct_validate_json(b"[1, 2, 3]")
@@ -54,6 +94,12 @@ class StructAdapter:
                 "`struct_validate` methods on the custom type, or use a "
                 "`Struct` instead"
             )
+        if _has_constraint_on_union(type):
+            raise TypeError(
+                "`Constraint` must be applied to a concrete type, not a union "
+                "or optional type; use `Annotated[T, Constraint(...)] | None` "
+                "for optional fields"
+            )
         self._type = type
         self._decoder_loose = None
         self._decoder_strict = None
@@ -66,7 +112,8 @@ class StructAdapter:
         buf : str or bytes
             The JSON message to decode.
         strict : bool, optional
-            If True (default), unmatched fields cause an error.
+            If True (default), use strict type validation and coercion rules.
+            If False, allow the documented lax-mode conversions.
         """
         if strict:
             decoder = self._decoder_strict
@@ -118,9 +165,11 @@ class StructAdapter:
         obj : Any
             A Python object to validate and convert.
         strict : bool, optional
-            If True (default), unmatched fields cause an error.
+            If True (default), use strict type validation and coercion rules.
+            If False, allow the documented lax-mode conversions.
         from_attributes : bool, optional
-            If True, accept objects with attributes instead of dict keys.
+            If True, accept non-dict objects by reading matching attributes.
+            Dict input continues to match fields by serialized alias names.
         """
         return _validate(
             obj,