structtype 0.13.0__tar.gz → 0.15.0__tar.gz

{structtype-0.13.0 → structtype-0.15.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`, ~21K lines).
+Core is a monolithic C extension (`src/structtype/_core.c`, ~22K lines).
 No runtime deps.
 
 ## Setup
@@ -25,28 +25,41 @@ Use `make` targets where available. Targeted tests can be run directly with
 | 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` |
+| Doctests | `make test-doc` |
+| Build sdist + wheel | `make build` |
 | Build docs | `make docs` |
 | Format | `make format` |
 | Lint | `make ruff-check` |
 | Type check | `make type-check` |
 | Static checks | `make check` |
 
+Benchmark targets: `make bench`, `make bench-validators`, `make bench-codecs`,
+`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
 
 - **88-char lines**, formatted with `ruff format`
-- `ruff check` with rules `E`, `F`, `I`, `W`
+- `ruff check` with Ruff's default rule set (the project config sets only
+  `target-version` and isort `combine-as-imports`; line length is enforced by
+  `ruff format`, not `E501`)
 - Private modules/functions prefixed with `_`
 - C code uses `ms_`/`MS_` prefix
 - Type stubs (`.pyi`) alongside public modules
 - 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
@@ -59,6 +72,8 @@ Use `make` targets where available. Targeted tests can be run directly with
 - `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
+- `obj.struct_dump_csv()` — encode one row as `list[str]` for `csv.writer.writerow()`; flat scalar fields only, positional
+- `cls.struct_validate_csv(row, *, null_values=("",))` — decode one CSV row (sequence of cell strings); always lax
 
 ### Dict & Iteration Protocol
 
@@ -75,15 +90,3 @@ Struct instances support the mapping protocol:
 - 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
-
-This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
-
-When the user types `/graphify`, use the installed graphify skill or instructions before doing anything else.
-
-Rules:
-- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
-- Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
-- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
-- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
-- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

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

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

{structtype-0.13.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,21 +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 $(BENCH_PYTHON) benchmarks/bench_strings.py
 
 ##@ Utility
 .PHONY: clean
@@ -161,6 +172,7 @@ clean: ## Delete all temporary files
 	rm -rf htmlcov-c
 	rm -f .coverage
 	rm -f coverage-c.info coverage-c.info.*
+	rm -rf .venv*
 
 .PHONY: install
 install: install-uv ## Install virtual environment
@@ -187,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.13.0 → structtype-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structtype
-Version: 0.13.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.13.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.13.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.13.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