structtype 0.3.0__tar.gz → 0.5.0__tar.gz

structtype-0.5.0/.opencode/opencode.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ".opencode/plugins/graphify.js"
+  ]
+}

structtype-0.5.0/.opencode/plugins/graphify.js

@@ -0,0 +1,30 @@
+// graphify OpenCode plugin
+// Injects a knowledge graph reminder before bash tool calls when the graph exists.
+//
+// IMPORTANT: keep the reminder string free of backticks and $(...) constructs.
+// The hook prepends `echo "<reminder>" && <cmd>` to the user's bash command;
+// backticks inside the double-quoted echo trigger bash command substitution,
+// which both corrupts tool output and silently executes the very graphify
+// command we are only suggesting. Plain words render fine in opencode's TUI.
+import { existsSync } from "fs";
+import { join } from "path";
+
+export const GraphifyPlugin = async ({ directory }) => {
+  let reminded = false;
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (reminded) return;
+      if (!existsSync(join(directory, "graphify-out", "graph.json"))) return;
+
+      if (input.tool === "bash") {
+        // ';' not '&&' — Windows PowerShell 5.1 rejects '&&' as a statement
+        // separator, breaking the first bash command of the session (#1646).
+        output.args.command =
+          'echo "[graphify] knowledge graph at graphify-out/. For focused questions, run graphify query with your question (scoped subgraph, usually much smaller than GRAPH_REPORT.md) instead of grepping raw files. Read GRAPH_REPORT.md only for broad architecture context." ; ' +
+          output.args.command;
+        reminded = true;
+      }
+    },
+  };
+};

{structtype-0.3.0 → structtype-0.5.0}/AGENTS.md

@@ -19,7 +19,7 @@ All commands go through `make`.
 | Task | Command |
 |---|---|
 | Unit tests (reinstall + last-failed) | `make test-lf` |
-| Targeted tests | `uv run --reinstall pytest tests/unit/test_json.py -k test_something` |
+| Targeted tests | `uv run --reinstall pytest tests/test_json.py -k test_something` |
 | Coverage | `make test-cov` |
 | Build docs | `make docs` |
 | Format | `make format` |
@@ -35,6 +35,7 @@ All commands go through `make`.
 - C code uses `ms_`/`MS_` prefix
 - Type stubs (`.pyi`) alongside public modules
 - Sentinel values: `NODEFAULT`, `UNSET`, `_NoDefault`, `UnsetType`
+- never do git commit
 
 ## Key API
 
@@ -48,7 +49,6 @@ All commands go through `make`.
 
 - `obj.struct_dump_json(*, enc_hook=None, decimal_format=None, uuid_format=None, order=None)` — serialize to JSON bytes
 - `obj.struct_dump()` — convert to built-in Python types (uses `encode_name` for keys)
-- `obj.struct_force_setattr(name, value)` — set attr on frozen struct
 - `obj.struct_validate_self()` — validate field values against types + constraints
 - `cls.struct_validate_json(buf, *, strict=True, dec_hook=None)` — deserialize from JSON
 - `cls.struct_validate(obj, *, strict=True, from_attributes=False, dec_hook=None)` — convert built-in types to struct
@@ -62,3 +62,16 @@ Struct instances support the mapping protocol:
 ## Gotchas
 
 - `make test-lf` reinstalls the C extension before running (last-failed first)
+
+## 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.3.0 → structtype-0.5.0}/Makefile

@@ -13,13 +13,17 @@ docs: ## build docs
 	rm -rf .doctrees site
 	uv run --group docs sphinx-build -d .doctrees -b html docs site --fail-on-warning
 
+.PHONY: docs-serve
+docs-serve: ## Open built docs in browser
+	uv run python -m webbrowser site/index.html
+
 .PHONY: wheels
 wheels: ## build wheels
-	uvx --from cibuildwheel==4.1.1 cibuildwheel
+	uvx --from cibuildwheel==4.2.0 cibuildwheel
 
 ##@ Quality
 .PHONY: test-cov
-test-cov: ## Run tests with coverage
+test-cov: build ## Run tests with coverage
 	uv run pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=structtype
 
 .PHONY: test-lf
@@ -33,9 +37,29 @@ test-doc: ## Run doctests
 .PHONY: test-all
 test-all: ## Run tests in all supporte Python versions
 	for py_v in $(PY_VERSIONS); do \
-		uv run --isolated -p $$py_v pytest; \
+		uv run --isolated --reinstall-package structtype -p $$py_v pytest; \
 	done
 
