structtype 0.1.0__tar.gz → 0.2.0__tar.gz

{structtype-0.1.0 → structtype-0.2.0}/AGENTS.md

@@ -41,22 +41,24 @@ All commands go through `make`.
 - `structtype.Struct` — base class with config options (frozen, tag, rename, etc.)
 - `structtype.Field` — field constraints (gt, ge, lt, le, min_length, etc.)
 - `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()` — serialize to JSON bytes
-- `obj.struct_dump()` — convert to built-in Python types
-- `obj.struct_to_dict()` — shallow field dict
-- `obj.struct_to_tuple()` — shallow field tuple
+- `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_check()` — validate field values against types + constraints
-- `cls.struct_validate_json(buf)` — deserialize from JSON
-- `cls.struct_validate_jsonln(buf)` — deserialize newline-delimited JSON to a list of structs
-- `cls.struct_dump_jsonln(items)` — serialize a list of structs as newline-delimited JSON
-- `cls.struct_validate(obj)` — convert built-in types to struct
+- `obj.struct_validate_self(*, strict=True, dec_hook=None)` — 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
+
+### Dict & Iteration Protocol
+
+Struct instances support the mapping protocol:
+- `dict(p)` — shallow dict of Python field names to values (iterates `(name, value)` pairs)
+- `list(p)` / `iter(p)` — iterate `(name, value)` 2-tuples in declaration order
 
 ## Gotchas
 
-- `pytest-randomly` shuffles test order
 - `make test-lf` reinstalls the C extension before running (last-failed first)

{structtype-0.1.0 → structtype-0.2.0}/Makefile

@@ -22,6 +22,10 @@ test-cov: ## Run tests with coverage
 test-lf: ## Run tests in current Python
 	uv run --reinstall pytest --lf
 
+.PHONY: test-doc
+test-doc: ## Run doctests
+	uv run pytest --doctest-modules --pyargs structtype
+
 .PHONY: test-all
 test-all: ## Run tests in all supporte Python versions
 	for py_v in $(PY_VERSIONS); do \
@@ -49,8 +53,7 @@ format: ## Format files using ruff format
 ##@ Benchmark
 .PHONY: bench
 bench: ## run benchmarks
-	uv run --group bench benchmarks/bench_compare.py
-	uv run --group bench benchmarks/bench_libs.py
+	uv run benchmarks/bench_libs.py
 
 ##@ Utility
 .PHONY: clean

{structtype-0.1.0/src/structtype.egg-info → structtype-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structtype
-Version: 0.1.0
+Version: 0.2.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.1.0 → structtype-0.2.0}/pyproject.toml

@@ -46,17 +46,6 @@ dev = [
   "pytest>=9",
   "pytest-coverage>=0.0",
 ]
