pytypehint 0.0.1__tar.gz

pytypehint-0.0.1/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

pytypehint-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv pip install --system -e ".[dev]"
+      - run: mypy src
+      - run: pytest

pytypehint-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv pip install --system -e ".[dev]"
+      - run: mypy src
+      - run: pytest
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

pytypehint-0.0.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.vscode/
+.idea/

pytypehint-0.0.1/.hypothesis/.gitignore

@@ -0,0 +1,9 @@
+# This .gitignore file was automatically created by Hypothesis. Hypothesis gitignores
+# .hypothesis by default, because we generally recommend that .hypothesis not be checked
+# into version control.
+#
+# If you *would* like to check .hypothesis into version control, you should delete this
+# file. Hypothesis will not re-create this .gitignore unless .hypothesis is deleted (and
+# if it does, that's a bug - please report it!)
+
+*

pytypehint-0.0.1/.hypothesis/constants/2678b14aa369a75b

@@ -0,0 +1,4 @@
+# file: /home/runner/work/pytypehint/pytypehint/src/pytypehint/signature.py
+# hypothesis_version: 6.156.6
+
+['argument']

pytypehint-0.0.1/.hypothesis/constants/394532c786c7fa39

@@ -0,0 +1,4 @@
+# file: /opt/hostedtoolcache/Python/3.11.15/x64/bin/pytest
+# hypothesis_version: 6.156.6
+
+['-script.pyw', '.exe', '__main__']

pytypehint-0.0.1/.hypothesis/constants/417463f20a0e2f4a

@@ -0,0 +1,4 @@
+# file: /home/runner/work/pytypehint/pytypehint/src/pytypehint/errors.py
+# hypothesis_version: 6.156.6
+
+[]

pytypehint-0.0.1/.hypothesis/constants/7ea8177d35d3f469

@@ -0,0 +1,4 @@
+# file: /home/runner/work/pytypehint/pytypehint/src/pytypehint/shapes.py
+# hypothesis_version: 6.156.6
+
+['_compiled', 'choices', 'extra', 'is_password', 'is_path_file', 'max', 'min', 'multiple_of', 'pattern', 'placeholder', 'pytype', 'rows', 'slider', 'step']

pytypehint-0.0.1/.hypothesis/constants/9260f428ce0a0a9c

@@ -0,0 +1,4 @@
+# file: /home/runner/work/pytypehint/pytypehint/src/pytypehint/validation.py
+# hypothesis_version: 6.156.6
+
+[' | ']

pytypehint-0.0.1/.hypothesis/constants/ad3acb7981ed8c4e

@@ -0,0 +1,4 @@
+# file: /home/runner/work/pytypehint/pytypehint/src/pytypehint/utils.py
+# hypothesis_version: 6.156.6
+
+['MISSING']

pytypehint-0.0.1/.hypothesis/constants/b60ecb6f6243dd23

@@ -0,0 +1,4 @@
+# file: /home/runner/work/pytypehint/pytypehint/src/pytypehint/atoms.py
+# hypothesis_version: 6.156.6
+
+['.']

pytypehint-0.0.1/.hypothesis/constants/be68644653efe775

@@ -0,0 +1,4 @@
+# file: /home/runner/work/pytypehint/pytypehint/src/pytypehint/structure.py
+# hypothesis_version: 6.156.6
+
+[' | ', '$type', 'Field', 'Struct(<incomplete>)', '_deferred', '_recipe', 'cls', 'default', 'description', 'fields', 'key', 'label', 'optional_toggle', 'tuple[Field, ...]']

pytypehint-0.0.1/.hypothesis/constants/edf98ac0cc5cb0cb

@@ -0,0 +1,4 @@
+# file: /home/runner/work/pytypehint/pytypehint/src/pytypehint/__init__.py
+# hypothesis_version: 6.156.6
+
+['0.0.1', 'Bool', 'Choices', 'Date', 'Description', 'EnumShape', 'Extra', 'Field', 'Float', 'Int', 'IsPassword', 'IsPathFile', 'Label', 'List', 'MISSING', 'Max', 'Min', 'MultipleOf', 'NoneShape', 'OptionalToggle', 'Pattern', 'Placeholder', 'Rows', 'SchemaTypeError', 'SchemaValueError', 'Shape', 'Signature', 'Slider', 'Step', 'Str', 'Struct', 'Time', 'signature_of', 'struct_of']

pytypehint-0.0.1/.hypothesis/constants/f49b7bbd9251f442

@@ -0,0 +1,4 @@
+# file: /home/runner/work/pytypehint/pytypehint/src/pytypehint/bridge.py
+# hypothesis_version: 6.156.6
+
+['<lambda>', '_deferred', 'cls', 'dataclass', 'default', 'enum', 'fields', 'list', 'self', 'typing.']

pytypehint-0.0.1/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.0.1] - 2026-07-15
+
+- Initial release.

pytypehint-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beltrán Offerrall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytypehint-0.0.1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: pytypehint
+Version: 0.0.1
+Summary: Compiles Python type hints into strict, inspectable schemas
+Author: Beltrán Offerrall
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pytypehint
+
+[![PyPI](https://img.shields.io/pypi/v/pytypehint.svg)](https://pypi.org/project/pytypehint/)
+
+`pytypehint` compiles Python type hints into strict, inspectable schemas. A
+hint carries everything there is to know about a field — its type, its limits,
+and its presentation — so the dataclass is the single source of truth: the
+core validates plain input data, fills fresh defaults and constructs dataclass
+instances; wrapper authors read the same schema to render controls, coerce
+external input and execute functions themselves. What the core hands them is
+raw, inspectable structure, never an opinion about it: interpretive
+conveniences belong to wrappers and to intermediate packages built on the core.
+Stdlib only; Python 3.11+; `py.typed` included.
+
+```bash
+pip install pytypehint
+```
+
+```python
+from dataclasses import dataclass, field
+from typing import Annotated
+from pytypehint import Label, Max, Min, signature_of, struct_of
+
+@dataclass(frozen=True)
+class Page:
+    number: Annotated[int, Min(1)] = 1
+    size: Annotated[int, Min(1), Max(100), Label("Page size")] = 20
+
+@dataclass
+class Search:
+    query: str
+    page: Page = Page()
+    tags: list[str] = field(default_factory=list)
+
+value = struct_of(Search).build({"query": "python", "page": {"size": 50}})
+# Search(query='python', page=Page(number=1, size=50), tags=[])
+
+try:
+    struct_of(Search).build({"query": "python", "page": {"size": 500}})
+except ValueError as error:
+    assert str(error) == "page: size: too large: 500, maximum 100"
+
+def search(query: str, page: Page = Page()): ...
+kwargs = signature_of(search).build({"query": "python"})
+search(**kwargs)  # execution belongs to the caller
+```
+
+## Guarantees
+
+- Exact types: `type(value) is T`; the core never coerces.
+- Data enters as dictionaries and lists; dataclass instances leave through `build`.
+- Defaults are certified at compilation and rematerialized fresh per missing key.
+- Invalid constraints fail while compiling the schema.
+- Errors retain the complete field and list-index path, as the message text and
+  as data: `SchemaTypeError` and `SchemaValueError` carry `path` and `leaf`, and
+  subclass `TypeError` and `ValueError`.
+- Notation atoms are stored and cross-checked but never affect validation;
+  presentation belongs to the wrapper.
+- `Struct`, `Field` and `Signature` compare by identity; compile once and share.
+- `build` validates the input once and constructs directly; the cost is linear.
+- `resolve` validates and fills defaults without constructing nested dictionaries.
+- `Signature.build` returns constructed keyword arguments and never invokes the function.
+
+## Vocabulary
+
+| Hint | Shape | Input |
+|---|---|---|
+| `int` | `Int` | exact `int` |
+| `float` | `Float` | exact `float` |
+| `str` | `Str` | exact `str` |
+| `bool` | `Bool` | exact `bool` |
+| `date` | `Date` | exact `datetime.date` |
+| `time` | `Time` | exact naive `datetime.time` |
+| `Enum` subclass | `EnumShape` | exact member type |
+| `None` | `NoneShape` | `None` |
+| `list[X]` | `List` | list; nesting and union items supported |
+| dataclass | `Struct` | dictionary; `build` constructs it |
+| `A \| B` | tuple of shapes | exact scalar type or routed dataclass dictionary |
+| `Literal[...]` | `Int` or `Str` with `Choices` | homogeneous `int` or `str` literals |
+
+## Public API
+
+Everything public is exported from `pytypehint`:
+
+- `struct_of`, `signature_of`;
+- `Struct`, `Field`, `Signature`;
+- errors: `SchemaTypeError`, `SchemaValueError`;
+- `Shape`, `Int`, `Float`, `Str`, `Bool`, `Date`, `Time`, `List`,
+  `NoneShape`, `EnumShape`;
+- limits: `Min`, `Max`, `Choices`, `MultipleOf`, `Pattern`, `IsPathFile`;
+- notation: `Label`, `Description`, `Placeholder`, `Step`, `Slider`,
+  `IsPassword`, `Rows`, `Extra`, `OptionalToggle`;
+- `MISSING`.
+
+Start with [the design principles](docs/philosophy.md), then read
+[build](docs/build.md), [resolve](docs/resolve.md), [defaults](docs/defaults.md),
+[vocabulary](docs/vocabulary.md), [atoms](docs/atoms.md),
+[restrictions](docs/restrictions.md), and [comparison](docs/comparison.md).

pytypehint-0.0.1/README.md

@@ -0,0 +1,98 @@
+# pytypehint
+
+[![PyPI](https://img.shields.io/pypi/v/pytypehint.svg)](https://pypi.org/project/pytypehint/)
+
+`pytypehint` compiles Python type hints into strict, inspectable schemas. A
+hint carries everything there is to know about a field — its type, its limits,
+and its presentation — so the dataclass is the single source of truth: the
+core validates plain input data, fills fresh defaults and constructs dataclass
+instances; wrapper authors read the same schema to render controls, coerce
+external input and execute functions themselves. What the core hands them is
+raw, inspectable structure, never an opinion about it: interpretive
+conveniences belong to wrappers and to intermediate packages built on the core.
+Stdlib only; Python 3.11+; `py.typed` included.
+
+```bash
+pip install pytypehint
+```
+
+```python
+from dataclasses import dataclass, field
+from typing import Annotated
+from pytypehint import Label, Max, Min, signature_of, struct_of
+
+@dataclass(frozen=True)
+class Page:
+    number: Annotated[int, Min(1)] = 1
+    size: Annotated[int, Min(1), Max(100), Label("Page size")] = 20
+
+@dataclass
+class Search:
+    query: str
+    page: Page = Page()
+    tags: list[str] = field(default_factory=list)
+
+value = struct_of(Search).build({"query": "python", "page": {"size": 50}})
+# Search(query='python', page=Page(number=1, size=50), tags=[])
+
+try:
+    struct_of(Search).build({"query": "python", "page": {"size": 500}})
+except ValueError as error:
+    assert str(error) == "page: size: too large: 500, maximum 100"
+
+def search(query: str, page: Page = Page()): ...
+kwargs = signature_of(search).build({"query": "python"})
+search(**kwargs)  # execution belongs to the caller
+```
+
+## Guarantees
+
+- Exact types: `type(value) is T`; the core never coerces.
+- Data enters as dictionaries and lists; dataclass instances leave through `build`.
+- Defaults are certified at compilation and rematerialized fresh per missing key.
+- Invalid constraints fail while compiling the schema.
+- Errors retain the complete field and list-index path, as the message text and
+  as data: `SchemaTypeError` and `SchemaValueError` carry `path` and `leaf`, and
+  subclass `TypeError` and `ValueError`.
+- Notation atoms are stored and cross-checked but never affect validation;
+  presentation belongs to the wrapper.
+- `Struct`, `Field` and `Signature` compare by identity; compile once and share.
+- `build` validates the input once and constructs directly; the cost is linear.
+- `resolve` validates and fills defaults without constructing nested dictionaries.
+- `Signature.build` returns constructed keyword arguments and never invokes the function.
+
+## Vocabulary
+
+| Hint | Shape | Input |
+|---|---|---|
+| `int` | `Int` | exact `int` |
+| `float` | `Float` | exact `float` |
+| `str` | `Str` | exact `str` |
+| `bool` | `Bool` | exact `bool` |
+| `date` | `Date` | exact `datetime.date` |
+| `time` | `Time` | exact naive `datetime.time` |
+| `Enum` subclass | `EnumShape` | exact member type |
+| `None` | `NoneShape` | `None` |
+| `list[X]` | `List` | list; nesting and union items supported |
+| dataclass | `Struct` | dictionary; `build` constructs it |
+| `A \| B` | tuple of shapes | exact scalar type or routed dataclass dictionary |
+| `Literal[...]` | `Int` or `Str` with `Choices` | homogeneous `int` or `str` literals |
+
+## Public API
+
+Everything public is exported from `pytypehint`:
+
+- `struct_of`, `signature_of`;
+- `Struct`, `Field`, `Signature`;
+- errors: `SchemaTypeError`, `SchemaValueError`;
+- `Shape`, `Int`, `Float`, `Str`, `Bool`, `Date`, `Time`, `List`,
+  `NoneShape`, `EnumShape`;
+- limits: `Min`, `Max`, `Choices`, `MultipleOf`, `Pattern`, `IsPathFile`;
+- notation: `Label`, `Description`, `Placeholder`, `Step`, `Slider`,
+  `IsPassword`, `Rows`, `Extra`, `OptionalToggle`;
+- `MISSING`.
+
+Start with [the design principles](docs/philosophy.md), then read
+[build](docs/build.md), [resolve](docs/resolve.md), [defaults](docs/defaults.md),
+[vocabulary](docs/vocabulary.md), [atoms](docs/atoms.md),
+[restrictions](docs/restrictions.md), and [comparison](docs/comparison.md).

pytypehint-0.0.1/docs/atoms.md

@@ -0,0 +1,80 @@
+# Atoms
+
+Atoms are frozen values inside `Annotated`. Limits affect validation; notation
+is stored for wrappers and ignored by validation.
+
+| Shape | Accepted atoms |
+|---|---|
+| `Int` | `Min`, `Max`, `Choices`, `MultipleOf`, `Step`, `Slider`, `Placeholder`, `Extra` |
+| `Float` | `Min`, `Max`, `Choices`, `Step`, `Slider`, `Placeholder`, `Extra` |
+| `Str` | `Min`, `Max`, `Choices`, `Pattern`, `IsPathFile`, `IsPassword`, `Rows`, `Placeholder`, `Extra` |
+| `Date`, `Time` | `Min`, `Max`, `Choices`, `Placeholder`, `Extra` |
+| `List` | `Min`, `Max` for length, `Extra` |
+| `Bool`, `NoneShape` | `Extra` |
+| `EnumShape`, dataclass (`Struct`) | none; annotate struct fields, not nesting |
+| any field | `Label`, `Description` |
+| optional field (`X \| None`) | `OptionalToggle` |
+
+## Atoms
+
+`Min(value, *, exclusive=False)` and `Max(...)` set lower and upper bounds.
+On strings and lists they constrain length and cannot be exclusive.
+
+`Choices(values=(...))` requires a non-empty tuple of unique, hashable values.
+Choices must have the shape's exact type and satisfy its other limits.
+
+`MultipleOf(value)` accepts a positive integer and applies only to `Int`.
+Integer-only divisibility avoids floating-point ambiguity.
+
+`Pattern(regex, *, message=None)` applies a full regular-expression match to
+`Str`. A custom message replaces the standard mismatch message.
+
+`Step(value)` is positive numeric wrapper notation. `Slider(show_value=True)`
+is notation for numeric fields and requires both `Min` and `Max`.
+
+`Placeholder(text)` is non-empty wrapper notation for scalar inputs.
+`IsPassword()` and `Rows(n)` are string notation; rows must be positive.
+
+`Extra(text)` is opaque, non-empty wrapper notation. The core stores it and
+never interprets it; layering follows the standard rule.
+
+`IsPathFile(extensions=(...))` marks a string as a path input. Extensions are
+lowercase dotted suffixes; validation checks the suffix, never file existence.
+
+`Label(text)` and `Description(text)` are non-empty field-level notation.
+
+`OptionalToggle(enabled)` is field-level notation for `X | None`. `True` starts
+a wrapper toggle on, `False` starts it off, and absence leaves the choice to the
+wrapper. It never changes resolution or defaults.
+
+## Compile-time cross-checks
+
+The schema rejects empty ranges; choices outside bounds or failing pattern,
+multiple or extension rules; ranges containing no valid multiple; sliders
+without both bounds; wrong bound types; and `OptionalToggle` on a non-optional
+field. These contradictions fail during schema compilation because a compiled
+schema must be structurally valid. Compilation rejects contradictions it can
+determine exactly; it does not attempt a general satisfiability proof across
+constraints such as a regular expression combined with length bounds.
+
+Unsupported metadata reports `unsupported metadata for <type>: <atom>`.
+Metadata across a multi-type union must be placed per option.
+
+## Layering
+
+For repeated atom classes, the outer layer wins; within one layer, the
+rightmost atom wins. The rule applies uniformly to limits and field notation:
+
+```python
+from typing import Annotated
+from pytypehint import Max, Min, OptionalToggle
+
+Percent = Annotated[int, Min(0), Max(100)]
+Narrow = Annotated[Percent, Max(50)]
+
+Optional = Annotated[int | None, OptionalToggle(True)]
+Closed = Annotated[Optional, OptionalToggle(False)]
+```
+
+Conflicting field atoms hoisted from different union options fail with
+`conflicting ... across union options`; an explicit outer atom overrides them.

pytypehint-0.0.1/docs/build.md

@@ -0,0 +1,96 @@
+# Build
+
+`Struct.build(data)` returns a validated dataclass instance.
+`Signature.build(data)` returns validated, constructed keyword arguments. It
+never calls the function; use `fn(**kwargs)` or `await fn(**kwargs)` yourself.
+
+```python
+from dataclasses import dataclass
+from pytypehint import signature_of, struct_of
+
+@dataclass
+class Config:
+    n: int = 1
+
+def run(config: Config):
+    return config.n
+
+data = {"n": 2}
+instance = struct_of(Config).build(data)
+kwargs = signature_of(run).build({"config": data})
+result = run(**kwargs)
+```
+
+## Data in, objects out
+
+Input uses dictionaries for every dataclass, including nested values. Instances
+are rejected because input belongs to the external-data side of the boundary:
+
+```text
+page: expected dict, got Page instance
+```
+
+Defaults are authored schema data and may still be dataclass instances.
+
+Nested dictionaries become instances; nested lists are rebuilt with their
+contents constructed. Input values are validated by exact type before any
+constructor runs.
+
+## Dataclass unions and `$type`
+
+Scalar union values already carry their Python type. A dictionary does not, so a
+union containing two or more dataclasses requires the reserved `$type` key. Its
+value is the selected class's `__name__`.
+
+```python
+from dataclasses import dataclass
+from pytypehint import struct_of
+
+@dataclass
+class File: path: str
+
+@dataclass
+class Url: value: str
+
+@dataclass
+class Source: value: File | Url
+
+data = {"value": {"$type": "Url", "value": "https://example.test"}}
+struct_of(Source).resolve(data)
+# {'value': {'$type': 'Url', 'value': 'https://example.test'}}
+struct_of(Source).build(data)    # Source(value=Url(...)); consumes $type
+```
+
+Missing and invalid discriminators fail as follows:
+
+```text
+value: ambiguous dict: field accepts File | Url — add "$type" naming the variant
+value: $type: not a choice: 'Other', expected one of ('File', 'Url')
+value: $type: expected str, got int
+```
+
+`$type` on a non-ambiguous dataclass is an ordinary unexpected key. The name
+cannot collide with a dataclass field because fields must be identifiers.
+Discrimination works at every nesting depth and in union-valued list items.
+
+## Errors and constructors
+
+Validation errors accumulate field names and list indexes:
+
+```text
+cart: items: [0]: size: default: too large: 145, maximum 100
+```
+
+Nested `resolve` failures receive the complete path. Once validation succeeds,
+`__init__` and `__post_init__` exceptions propagate unchanged: they are program
+errors, not input-coordinate errors. Put cross-field validation in
+`__post_init__`; it runs after each successful construction.
+
+`build` validates the input tree once and then constructs from it. Do not mutate
+the input while that construction is running: `__post_init__` is for cross-field
+validation, not for effects on the input data. A constructor that reaches back
+and edits the dictionaries still being built reads values the core has already
+validated and will not check again, so the result is undefined. This is the same
+promise [defaults.md](defaults.md) asks for recipes, and it belongs to the author
+for the same reason: the core cannot prove it without charging every honest input
+for the check.

pytypehint-0.0.1/docs/comparison.md

@@ -0,0 +1,35 @@
+# Comparison
+
+| Capability | pytypehint core | Wrapper | Dataclasses alone |
+|---|---:|---:|---:|
+| Compile type hints into inspectable shapes | yes | consumes | no |
+| Exact validation and error paths | yes | may present | no |
+| Cross-check atom contradictions at import | yes | no | no |
+| Fresh rematerialized defaults | yes | consumes | factories only |
+| Construct nested dataclasses from data | yes | calls | no |
+| Coerce HTTP/CLI/form input | no | yes | no |
+| Render controls | no | yes | no |
+| Accumulate every failure in a tree | no | yes | no |
+| Interpret the schema (optionality, traversal) | no | yes | no |
+| Execute or await functions | no | yes | normal Python |
+
+The core column is schema, validation and construction, and stops there. The
+wrapper column need not be a single wrapper: coercion, presentation, inspection
+ergonomics and error accumulation may live in the wrapper itself or in an
+intermediate package that depends on the core and versions its own conveniences
+on its own schedule. See [philosophy.md](philosophy.md).
+
+## When not to use it
+
+Do not use pytypehint when input is already trusted Python objects, when coercion
+is the primary task and no wrapper boundary exists, or when the required types
+fall outside its closed vocabulary. Direct dataclass construction is simpler for
+internal code without an external-data boundary.
+
+## Cost
+
+Compile schemas once and share them. Compilation resolves hints, checks atoms and
+certifies defaults. `build` then validates the supplied tree once and constructs
+directly from it; missing defaults are rematerialized and validated at their own
+level. Every value is validated exactly once, so the cost is linear in the size
+of the input.

pytypehint-0.0.1/docs/defaults.md

@@ -0,0 +1,37 @@
+# Defaults
+
+A default is a recipe. It is certified when the schema compiles and
+rematerialized whenever a build or resolve omits its key.
+
+| Default | Rematerialization |
+|---|---|
+| `int`, `float`, `str`, `bool`, `date`, `time`, `None` | passed as is; immutable |
+| Enum member | passed as is; members are singletons |
+| list | fresh list; items rematerialized recursively |
+| dataclass instance | reconstructed through its constructor |
+| `default_factory` | factory called again |
+
+Recipes run once at `struct_of`/`signature_of` for certification and once per
+missing-key serving. A provided key never runs its recipe. The served value is
+validated each time, so an impure recipe that drifts outside its schema
+fails with a `default` path segment.
+
+Defaults must be pure and deterministic: same recipe, equal result, no shared
+mutable state or observable side effects. The core cannot prove that promise.
+Mutating an externally held recipe object or the certified `field.default`
+violates the same rule from outside and remains the author's responsibility. The
+same promise covers the input: `build` validates it once and constructs from it,
+so the core watches neither concurrent mutation nor a `__post_init__` that edits
+the input data. See [build.md](build.md).
+
+Instance reconstruction preserves equality, not internal alias topology. It
+runs `__init__` and `__post_init__` on every serving.
+
+Python rejects a non-frozen dataclass instance used directly as a dataclass
+field default before pytypehint runs (`ValueError: mutable default ... is not
+allowed`). Use `field(default_factory=...)`. Function defaults have no such
+Python restriction and may use an instance directly.
+
+Calling a function directly still uses Python's shared defaults. Fresh function
+defaults apply only when data passes through `signature_of(fn).resolve(...)` or
+`.build(...)`.