+UNAME_S := $(shell uname -s)
+ifeq ($(UNAME_S),Darwin)
+ASAN_RUNTIME := $(shell clang --print-file-name=libclang_rt.asan_osx_dynamic.dylib)
+SANITIZE_PRELOAD := DYLD_INSERT_LIBRARIES=$(ASAN_RUNTIME)
+else
+ASAN_RUNTIME := $(shell gcc --print-file-name=libasan.so)
+SANITIZE_PRELOAD := LD_PRELOAD=$(ASAN_RUNTIME)
+endif
+
+DEBUG_PY ?= 3.14+debug
+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 .
+	$(SANITIZE_PRELOAD) STRUCTTYPE_ASAN_RUNTIME=$(ASAN_RUNTIME) ASAN_OPTIONS=detect_leaks=0 \
+		PYTHONMALLOC=debug PYTHONFAULTHANDLER=1 PYTHONDEVMODE=1 \
+		$(DEBUG_VENV)/bin/python -m pytest
+
 .PHONY: check
 check: ## Run all checks
 	-uvx ty check ${SOURCE_DIR}

{structtype-0.3.0 → structtype-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structtype
-Version: 0.3.0
+Version: 0.5.0
 Summary: Fast Struct type with validation and JSON serialization for Python.
 Maintainer-email: Wolfgang Langner <tds333@mailbox.org>
 License-Expression: BSD-3-Clause
@@ -72,7 +72,13 @@ Full documentation is available at **https://tds333.github.io/structtype/**.
 
 ## Benchmarks
 
-structtype is as fast as msgspec and about 3-5x faster than pydantic.
+structtype is as fast as msgspec and about 3-5x faster than pydantic. See the
+[benchmarks page](https://tds333.github.io/structtype/benchmarks.html) for the full numbers.
+
+## Links
+
+- [Changelog](https://tds333.github.io/structtype/changelog.html)
+- [Source code](https://github.com/tds333/structtype)
 
 ## License
 

{structtype-0.3.0 → structtype-0.5.0}/README.md

@@ -49,7 +49,13 @@ Full documentation is available at **https://tds333.github.io/structtype/**.
 
 ## Benchmarks
 
-structtype is as fast as msgspec and about 3-5x faster than pydantic.
+structtype is as fast as msgspec and about 3-5x faster than pydantic. See the
+[benchmarks page](https://tds333.github.io/structtype/benchmarks.html) for the full numbers.
+
+## Links
+
+- [Changelog](https://tds333.github.io/structtype/changelog.html)
+- [Source code](https://github.com/tds333/structtype)
 
 ## License
 

{structtype-0.3.0 → structtype-0.5.0}/pyproject.toml

@@ -84,8 +84,7 @@ editable_mode = "compat"
 [tool.cibuildwheel]
 build = "cp3*"
 skip = ["pp*", "*-manylinux_i686", "*-musllinux*", "*-win32"]
-enable = ["cpython-prerelease"]
 test-command = "pip install pytest>=9 && pytest {project}/tests"
 
 [tool.ruff]
-target-version = "py310"
+target-version = "py310"

{structtype-0.3.0 → structtype-0.5.0}/setup.py

@@ -27,8 +27,15 @@ DEBUG = os.environ.get("STRUCTTYPE_DEBUG", SANITIZE or COVERAGE)
 extra_compile_args = []
 extra_link_args = []
 if SANITIZE:
-    extra_compile_args.extend(["-fsanitize=address", "-fsanitize=undefined"])
-    extra_link_args.extend(["-lasan", "-lubsan"])
+    extra_compile_args.extend(
+        [
+            "-fsanitize=address",
+            "-fsanitize=undefined",
+            "-fsanitize=signed-integer-overflow",
+        ]
+    )
+    if sys.platform != "darwin":
+        extra_link_args.extend(["-lasan", "-lubsan"])
 if COVERAGE:
     extra_compile_args.append("--coverage")
     extra_link_args.append("-lgcov")

{structtype-0.3.0 → structtype-0.5.0}/src/structtype/__init__.py

@@ -1,9 +1,11 @@
 from ._adapter import StrAdapter, StructAdapter
 from ._core import (
+    ALL_BUILTIN_TYPES,
     NODEFAULT,
     UNSET,
     DecodeError,
     EncodeError,
+    Factory,
     Field,
     Raw,
     Struct,

{structtype-0.3.0 → structtype-0.5.0}/src/structtype/__init__.pyi

@@ -68,7 +68,7 @@ class _NoDefault(enum.Enum):
 
 NODEFAULT: Final = _NoDefault.NODEFAULT
 
-@dataclass_transform(field_specifiers=(Field,))
+@dataclass_transform(field_specifiers=("Field",))
 class Struct(metaclass=StructMeta):
     __struct_fields__: ClassVar[tuple[str, ...]]
     __struct_config__: ClassVar[StructConfig]
@@ -110,22 +110,19 @@ class Struct(metaclass=StructMeta):
     def struct_dump_json(
         self,
         *,
-        enc_hook: Callable[[Any], Any] | None = None,
         decimal_format: Literal["string", "number"]
         | Callable[[Any], Any]
         | None = None,
         uuid_format: Literal["canonical", "hex"] | None = None,
-        order: Literal["deterministic", "sorted"] | None = None,
+        sort_keys: bool = False,
     ) -> bytes: ...
     def struct_dump(
         self,
         *,
-        enc_hook: Callable[[Any], Any] | None = None,
-        order: Literal["deterministic", "sorted"] | None = None,
+        sort_keys: bool = False,
         str_keys: bool = False,
         builtin_types: Iterable[type] | None = None,
     ) -> dict[str, Any] | list[Any]: ...
-    def struct_force_setattr(self, name: str, value: Any) -> None: ...
     def struct_validate_self(self) -> None: ...
     @classmethod
     def struct_validate_json(
@@ -133,7 +130,6 @@ class Struct(metaclass=StructMeta):
         buf: str | Buffer,
         *,
         strict: bool = True,
-        dec_hook: Callable[[type[Any], Any], Any] | None = None,
     ) -> _T: ...
     @classmethod
     def struct_validate(
@@ -142,7 +138,6 @@ class Struct(metaclass=StructMeta):
         *,
         strict: bool = True,
         from_attributes: bool = False,
-        dec_hook: Callable[[type[Any], Any], Any] | None = None,
     ) -> _T: ...
 
 # Lie and say `Raw` is a subclass of `bytes`, so mypy will accept it in most
@@ -158,6 +153,11 @@ class Raw(bytes):
 #: We can't represent this in types, only via a name:
 _NonNegativeInt: TypeAlias = int
 
+@final
+class Factory:
+    def __init__(self, factory: Callable[[], Any]) -> None: ...
+    factory: Final[Callable[[], Any]]
+
 @final
 class Field:
     # Numeric:
@@ -168,13 +168,14 @@ class Field:
         gt: int | float | None = None,
         lt: int | float | None = None,
         multiple_of: int | float | None = None,
-        default: Any = NODEFAULT,
-        default_factory: Callable[[], Any] | 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
     def __init__(
@@ -183,13 +184,14 @@ class Field:
         gt: int | float | None = None,
         le: int | float | None = None,
         multiple_of: int | float | None = None,
-        default: Any = NODEFAULT,
-        default_factory: Callable[[], Any] | 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
     def __init__(
@@ -198,13 +200,14 @@ class Field:
         ge: int | float | None = None,
         lt: int | float | None = None,
         multiple_of: int | float | None = None,
-        default: Any = NODEFAULT,
-        default_factory: Callable[[], Any] | 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
     def __init__(
@@ -213,13 +216,14 @@ class Field:
         ge: int | float | None = None,
         le: int | float | None = None,
         multiple_of: int | float | None = None,
-        default: Any = NODEFAULT,
-        default_factory: Callable[[], Any] | 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: ...
     # Other (string/datetime):
     @overload
@@ -230,16 +234,15 @@ class Field:
         min_length: _NonNegativeInt | None = None,
         max_length: _NonNegativeInt | None = None,
         tz: bool | None = None,
-        default: Any = NODEFAULT,
-        default_factory: Callable[[], Any] | 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: ...
-    default: Final[Any]
-    default_factory: Final[Callable[[], Any] | None]
     alias: Final[str | None]
     gt: Final[int | float | None]
     ge: Final[int | float | None]
@@ -253,7 +256,10 @@ class Field:
     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]]: ...
 
 class StructConfig:
@@ -309,33 +315,29 @@ class StructAdapter:
         buf: str | Buffer,
         *,
         strict: bool = True,
-        dec_hook: Callable[[type[Any], Any], Any] | None = None,
     ) -> Any: ...
     def struct_dump_json(
         self,
         obj: Any,
         *,
-        enc_hook: Callable[[Any], Any] | None = None,
         decimal_format: Literal["string", "number"]
         | Callable[[Any], Any]
         | None = None,
         uuid_format: Literal["canonical", "hex"] | None = None,
-        order: Literal["deterministic", "sorted"] | None = None,
+        sort_keys: bool = False,
     ) -> bytes: ...
     def struct_validate(
         self,
         obj: Any,
         *,
         strict: bool = True,
-        dec_hook: Callable[[type[Any], Any], Any] | None = None,
         from_attributes: bool = False,
     ) -> Any: ...
     def struct_dump(
         self,
         obj: Any,
         *,
-        enc_hook: Callable[[Any], Any] | None = None,
-        order: Literal["deterministic", "sorted"] | None = None,
+        sort_keys: bool = False,
         str_keys: bool = False,
         builtin_types: Iterable[type] | None = None,
     ) -> Any: ...
@@ -348,3 +350,5 @@ class DecodeError(ValueError): ...
 class ValidationError(ValueError): ...
 
 __version__: str
+
+ALL_BUILTIN_TYPES: tuple[type, ...]

{structtype-0.3.0 → structtype-0.5.0}/src/structtype/_adapter.py

@@ -1,6 +1,32 @@
-from typing import Any
-
-from ._core import _dump, _json_decode, _json_encode, _validate
+from typing import Any, get_args
+
+from ._core import (  # type: ignore
+    Field as _Field,
+)
+from ._core import (
+    _dump,
+    _json_decode,
+    _json_encode,
+    _validate,
+)
+
+
+def _has_codec(ann):
+    """True if the annotation carries a ``Field`` with ``dump``/``validate``."""
+    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
+            ):
+                return True
+    supertype = getattr(ann, "__supertype__", None)  # NewType
+    if supertype is not None and _has_codec(supertype):
+        return True
+    value = getattr(ann, "__value__", None)  # PEP 695 type alias
+    if value is not None and _has_codec(value):
+        return True
+    return any(_has_codec(arg) for arg in get_args(ann))
 
 
 class StructAdapter:
@@ -9,6 +35,11 @@ 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
+    ``struct_dump`` / ``struct_validate`` protocol methods on the custom type,
+    or use a ``Struct``.
+
     >>> from structtype import StructAdapter
     >>> adapter = StructAdapter(list[int])
     >>> adapter.struct_validate_json(b"[1, 2, 3]")
@@ -18,9 +49,15 @@ class StructAdapter:
     __slots__ = ("_type",)
 
     def __init__(self, type: Any):
+        if _has_codec(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"
+            )
         self._type = type
 
-    def struct_validate_json(self, buf, *, strict=True, dec_hook=None):
+    def struct_validate_json(self, buf, *, strict=True):
         """Validate JSON bytes and decode into the adapter's type.
 
         Parameters
@@ -29,13 +66,16 @@ class StructAdapter:
             The JSON message to decode.
         strict : bool, optional
             If True (default), unmatched fields cause an error.
-        dec_hook : callable, optional
-            A callback for customizing decoding of specific types.
         """
-        return _json_decode(buf, type=self._type, strict=strict, dec_hook=dec_hook)
+        return _json_decode(buf, type=self._type, strict=strict)
 
     def struct_dump_json(
-        self, obj, *, enc_hook=None, decimal_format=None, uuid_format=None, order=None
+        self,
+        obj,
+        *,
+        decimal_format=None,
+        uuid_format=None,
+        sort_keys=False,
     ):
         """Encode a validated object to JSON bytes.
 
@@ -43,26 +83,21 @@ class StructAdapter:
         ----------
         obj : Any
             A value to encode. Must match the adapter's type.
-        enc_hook : callable, optional
-            A callback for customizing encoding of specific types.
         decimal_format : str or callable, optional
             Controls how ``Decimal`` values are encoded.
         uuid_format : str, optional
             Controls how ``UUID`` values are encoded.
-        order : str, optional
-            Determines key ordering in JSON objects.
+        sort_keys : bool, optional
+            If True, sort dict keys and set elements for deterministic output.
         """
         return _json_encode(
             obj,
-            enc_hook=enc_hook,
             decimal_format=decimal_format,
             uuid_format=uuid_format,
-            order=order,
+            sort_keys=sort_keys,
         )
 
-    def struct_validate(
-        self, obj, *, strict=True, dec_hook=None, from_attributes=False
-    ):
+    def struct_validate(self, obj, *, strict=True, from_attributes=False):
         """Validate a Python object against the adapter's type.
 
         Parameters
@@ -71,8 +106,6 @@ class StructAdapter:
             A Python object to validate and convert.
         strict : bool, optional
             If True (default), unmatched fields cause an error.
-        dec_hook : callable, optional
-            A callback for customizing decoding of specific types.
         from_attributes : bool, optional
             If True, accept objects with attributes instead of dict keys.
         """
@@ -80,20 +113,23 @@ class StructAdapter:
             obj,
             self._type,
             strict=strict,
-            dec_hook=dec_hook,
             from_attributes=from_attributes,
         )
 
     def struct_dump(
-        self, obj, *, enc_hook=None, order=None, str_keys=False, builtin_types=None
+        self,
+        obj,
+        *,
+        sort_keys=False,
+        str_keys=False,
+        builtin_types=None,
     ):
         """Convert a validated object to built-in Python types (``dict``, ``list``, etc.)."""
         return _dump(
             obj,
             builtin_types=builtin_types,
             str_keys=str_keys,
-            enc_hook=enc_hook,
-            order=order,
+            sort_keys=sort_keys,
         )