-bench = [
-  "cattrs==25.3.0",
-  "mashumaro==3.17",
-  "msgspec",
-  "orjson==3.11.4",
-  "pydantic==2.12.4",
-  "pysimdjson==7.0.2",
-  "python-rapidjson==1.22",
-  "requests",
-  "ujson==5.11.0",
-]
 docs = [
   "furo",
   "ipython",
@@ -65,11 +54,6 @@ docs = [
   "sphinx-copybutton",
   "sphinx-design",
 ]
-hooks = [
-  "codespell==2.4.1",
-  "prek>=0.2.13",
-  "ruff==0.15.16",
-]
 
 [build-system]
 requires = [

{structtype-0.1.0 → structtype-0.2.0}/src/structtype/__init__.py

@@ -11,7 +11,7 @@ from ._core import (
     UnsetType,
     ValidationError,
 )
-from ._adapter import StructAdapter
+from ._adapter import StrAdapter, StructAdapter
 from ._inspect import FieldInfo, fields
 from ._json_schema import json_schema, json_schema_dump, json_schema_components
 from ._version import __version__

{structtype-0.1.0 → structtype-0.2.0}/src/structtype/__init__.pyi

@@ -1,5 +1,5 @@
 import enum
-from collections.abc import Callable, Iterable, Mapping
+from collections.abc import Callable, Iterable, Iterator, Mapping
 from inspect import Signature
 from typing import (
     Any,
@@ -115,6 +115,7 @@ class Struct(metaclass=StructMeta):
     ) -> None: ...
     def __rich_repr__(self) -> list[tuple[str, Any]]: ...
     def __replace__(self, **changes: Any) -> Self: ...
+    def __iter__(self) -> Iterator[tuple[str, Any]]: ...
     def struct_dump_json(
         self,
         *,
@@ -124,10 +125,8 @@ class Struct(metaclass=StructMeta):
         order: Literal["deterministic", "sorted"] | None = None,
     ) -> bytes: ...
     def struct_dump(self) -> dict[str, Any]: ...
-    def struct_to_dict(self) -> dict[str, Any]: ...
-    def struct_to_tuple(self) -> tuple[Any, ...]: ...
     def struct_force_setattr(self, name: str, value: Any) -> None: ...
-    def struct_check(
+    def struct_validate_self(
         self,
         *,
         strict: bool = True,
@@ -150,24 +149,6 @@ class Struct(metaclass=StructMeta):
         from_attributes: bool = False,
         dec_hook: Callable[[type[Any], Any], Any] | None = None,
     ) -> _T: ...
-    @classmethod
-    def struct_validate_jsonln(
-        cls: type[_T],
-        buf: str | Buffer,
-        *,
-        strict: bool = True,
-        dec_hook: Callable[[type[Any], Any], Any] | None = None,
-    ) -> list[_T]: ...
-    @classmethod
-    def struct_dump_jsonln(
-        cls,
-        items: Iterable[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,
-    ) -> bytes: ...
 
 # Lie and say `Raw` is a subclass of `bytes`, so mypy will accept it in most
 # places where an object that implements the buffer protocol is valid
@@ -354,6 +335,9 @@ class StructAdapter:
     ) -> Any: ...
     def struct_dump(self, obj: Any) -> Any: ...
 
+class StrAdapter:
+    def __new__(cls, type: type[Any]) -> type[str]: ...
+
 class EncodeError(ValueError): ...
 class DecodeError(ValueError): ...
 class ValidationError(ValueError): ...

structtype-0.2.0/src/structtype/_adapter.py

@@ -0,0 +1,112 @@
+from typing import Any
+
+from ._core import _convert, json_decode, json_encode
+
+
+class StructAdapter:
+    """Adapter for validating and serializing types without subclassing ``Struct``.
+
+    Useful when you want to validate or serialize plain Python types
+    (e.g. ``list[int]``) without defining a full ``Struct`` subclass.
+
+    >>> from structtype import StructAdapter
+    >>> adapter = StructAdapter(list[int])
+    >>> adapter.struct_validate_json(b"[1, 2, 3]")
+    [1, 2, 3]
+    """
+
+    __slots__ = ("_type",)
+
+    def __init__(self, type: Any):
+        self._type = type
+
+    def struct_validate_json(self, buf, *, strict=True, dec_hook=None):
+        """Validate JSON bytes and decode into the adapter's type.
+
+        Parameters
+        ----------
+        buf : str or bytes
+            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)
+
+    def struct_dump_json(self, obj, *, enc_hook=None, decimal_format=None, uuid_format=None, order=None):
+        """Encode a validated object to JSON bytes.
+
+        Parameters
+        ----------
+        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.
+        """
+        return json_encode(obj, enc_hook=enc_hook, decimal_format=decimal_format, uuid_format=uuid_format, order=order)
+
+    def struct_validate(
+        self, obj, *, strict=True, dec_hook=None, from_attributes=False
+    ):
+        """Validate a Python object against the adapter's type.
+
+        Parameters
+        ----------
+        obj : Any
+            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.
+        """
+        return _convert(
+            obj,
+            self._type,
+            strict=strict,
+            dec_hook=dec_hook,
+            from_attributes=from_attributes,
+        )
+
+    def struct_dump(self, obj):
+        """Convert a validated object to built-in Python types (``dict``, ``list``, etc.)."""
+        if hasattr(obj, "struct_dump"):
+            return obj.struct_dump()
+        if hasattr(obj, "model_dump"):
+            return obj.model_dump()
+        return obj
+
+
+class StrAdapter:
+    """Create a ``str`` subclass wrapper for validating a type during
+    structtype serialization.
+
+    Wraps a type that has a single-argument string constructor
+    (e.g. ``HttpUrl``, ``EmailStr``, ``IPv4Address``) into a ``str``
+    subclass. The wrapped value is stored as a string but validated by
+    calling ``typ(value)`` on construction. During structtype
+    validation and serialization, the wrapper is treated as a native
+    ``str``.
+
+    >>> from structtype import StrAdapter, Struct
+    >>> from ipaddress import IPv4Address
+    >>>
+    >>> class Config(Struct):
+    ...     ip: StrAdapter(IPv4Address)
+    """
+
+    __slots__ = ()
+
+    def __new__(cls, typ):
+        return type(f"_Wrapped_{typ.__name__}", (str,), {
+            "__slots__": (),
+            "__new__": lambda self, v: str.__new__(self, str(typ(v))),
+        })