structtype 0.8.1__tar.gz → 0.10.0__tar.gz

{structtype-0.8.1 → structtype-0.10.0}/AGENTS.md

@@ -18,9 +18,11 @@ All commands go through `make`.
 
 | Task | Command |
 |---|---|
-| Unit tests (reinstall + last-failed) | `make test-lf` |
+| Unit tests (reinstall + full suite) | `make test` |
 | Targeted tests | `uv run --reinstall pytest tests/test_json.py -k test_something` |
-| Coverage | `make test-cov` |
+| Coverage (Python) | `make test-cov` |
+| Coverage (Python + C) | `make test-cov-c` |
+| Tests in all supported Pythons | `make test-all` |
 | Build docs | `make docs` |
 | Format | `make format` |
 | Lint | `make ruff-check` |
@@ -40,16 +42,18 @@ All commands go through `make`.
 ## Key API
 
 - `structtype.Struct` — base class with config options (frozen, tag, rename, etc.)
-- `structtype.Field` — field constraints (gt, ge, lt, le, min_length, 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.fields(type_or_instance)` — get FieldInfo tuple for a struct type/instance
 - `structtype._inspect.type_info()` / `multi_type_info()` — type introspection
 
 ### Struct Methods
 
-- `obj.struct_dump_json(*, decimal_format=None, uuid_format=None, sort_keys=False)` — serialize to JSON bytes
+- `obj.struct_dump_json(*, decimal_as_number=False, uuid_as_hex=False, sort_keys=False)` — serialize to JSON bytes
 - `obj.struct_dump(*, sort_keys=False, str_keys=False, builtin_types=None)` — convert to built-in Python types (uses `alias` for keys)
-- `obj.struct_validate_self()` — validate field values against types + constraints
+- `obj.struct_check_types()` — validate field values against types + constraints (pure type-check, no conversion)
 - `cls.struct_validate_json(buf, *, strict=True)` — deserialize from JSON
 - `cls.struct_validate(obj, *, strict=True, from_attributes=False)` — convert built-in types to struct
 
@@ -61,7 +65,8 @@ Struct instances support the mapping protocol:
 
 ## Gotchas
 
-- `make test-cov` reinstalls the C extension before running (last-failed first)
+- `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/`.
 - 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.
 
 ## graphify

{structtype-0.8.1 → structtype-0.10.0}/Makefile

@@ -23,12 +23,22 @@ wheels: ## build wheels
 
 ##@ Quality
 .PHONY: test-cov
-test-cov: build ## Run tests with coverage
-	uv run pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=structtype
-
-.PHONY: test-lf
-test-lf: ## Run tests in current Python
-	uv run --reinstall pytest --lf
+test-cov: ## Run tests with coverage
+	uv run --reinstall-package structtype pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=structtype
+
+.PHONY: test-cov-c
+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
+
+.PHONY: test
+test: ## Run tests in current Python
+	uv run --reinstall pytest
 
 .PHONY: test-doc
 test-doc: ## Run doctests
@@ -110,7 +120,9 @@ clean: ## Delete all temporary files
 	rm -rf **/__pycache__
 	rm -rf build
 	rm -rf dist
+	rm -rf htmlcov-c
 	rm -f .coverage
+	rm -f coverage-c.info coverage-c.info.*
 
 .PHONY: install
 install: install-uv ## Install virtual environment

{structtype-0.8.1/src/structtype.egg-info → structtype-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structtype
-Version: 0.8.1
+Version: 0.10.0
 Summary: Fast Struct type with validation and JSON serialization for Python.
 Maintainer-email: Wolfgang Langner <tds333@mailbox.org>
 License-Expression: BSD-3-Clause
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Free Threading
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE

{structtype-0.8.1 → structtype-0.10.0}/pyproject.toml

@@ -16,6 +16,7 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
   "Programming Language :: Python :: 3.15",
+  "Programming Language :: Python :: Free Threading",
 ]
 dependencies = []
 dynamic = ["version"]

{structtype-0.8.1 → structtype-0.10.0}/src/structtype/__init__.py

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

{structtype-0.8.1 → structtype-0.10.0}/src/structtype/__init__.pyi

@@ -37,7 +37,7 @@ class StructConfig(TypedDict, total=False):
     repr_omit_defaults: bool
     omit_defaults: bool
     forbid_unknown_fields: bool
-    validate_on_init: bool
+    check_types_on_init: bool
     weakref: bool
     dict: bool
     cache_hash: bool
@@ -81,10 +81,8 @@ class Struct(metaclass=StructMeta):
     def struct_dump_json(
         self,
         *,
-        decimal_format: Literal["string", "number"]
-        | Callable[[Any], Any]
-        | None = None,
-        uuid_format: Literal["canonical", "hex"] | None = None,
+        decimal_as_number: bool = False,
+        uuid_as_hex: bool = False,
         sort_keys: bool = False,
     ) -> bytes: ...
     def struct_dump(
@@ -94,7 +92,7 @@ class Struct(metaclass=StructMeta):
         str_keys: bool = False,
         builtin_types: Iterable[type] | None = None,
     ) -> dict[str, Any] | list[Any]: ...
-    def struct_validate_self(self) -> None: ...
+    def struct_check_types(self) -> None: ...
     @classmethod
     def struct_validate_json(
         cls,
@@ -160,18 +158,47 @@ class Serializer:
     load: Final[Callable[[Any], Any] | None]
     dump: Final[Callable[[Any], Any] | None]
 
-class Validator:
+class Constraint:
     def __init__(self, fn: Callable[[Any], Any] | None = None) -> None: ...
     def __call__(self, value: Any) -> None: ...
 
 @final
-class NumericValidator(Validator):
+class NumericConstraint(Constraint):
+    # Numeric bounds. You can't mix:
+    # - `gt` and `ge`
+    # - `lt` and `le`
+    # Cross-pair combinations (`gt` with `le`, `ge` with `lt`) are valid,
+    # so all four pairings are enumerated as separate overloads. The C
+    # runtime raises `ValueError` for the invalid pairings.
+    @overload
+    def __init__(
+        self,
+        *,
+        gt: int | float | None = None,
+        lt: int | float | None = None,
+        multiple_of: int | float | None = None,
+    ) -> None: ...
+    @overload
     def __init__(
         self,
         *,
         gt: int | float | None = None,
+        le: int | float | None = None,
+        multiple_of: int | float | None = None,
+    ) -> None: ...
+    @overload
+    def __init__(
+        self,
+        *,
         ge: int | float | None = None,
         lt: int | float | None = None,
+        multiple_of: int | float | None = None,
+    ) -> None: ...
+    @overload
+    def __init__(
+        self,
+        *,
+        ge: int | float | None = None,
         le: int | float | None = None,
         multiple_of: int | float | None = None,
     ) -> None: ...
@@ -182,7 +209,7 @@ class NumericValidator(Validator):
     multiple_of: Final[int | float | None]
 
 @final
-class StrValidator(Validator):
+class StrConstraint(Constraint):
     def __init__(
         self,
         *,
@@ -195,7 +222,7 @@ class StrValidator(Validator):
     max_length: Final[int | None]
 
 @final
-class BytesValidator(Validator):
+class BytesConstraint(Constraint):
     def __init__(
         self,
         *,
@@ -206,7 +233,7 @@ class BytesValidator(Validator):
     max_length: Final[int | None]
 
 @final
-class CollectionValidator(Validator):
+class CollectionConstraint(Constraint):
     def __init__(
         self,
         *,
@@ -217,7 +244,7 @@ class CollectionValidator(Validator):
     max_length: Final[int | None]
 
 @final
-class TimezoneValidator(Validator):
+class TimezoneConstraint(Constraint):
     def __init__(self, *, tz: bool) -> None: ...
     tz: Final[bool]
 
@@ -263,10 +290,8 @@ class StructAdapter:
         self,
         obj: Any,
         *,
-        decimal_format: Literal["string", "number"]
-        | Callable[[Any], Any]
-        | None = None,
-        uuid_format: Literal["canonical", "hex"] | None = None,
+        decimal_as_number: bool = False,
+        uuid_as_hex: bool = False,
         sort_keys: bool = False,
     ) -> bytes: ...
     def struct_validate(

{structtype-0.8.1 → structtype-0.10.0}/src/structtype/_adapter.py

@@ -1,11 +1,13 @@
 from typing import Any, get_args
 
-from ._core import (  # type: ignore
+from ._core import (
+    JSONDecoder as _JSONDecoder,
+)
+from ._core import (
     Serializer as _Serializer,
 )
 from ._core import (  # type: ignore
     _dump,
-    _json_decode,
     _json_encode,
     _validate,
 )
@@ -46,7 +48,7 @@ class StructAdapter:
     [1, 2, 3]
     """
 
-    __slots__ = ("_type",)
+    __slots__ = ("_decoder_loose", "_decoder_strict", "_type")
 
     def __init__(self, type: Any):
         if _has_serializer(type):
@@ -57,6 +59,8 @@ class StructAdapter:
                 "`Struct` instead"
             )
         self._type = type
+        self._decoder_loose = None
+        self._decoder_strict = None
 
     def struct_validate_json(self, buf, *, strict=True):
         """Validate JSON bytes and decode into the adapter's type.
@@ -68,14 +72,24 @@ class StructAdapter:
         strict : bool, optional
             If True (default), unmatched fields cause an error.
         """
-        return _json_decode(buf, type=self._type, strict=strict)
+        if strict:
+            decoder = self._decoder_strict
+            if decoder is None:
+                decoder = _JSONDecoder(self._type, strict=True)
+                self._decoder_strict = decoder
+        else:
+            decoder = self._decoder_loose
+            if decoder is None:
+                decoder = _JSONDecoder(self._type, strict=False)
+                self._decoder_loose = decoder
+        return decoder.decode(buf)
 
     def struct_dump_json(
         self,
         obj,
         *,
-        decimal_format=None,
-        uuid_format=None,
+        decimal_as_number=False,
+        uuid_as_hex=False,
         sort_keys=False,
     ):
         """Encode a validated object to JSON bytes.
@@ -84,17 +98,19 @@ class StructAdapter:
         ----------
         obj : Any
             A value to encode. Must match the adapter's type.
-        decimal_format : str or callable, optional
-            Controls how ``Decimal`` values are encoded.
-        uuid_format : str, optional
-            Controls how ``UUID`` values are encoded.
+        decimal_as_number : bool, optional
+            If True, ``Decimal`` values are encoded as JSON numbers instead
+            of strings (may lose precision when decoded).
+        uuid_as_hex : bool, optional
+            If True, ``UUID`` values are encoded as hex strings instead of
+            canonical form.
         sort_keys : bool, optional
             If True, sort dict keys and set elements for deterministic output.
         """
         return _json_encode(
             obj,
-            decimal_format=decimal_format,
-            uuid_format=uuid_format,
+            decimal_as_number=decimal_as_number,
+            uuid_as_hex=uuid_as_hex,
             sort_keys=sort_keys,
         )
 

{structtype-0.8.1 → structtype-0.10.0}/src/structtype/_config.py

@@ -7,6 +7,7 @@ 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).
     """
 
     frozen: bool
@@ -17,7 +18,7 @@ class StructConfig(TypedDict, total=False):
     array_like: bool
     omit_defaults: bool
     forbid_unknown_fields: bool
-    validate_on_init: bool
+    check_types_on_init: bool
     weakref: bool
     dict: bool
     cache_hash: bool