pytypehint 1.2.2__tar.gz → 1.3.0__tar.gz

{pytypehint-1.2.2 → pytypehint-1.3.0}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.3.0 - 2026-11-13
+
+- Add `Struct.encode(instance)` and `Signature.encode(kwargs)`: write a valid
+  value as the portable tree `decode` reads. For a valid value,
+  `schema.build(schema.decode(schema.encode(value)))` returns it with its types,
+  also after a JSON transport.
+- Name union options exactly as `to_dict()` already does for defaults; both now
+  share one writer. The portable format remains `v: 1` and exported documents
+  are unchanged.
+- Encode does not validate. It rejects only what it cannot write: a wrong root
+  type, a value belonging to no option of its slot, a fixed tuple of the wrong
+  length and unknown signature arguments, each with its `path`.
+- The public surface grows by no new names: both are methods on the compiled
+  schemas. Existing operations retain their behavior.
+
+## 1.2.3 - 2026-09-29
+
+### Changed
+
+- Documentation only: the README's Documentation list links each page on the
+  documentation site, so readers on GitHub and PyPI land there. The code is the same as 1.2.2.
+
 ## 1.2.2 - 2026-09-29
 
 ### Changed

{pytypehint-1.2.2 → pytypehint-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pytypehint
-Version: 1.2.2
+Version: 1.3.0
 Summary: Compiles Python type hints into strict, inspectable, portable contracts
 Project-URL: Documentation, https://offerrall.github.io/pytypehint/
 Project-URL: Repository, https://github.com/offerrall/pytypehint
@@ -52,15 +52,16 @@ The full documentation is at https://offerrall.github.io/pytypehint/.
 
 ## Documentation
 
-- [Overview](docs/overview.md): immutable models, portable data, field metadata and the four operations.
-- [Immutable models](docs/immutable.md): the `@immutable` contract, allowed fields, reuse and Python behavior.
-- [Types and API](docs/vocabulary.md): which hints compile to which shapes, and the public API.
-- [Atoms](docs/atoms.md): constraints and notation per shape, file names, layering and extras.
-- [Build](docs/build.md): validating and constructing instances or keyword arguments, union selection and errors.
-- [Resolve](docs/resolve.md): validated dictionaries with defaults filled at the current level.
-- [Decode](docs/decode.md): restoring portable values such as dates, enums and tuples before validation.
-- [Tuples](docs/tuples.md): fixed, variadic and empty tuples and the `Tuple` shape.
-- [Defaults](docs/defaults.md): certification and rematerialization of default values.
-- [Portable contract](docs/contract.md): the JSON-compatible schema document returned by `to_dict()`.
-- [Limits](docs/limits.md): rejected definitions, option identity and runtime limits.
-- [Design](docs/design.md): what the core owns, what consumers own, and why.
+- [Overview](https://offerrall.github.io/pytypehint/): immutable models, portable data, field metadata and the five operations.
+- [Immutable models](https://offerrall.github.io/pytypehint/immutable/): the `@immutable` contract, allowed fields, reuse and Python behavior.
+- [Types and API](https://offerrall.github.io/pytypehint/vocabulary/): which hints compile to which shapes, and the public API.
+- [Atoms](https://offerrall.github.io/pytypehint/atoms/): constraints and notation per shape, file names, layering and extras.
+- [Build](https://offerrall.github.io/pytypehint/build/): validating and constructing instances or keyword arguments, union selection and errors.
+- [Resolve](https://offerrall.github.io/pytypehint/resolve/): validated dictionaries with defaults filled at the current level.
+- [Decode](https://offerrall.github.io/pytypehint/decode/): restoring portable values such as dates, enums and tuples before validation.
+- [Encode](https://offerrall.github.io/pytypehint/encode/): writing valid values as portable data, the inverse of decode.
+- [Tuples](https://offerrall.github.io/pytypehint/tuples/): fixed, variadic and empty tuples and the `Tuple` shape.
+- [Defaults](https://offerrall.github.io/pytypehint/defaults/): certification and rematerialization of default values.
+- [Portable contract](https://offerrall.github.io/pytypehint/contract/): the JSON-compatible schema document returned by `to_dict()`.
+- [Limits](https://offerrall.github.io/pytypehint/limits/): rejected definitions, option identity and runtime limits.
+- [Design](https://offerrall.github.io/pytypehint/design/): what the core owns, what consumers own, and why.

pytypehint-1.3.0/README.md

@@ -0,0 +1,43 @@
+# pytypehint
+
+Define data once with ordinary Python type hints and dataclasses. pytypehint
+compiles them into strict schemas that validate input with exact types and no
+implicit coercion, build nested dataclasses, and export a portable description
+another process can read.
+
+Use `@immutable` for deeply immutable models that validate themselves and reuse
+already validated children. pytypehint is the schema and validation core of
+[func-to-web](https://offerrall.github.io/func-to-web/).
+
+```python
+from dataclasses import dataclass
+from typing import Annotated
+from pytypehint import Min, struct_of
+
+@dataclass
+class Item:
+    name: str
+    quantity: Annotated[int, Min(1)] = 1
+
+schema = struct_of(Item)
+item = schema.build({"name": "Pen"})          # Item(name='Pen', quantity=1)
+schema.build({"name": "Pen", "quantity": 0})  # SchemaValueError: quantity
+```
+
+The full documentation is at https://offerrall.github.io/pytypehint/.
+
+## Documentation
+
+- [Overview](https://offerrall.github.io/pytypehint/): immutable models, portable data, field metadata and the five operations.
+- [Immutable models](https://offerrall.github.io/pytypehint/immutable/): the `@immutable` contract, allowed fields, reuse and Python behavior.
+- [Types and API](https://offerrall.github.io/pytypehint/vocabulary/): which hints compile to which shapes, and the public API.
+- [Atoms](https://offerrall.github.io/pytypehint/atoms/): constraints and notation per shape, file names, layering and extras.
+- [Build](https://offerrall.github.io/pytypehint/build/): validating and constructing instances or keyword arguments, union selection and errors.
+- [Resolve](https://offerrall.github.io/pytypehint/resolve/): validated dictionaries with defaults filled at the current level.
+- [Decode](https://offerrall.github.io/pytypehint/decode/): restoring portable values such as dates, enums and tuples before validation.
+- [Encode](https://offerrall.github.io/pytypehint/encode/): writing valid values as portable data, the inverse of decode.
+- [Tuples](https://offerrall.github.io/pytypehint/tuples/): fixed, variadic and empty tuples and the `Tuple` shape.
+- [Defaults](https://offerrall.github.io/pytypehint/defaults/): certification and rematerialization of default values.
+- [Portable contract](https://offerrall.github.io/pytypehint/contract/): the JSON-compatible schema document returned by `to_dict()`.
+- [Limits](https://offerrall.github.io/pytypehint/limits/): rejected definitions, option identity and runtime limits.
+- [Design](https://offerrall.github.io/pytypehint/design/): what the core owns, what consumers own, and why.

{pytypehint-1.2.2 → pytypehint-1.3.0}/docs/contract.md

@@ -95,7 +95,8 @@ A field default taken from the document round-trips through
 `schema.build(schema.decode(data))`, subject to the author's
 [default purity requirements](defaults.md).
 
-To select an option when writing portable values:
+[`encode`](encode.md) writes any valid value in this spelling. To select an
+option when writing portable values by other means:
 
 | Slot | Encoding |
 |---|---|

{pytypehint-1.2.2 → pytypehint-1.3.0}/docs/decode.md

@@ -16,7 +16,7 @@ booking = schema.build(schema.decode({"day": "2026-08-08"}))
 assert booking.day == date(2026, 8, 8)
 ```
 
-The caller parses JSON text. Decode accepts the resulting plain dictionaries,
+[`encode`](encode.md) is the inverse operation. The caller parses JSON text. Decode accepts the resulting plain dictionaries,
 lists, strings, numbers, booleans and `None`; it does not parse or emit JSON.
 
 | Shape | Restoration |

{pytypehint-1.2.2 → pytypehint-1.3.0}/docs/design.md

@@ -10,7 +10,7 @@ checks requiring files, networks or application state:
 | Task | Responsible layer |
 |---|---|
 | Define ordinary models | Python dataclasses and type hints |
-| Inspect/export schemas, validate values, restore portable types, construct models | pytypehint |
+| Inspect/export schemas, validate values, restore and write portable types, construct models | pytypehint |
 | Parse JSON, coerce form/CLI input, render controls, collect multiple errors | Consumer |
 | Call functions, check files, manage persistence/authentication | Application |
 

pytypehint-1.3.0/docs/encode.md

@@ -0,0 +1,74 @@
+# Encode
+
+`schema.encode(value)` writes a valid value as the portable tree that
+[decode](decode.md) reads. It is the inverse of `decode`:
+
+```python
+from dataclasses import dataclass
+from datetime import date
+from pytypehint import struct_of
+
+@dataclass
+class Booking:
+    day: date
+    guests: int | float = 2
+
+schema = struct_of(Booking)
+booking = Booking(day=date(2026, 8, 8))
+written = schema.encode(booking)
+
+assert written == {"day": "2026-08-08", "guests": {"$type": "int", "$value": 2}}
+assert schema.build(schema.decode(written)) == booking
+```
+
+`Struct.encode` takes an exact instance of its dataclass. `Signature.encode`
+takes a dictionary of arguments, such as the one `build` returns, and writes the
+keys it is given; it fills no defaults and rejects unknown keys.
+
+The result is a new tree of plain dictionaries, lists, strings, numbers, booleans
+and `None`. The caller serializes it, for example with `json.dumps`. The value is
+never modified, and the tree shares no container with it.
+
+| Shape | Written as |
+|---|---|
+| `Date` | `"YYYY-MM-DD"` |
+| `Time` | `"HH:MM:SS"` |
+| `EnumShape` | Member name |
+| `List`, `Tuple` | Array |
+| `Struct` | Object of its fields |
+| Others | The value itself |
+
+## Unions
+
+An option is named exactly where its portable spelling collides with another
+option of the same slot, following the [portable contract](contract.md#values-and-defaults):
+dataclass variants carry an inline `$type`, other colliding options use the
+`$type`/`$value` wrapper, and unambiguous options are written bare. These are the
+spellings `to_dict()` uses for defaults.
+
+Options sharing a Python type, such as `Annotated[list[str], Min(1)] | list[int]`,
+are told apart by the first option that accepts the value.
+
+## Round trip
+
+For a value that passes validation:
+
+```python
+schema.build(schema.decode(schema.encode(value))) == value
+```
+
+The same holds after `json.loads(json.dumps(...))`. Types are preserved: floats
+stay floats, tuples stay tuples and each union value returns to its own option.
+
+## Validation
+
+Encode writes; it does not validate. It checks only what it needs in order to
+write: the root type, that each value belongs to an option of its slot, and
+fixed tuple lengths. Those failures raise `SchemaTypeError` or `SchemaValueError`
+with the field names and indexes of the value in `path`.
+
+A value outside its limits, such as a number below `Min`, is written faithfully,
+and `build` rejects it when the tree is read back. Time fractions and offsets are
+kept in the text for the same reason. Non-finite floats are written as they are
+and have no standard JSON spelling. Cycles and excessive nesting can raise
+`RecursionError`.

{pytypehint-1.2.2 → pytypehint-1.3.0}/docs/immutable.md

@@ -78,6 +78,6 @@ validation cannot undo their external effects. Use ordinary dataclasses and
 Model classes and compiled contracts remain registered for the process lifetime;
 define reusable models rather than generating a new class for each value.
 
-`resolve`, `build`, `decode` and `to_dict` remain available through `struct_of`.
+`resolve`, `build`, `decode`, `encode` and `to_dict` remain available through `struct_of`.
 Their input rules and full recursive validation are unchanged; the reuse shortcut
 belongs only to `@immutable` construction.

{pytypehint-1.2.2 → pytypehint-1.3.0}/docs/overview.md

@@ -61,8 +61,8 @@ see [Immutable models](immutable.md) for the full contract, inheritance and defa
 ## Portable data and inspection
 
 The same models work with the schema API. `decode` restores portable values such
-as JSON arrays and discriminated unions, and `to_dict` describes the schema for a
-UI or another process:
+as JSON arrays and discriminated unions, `encode` writes them back, and `to_dict`
+describes the schema for a UI or another process:
 
 ```python
 from pytypehint import struct_of
@@ -77,6 +77,7 @@ loaded = schema.build(schema.decode({
 }))
 
 assert loaded == original
+assert schema.build(schema.decode(schema.encode(original))) == original
 contract = schema.to_dict()  # Portable description for a UI or another process
 ```
 
@@ -95,11 +96,12 @@ assert size_field.label.value == "Brush size"
 assert size_shape.max.value == 256
 ```
 
-## The four operations
+## The five operations
 
 | Method | Result |
 |---|---|
 | [`build(data)`](build.md) | Dataclass instance; `signature_of(fn)` returns kwargs for `fn(**kwargs)` |
 | [`resolve(data)`](resolve.md) | Validated dictionary with missing defaults filled at this level |
 | [`decode(data)`](decode.md) | Portable values restored to Python types |
+| [`encode(value)`](encode.md) | A valid value written as portable data |
 | [`to_dict()`](contract.md) | Portable schema description |

{pytypehint-1.2.2 → pytypehint-1.3.0}/docs/vocabulary.md

@@ -48,8 +48,8 @@ Everything public is exported from `pytypehint`:
   `Extra`, `OptionalToggle`;
 - `MISSING`.
 
-`Struct` and `Signature` expose the [four operations](overview.md#the-four-operations):
-`.build(data)`, `.resolve(data)`, `.decode(data)` and `.to_dict()`.
+`Struct` and `Signature` expose the [five operations](overview.md#the-five-operations):
+`.build(data)`, `.resolve(data)`, `.decode(data)`, `.encode(value)` and `.to_dict()`.
 `Struct.fields` and `Signature.params` contain `Field` objects; `Field.shape`
 contains the available shapes, and `Field.default` is `MISSING` when no default
 exists. `Shape.option_id()` gives the discriminator identity.

{pytypehint-1.2.2 → pytypehint-1.3.0}/src/pytypehint/__init__.py

@@ -13,7 +13,7 @@ from pytypehint.shapes import (
 )
 from pytypehint.utils import MISSING
 
-__version__ = "1.2.2"
+__version__ = "1.3.0"
 
 __all__ = [
     "immutable",

{pytypehint-1.2.2 → pytypehint-1.3.0}/src/pytypehint/contract.py

@@ -1,12 +1,10 @@
 from datetime import date, time
 
-from pytypehint.errors import SchemaValueError
 from pytypehint.shapes import (
     Bool, Date, EnumShape, Float, Int, List, NoneShape, Str, Time, Tuple,
 )
-from pytypehint.structure import Struct, _TYPE, _VALUE, _portable_options
+from pytypehint.structure import Struct, _encode_options
 from pytypehint.utils import MISSING
-from pytypehint.validation import value_branch
 
 _VERSION = 1
 
@@ -17,43 +15,6 @@ _TYPE_NAMES = {
 }
 
 
-def _portable(shapes, value):
-    shape = value_branch(shapes, value)
-    if shape is None:
-        raise SchemaValueError(
-            f"cannot describe {value!r}: it matches no option of this slot")
-    written = _written(shape, value)
-
-    if type(shape) is Struct:
-        if len([s for s in shapes if type(s) is Struct]) > 1:
-            return {_TYPE: shape.cls.__name__, **written}
-        return written
-
-    if any(option is shape for option in _portable_options(shapes)):
-        return {_TYPE: shape.option_id(), _VALUE: written}
-    return written
-
-
-def _written(shape, value):
-    kind = type(shape)
-    if kind is Date:
-        return value.isoformat()
-    if kind is Time:
-        return value.isoformat(timespec="seconds")
-    if kind is EnumShape:
-        return value.name
-    if kind is List:
-        return [_portable(shape.item, item) for item in value]
-    if kind is Tuple:
-        return [_portable(shape._item_at(i), item) for i, item in enumerate(value)]
-    if kind is Struct:
-        return {f.name: _portable(f.shape, getattr(value, f.name))
-                for f in shape.fields}
-    if kind is Float:
-        return _as_float(value)
-    return value
-
-
 def _as_float(value):
     try:
         restored = float(value)
@@ -234,7 +195,7 @@ def _field_node(f, doc: _Document) -> dict:
     if f.optional_toggle is not None:
         node["optional_toggle"] = f.optional_toggle.enabled
     if f.default is not MISSING:
-        node["default"] = _portable(f.shape, f.default)
+        node["default"] = _encode_options(f.shape, f.default, (f.name, "default"))
     node["shape"] = _slot(f.shape, doc)
     return node
 

{pytypehint-1.2.2 → pytypehint-1.3.0}/src/pytypehint/signature.py

@@ -2,7 +2,7 @@ from dataclasses import dataclass
 
 from pytypehint.contract import _signature_document
 from pytypehint.structure import (
-    Field, _build_kwargs, _decode_fields, _resolve_fields,
+    Field, _build_kwargs, _decode_fields, _encode_fields, _resolve_fields,
 )
 
 
@@ -28,6 +28,9 @@ class Signature:
     def decode(self, kwargs) -> dict:
         return _decode_fields(self.params, kwargs)
 
+    def encode(self, kwargs) -> dict:
+        return _encode_fields(self.params, kwargs, kind="argument")
+
     def resolve(self, kwargs) -> dict:
         return _resolve_fields(self.params, kwargs, kind="argument")
 

{pytypehint-1.2.2 → pytypehint-1.3.0}/src/pytypehint/structure.py

@@ -57,6 +57,12 @@ class Struct(Shape):
     def decode(self, data) -> dict:
         return _decode_fields(self.fields, data)
 
+    def encode(self, instance) -> dict:
+        if type(instance) is not self.cls:
+            raise SchemaTypeError(
+                f"expected {self.cls.__name__}, got {type(instance).__name__}")
+        return _encode_shape(self, instance, ())
+
     def resolve(self, data) -> dict:
         if type(data) is self.cls:
             raise SchemaTypeError(f"expected dict, got {self.cls.__name__} instance")
@@ -430,6 +436,69 @@ def _decode_fields(fields, data) -> dict:
     return decoded
 
 
+# Encode checks only what routing needs; build validates what decode restores.
+def _encode_options(shapes, value, path):
+    shape = value_branch(shapes, value)
+    if shape is None:
+        try:
+            check_options_value(shapes, value)
+        except (TypeError, ValueError) as e:
+            raise _prefixed(e, path) from e
+        raise AssertionError("unrouted value matches an option")
+
+    written = _encode_shape(shape, value, path)
+
+    if type(shape) is Struct:
+        if len([s for s in shapes if type(s) is Struct]) > 1:
+            return {_TYPE: shape.cls.__name__, **written}
+        return written
+
+    if any(option is shape for option in _portable_options(shapes)):
+        return {_TYPE: shape.option_id(), _VALUE: written}
+    return written
+
+
+def _encode_shape(shape, value, path):
+    kind = type(shape)
+    # Keep an invalid fraction or offset in the text for validation to report.
+    if kind in (Date, Time):
+        return value.isoformat()
+    if kind is EnumShape:
+        return value.name
+    if kind is List:
+        return [_encode_options(shape.item, item, (*path, i))
+                for i, item in enumerate(value)]
+    if kind is Tuple:
+        # Length limits are left for build; only a fixed size decides the slots.
+        if not shape.variadic and len(value) != len(shape.items):
+            raise SchemaValueError(
+                f"expected {len(shape.items)} items, got {len(value)}", path)
+        return [_encode_options(shape._item_at(i), item, (*path, i))
+                for i, item in enumerate(value)]
+    if kind is Struct:
+        return {f.name: _encode_options(f.shape, getattr(value, f.name), (*path, f.name))
+                for f in shape.fields}
+    return value
+
+
+def _encode_fields(fields, data, *, kind: str) -> dict:
+    if type(data) is not dict:
+        raise SchemaTypeError(f"expected dict, got {type(data).__name__}")
+
+    invalid_key = next((key for key in data if type(key) is not str), MISSING)
+    if invalid_key is not MISSING:
+        raise SchemaTypeError(
+            f"expected string keys, got {type(invalid_key).__name__}")
+
+    known = {f.name for f in fields}
+    extra = sorted(k for k in data if k not in known)
+    if extra:
+        raise SchemaTypeError(f"unexpected {kind}(s): {', '.join(extra)}")
+
+    return {f.name: _encode_options(f.shape, data[f.name], (f.name,))
+            for f in fields if f.name in data}
+
+
 # Build disables present-value checks after the outer resolve validated them.
 def _resolve_fields(fields, data, *, kind: str, fill: bool = True,
                     check_present: bool = True) -> dict: