pytypehint 0.0.1__py3-none-any.whl

pytypehint/__init__.py

@@ -0,0 +1,58 @@
+from pytypehint.bridge import struct_of, signature_of
+from pytypehint.atoms import (
+    # limit atoms
+    Min, Max, Choices, MultipleOf, Pattern, IsPathFile,
+    # notation atoms
+    Label, Description, Placeholder, Step, Slider, IsPassword, Rows, Extra,
+    OptionalToggle,
+)
+from pytypehint.errors import SchemaTypeError, SchemaValueError
+from pytypehint.structure import Struct, Field
+from pytypehint.signature import Signature
+from pytypehint.shapes import (
+    Shape, Int, Float, Str, Bool, Date, Time, List, NoneShape, EnumShape,
+)
+from pytypehint.utils import MISSING
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "struct_of",
+    "signature_of",
+    # limit atoms
+    "Min",
+    "Max",
+    "Choices",
+    "MultipleOf",
+    "Pattern",
+    "IsPathFile",
+    # notation atoms
+    "Label",
+    "Description",
+    "Placeholder",
+    "Step",
+    "Slider",
+    "IsPassword",
+    "Rows",
+    "Extra",
+    "OptionalToggle",
+    # errors
+    "SchemaTypeError",
+    "SchemaValueError",
+    # compiled schema, for inspection
+    "Struct",
+    "Field",
+    "Signature",
+    # shapes
+    "Shape",
+    "Int",
+    "Float",
+    "Str",
+    "Bool",
+    "Date",
+    "Time",
+    "List",
+    "NoneShape",
+    "EnumShape",
+    "MISSING",
+]

pytypehint/atoms.py

@@ -0,0 +1,220 @@
+import re
+from dataclasses import dataclass, field
+from datetime import date, time
+
+from pytypehint.utils import type_name
+
+
+_ORDERED = (int, float, date, time)
+
+
+@dataclass(frozen=True)
+class Min:
+    value: int | float | date | time
+    exclusive: bool = field(default=False, kw_only=True)
+
+    def __post_init__(self):
+        name = type_name(self)
+        if type(self.value) not in _ORDERED:
+            raise TypeError(f"{name}.value must be orderable (int, float, date or time), got {type(self.value).__name__}")
+
+        if type(self.exclusive) is not bool:
+            raise TypeError(f"{name}.exclusive must be bool, got {type(self.exclusive).__name__}")
+
+
+@dataclass(frozen=True)
+class Max:
+    value: int | float | date | time
+    exclusive: bool = field(default=False, kw_only=True)
+
+    def __post_init__(self):
+        name = type_name(self)
+        if type(self.value) not in _ORDERED:
+            raise TypeError(f"{name}.value must be orderable (int, float, date or time), got {type(self.value).__name__}")
+
+        if type(self.exclusive) is not bool:
+            raise TypeError(f"{name}.exclusive must be bool, got {type(self.exclusive).__name__}")
+
+
+@dataclass(frozen=True)
+class Label:
+    value: str
+
+    def __post_init__(self):
+        name = type_name(self)
+        if type(self.value) is not str:
+            raise TypeError(f"{name}.value must be str, got {type(self.value).__name__}")
+
+        if not self.value:
+            raise ValueError(f"{name}.value must not be empty")
+
+
+@dataclass(frozen=True)
+class Description:
+    value: str
+
+    def __post_init__(self):
+        name = type_name(self)
+        if type(self.value) is not str:
+            raise TypeError(f"{name}.value must be str, got {type(self.value).__name__}")
+
+        if not self.value:
+            raise ValueError(f"{name}.value must not be empty")
+
+
+@dataclass(frozen=True)
+class Step:
+    value: int | float
+
+    def __post_init__(self):
+        name = type_name(self)
+        if type(self.value) not in (int, float):
+            raise TypeError(f"{name}.value must be a number, got {type(self.value).__name__}")
+
+        if self.value <= 0:
+            raise ValueError(f"{name}.value must be > 0, got {self.value}")
+
+
+@dataclass(frozen=True, kw_only=True)
+class Slider:
+    show_value: bool = True
+
+    def __post_init__(self):
+        if type(self.show_value) is not bool:
+            raise TypeError(f"{type_name(self)}.show_value must be bool, got {type(self.show_value).__name__}")
+
+
+@dataclass(frozen=True)
+class Placeholder:
+    value: str
+
+    def __post_init__(self):
+        name = type_name(self)
+        if type(self.value) is not str:
+            raise TypeError(f"{name}.value must be str, got {type(self.value).__name__}")
+
+        if not self.value:
+            raise ValueError(f"{name}.value must not be empty")
+
+
+@dataclass(frozen=True)
+class Extra:
+    value: str
+
+    def __post_init__(self):
+        name = type_name(self)
+        if type(self.value) is not str:
+            raise TypeError(f"{name}.value must be str, got {type(self.value).__name__}")
+
+        if not self.value:
+            raise ValueError(f"{name}.value must not be empty")
+
+
+@dataclass(frozen=True, kw_only=True)
+class Choices:
+    values: tuple[int | float | str | date | time, ...]
+
+    def __post_init__(self):
+        name = type_name(self)
+        if type(self.values) is not tuple:
+            raise TypeError(f"{name}.values must be tuple, got {type(self.values).__name__}")
+
+        if not self.values:
+            raise ValueError(f"{name}.values must not be empty")
+
+        # Type belongs to the key because Python equates 1, 1.0 and True.
+        keys = [(type(v), v) for v in self.values]
+        try:
+            if len(keys) != len(set(keys)):
+                raise ValueError(f"{name}.values must not repeat")
+        except TypeError:
+            raise TypeError(f"{name}.values must be hashable") from None
+
+
+@dataclass(frozen=True)
+class MultipleOf:
+    value: int
+
+    def __post_init__(self):
+        name = type_name(self)
+        if type(self.value) is not int:
+            raise TypeError(f"{name}.value must be int, got {type(self.value).__name__}")
+
+        if self.value <= 0:
+            raise ValueError(f"{name}.value must be > 0, got {self.value}")
+
+
+@dataclass(frozen=True)
+class Pattern:
+    value: str
+    message: str | None = field(default=None, kw_only=True)
+
+    def __post_init__(self):
+        name = type_name(self)
+        if type(self.value) is not str:
+            raise TypeError(f"{name}.value must be str, got {type(self.value).__name__}")
+
+        if not self.value:
+            raise ValueError(f"{name}.value must not be empty")
+
+        try:
+            re.compile(self.value)
+        except re.error as e:
+            raise ValueError(f"{name}.value is not a valid regex: {e}") from e
+
+        if self.message is not None:
+            if type(self.message) is not str:
+                raise TypeError(f"{name}.message must be str, got {type(self.message).__name__}")
+
+            if not self.message:
+                raise ValueError(f"{name}.message must not be empty")
+
+
+@dataclass(frozen=True, kw_only=True)
+class IsPassword:
+    pass
+
+
+@dataclass(frozen=True)
+class Rows:
+    value: int
+
+    def __post_init__(self):
+        name = type_name(self)
+        if type(self.value) is not int:
+            raise TypeError(f"{name}.value must be int, got {type(self.value).__name__}")
+
+        if self.value <= 0:
+            raise ValueError(f"{name}.value must be > 0, got {self.value}")
+
+
+@dataclass(frozen=True, kw_only=True)
+class IsPathFile:
+    extensions: tuple[str, ...] = ()
+
+    def __post_init__(self):
+        name = type_name(self)
+        if type(self.extensions) is not tuple:
+            raise TypeError(f"{name}.extensions must be tuple, got {type(self.extensions).__name__}")
+
+        for e in self.extensions:
+            if type(e) is not str:
+                raise TypeError(f"{name}.extensions: expected str, got {type(e).__name__}")
+
+            if not e.startswith("."):
+                raise ValueError(f"{name}.extensions: {e!r} must start with '.'")
+
+            if e != e.lower():
+                raise ValueError(f"{name}.extensions: {e!r} must be lowercase")
+
+        if len(self.extensions) != len(set(self.extensions)):
+            raise ValueError(f"{name}.extensions must not repeat")
+
+
+@dataclass(frozen=True)
+class OptionalToggle:
+    enabled: bool
+
+    def __post_init__(self):
+        if type(self.enabled) is not bool:
+            raise TypeError(f"{type_name(self)}.enabled must be bool, got {type(self.enabled).__name__}")

pytypehint/bridge.py

@@ -0,0 +1,309 @@
+import inspect
+import types
+from dataclasses import (
+    MISSING as _DC_MISSING, Field as _DcField, InitVar as _InitVar,
+    fields as dc_fields, is_dataclass,
+)
+from enum import Enum
+from typing import Annotated, Literal, Union, get_args, get_origin, get_type_hints
+
+from pytypehint import atoms
+from pytypehint.atoms import Choices, Description, Label, OptionalToggle
+from pytypehint.shapes import Bool, Date, EnumShape, Float, Int, List, NoneShape, Shape, Str, Time
+from pytypehint.signature import Signature
+from pytypehint.structure import Field, Struct, _Factory, _certify
+from pytypehint.utils import MISSING
+
+_ATOM_CLASSES = {v for v in vars(atoms).values()
+                 if isinstance(v, type) and is_dataclass(v)
+                 and v.__module__ == atoms.__name__}
+_FIELD_ATOMS = (Label, Description, OptionalToggle)
+
+
+def _atom_type(hint):
+    if get_origin(hint) in (Union, types.UnionType):
+        hint = next((a for a in get_args(hint) if a is not type(None)), None)
+    return hint if hint in _ATOM_CLASSES else None
+
+
+def _atoms_of(shape_cls):
+    hints = get_type_hints(shape_cls)
+    return {a: f.name for f in dc_fields(shape_cls)
+            if (a := _atom_type(hints[f.name])) is not None}
+
+
+_VOCABULARY = {cls.pytype: (cls, _atoms_of(cls))
+               for cls in (Int, Float, Bool, Str, Date, Time,
+                           NoneShape, List)}
+
+
+def _kwargs_of(meta, kind, table):
+    kwargs = {}
+    for m in meta:
+        name = table.get(type(m))
+        if name is None:
+            raise TypeError(f"unsupported metadata for {kind}: {m!r}")
+        kwargs[name] = m
+    return kwargs
+
+
+def _split_annotated(hint):
+    if get_origin(hint) is Annotated:
+        base, *meta = get_args(hint)
+        return base, tuple(meta)
+    return hint, ()
+
+
+def _options_of(hint):
+    if get_origin(hint) in (Union, types.UnionType):
+        return get_args(hint)
+    return (hint,)
+
+
+def _hint_label(hint) -> str:
+    return hint.__name__ if isinstance(hint, type) else str(hint).replace("typing.", "")
+
+
+# Two hints can read as different options and still compile to one pytype:
+# Literal['a'] and str both become Str. A list item routes by its exact runtime
+# type, so such a pair is unroutable. List.item reports the collision by shape,
+# which cannot name the hints the author actually wrote — this can.
+def _reject_colliding_items(raw_options, item_options) -> None:
+    seen: dict[type, object] = {}
+    for hint, shape in zip(raw_options, item_options):
+        if shape.pytype in seen:
+            raise ValueError(
+                f"list items: {_hint_label(seen[shape.pytype])} and {_hint_label(hint)} "
+                f"both compile to {shape.pytype.__name__} — merge them into one option, "
+                f"or give each variant a dataclass and route with $type")
+        seen[shape.pytype] = hint
+
+
+def _shape_of(opt, cache: dict) -> Shape:
+    base, meta = _split_annotated(opt)
+
+    if base is None:
+        base = type(None)
+
+    if base is list:
+        raise TypeError("list requires an item type: list[X]")
+
+    if get_origin(base) is list:
+        (item_hint,) = get_args(base)
+        item_base, item_meta = _split_annotated(item_hint)
+        if any(isinstance(m, _FIELD_ATOMS) for m in item_meta):
+            raise TypeError("field atoms cannot apply to list items")
+        raw_options = _options_of(item_base)
+        if len(raw_options) > 1 and item_meta:
+            raise TypeError(
+                "metadata on a union of multiple types must go per option: "
+                "Annotated[int, Min(0)] | str")
+        item_options = ((_shape_of(item_hint, cache),) if len(raw_options) == 1
+                        else tuple(_shape_of(o, cache) for o in raw_options))
+        if len(raw_options) > 1:
+            _reject_colliding_items(raw_options, item_options)
+        return List(item=item_options,
+                    **_kwargs_of(meta, "list", _VOCABULARY[list][1]))
+
+    if get_origin(base) is Literal:
+        values = get_args(base)
+        for v in values:
+            if type(v) is float:
+                raise TypeError("Literal values must be int or str, got float — "
+                                "for float choices use Annotated[float, Choices(...)]")
+            if type(v) not in (int, str):
+                raise TypeError(f"Literal values must be int or str, got {type(v).__name__}")
+        if len({type(v) for v in values}) > 1:
+            raise TypeError("Literal values must all be the same type")
+        if any(type(m) is Choices for m in meta):
+            raise TypeError("Literal already defines its choices")
+        return _shape_of(Annotated[tuple([type(values[0]),
+                                          Choices(values=values), *meta])], cache)
+
+    if base in _VOCABULARY:
+        shape_cls, table = _VOCABULARY[base]
+        return shape_cls(**_kwargs_of(meta, base.__name__, table))
+
+    if isinstance(base, type) and issubclass(base, Enum):
+        _kwargs_of(meta, "enum", {})
+        return EnumShape(cls=base)
+
+    if isinstance(base, type) and is_dataclass(base):
+        _kwargs_of(meta, "dataclass", {})
+        return _struct_of_class(base, cache)
+
+    raise TypeError(f"unsupported type: {base!r}")
+
+
+def _field_atoms_of(meta):
+    field_atoms = {}
+    type_meta = []
+    for m in meta:
+        if isinstance(m, _FIELD_ATOMS):
+            field_atoms[type(m)] = m
+        else:
+            type_meta.append(m)
+    return field_atoms, type_meta
+
+
+def _field_of(name: str, hint, default, cache: dict) -> Field:
+    base_hint, meta = _split_annotated(hint)
+
+    outer_atoms, type_meta = _field_atoms_of(meta)
+
+    options = _options_of(base_hint)
+
+    if type_meta:
+        # None expresses optionality; type metadata targets the single real option.
+        real_opts = [o for o in options if o is not type(None) and o is not None]
+        if len(real_opts) == 0:
+            raise TypeError(f"{name}: metadata on None: None is optionality, not a type")
+        if len(real_opts) > 1:
+            raise TypeError(
+                f"{name}: metadata on a union of multiple types must go per option: "
+                f"Annotated[int, Min(0)] | str")
+        # Preserve the user's union-option order.
+        options = tuple(
+            Annotated[tuple([o, *type_meta])]
+            if o is not type(None) and o is not None else o
+            for o in options)
+
+    # typing flattens Annotated aliases; hoist their field atoms before compiling.
+    hoisted: dict[type, object] = {}
+    stripped = []
+    for opt in options:
+        opt_base, opt_meta = _split_annotated(opt)
+        opt_atoms, opt_type_meta = _field_atoms_of(opt_meta)
+        for atom_type, atom in opt_atoms.items():
+            if atom_type in outer_atoms:
+                continue
+            existing = hoisted.get(atom_type)
+            if existing is not None and existing != atom:
+                raise TypeError(
+                    f"{name}: conflicting {atom_type.__name__.lower()}s across union options: "
+                    f"{getattr(existing, 'value', existing)!r} vs {getattr(atom, 'value', atom)!r}")
+            hoisted[atom_type] = atom
+        stripped.append(
+            Annotated[tuple([opt_base, *opt_type_meta])] if opt_type_meta else opt_base)
+
+    field_atoms = {**hoisted, **outer_atoms}
+
+    return Field(name=name, shape=tuple(_shape_of(o, cache) for o in stripped),
+                 default=default,
+                 label=field_atoms.get(Label),
+                 description=field_atoms.get(Description),
+                 optional_toggle=field_atoms.get(OptionalToggle))
+
+
+def _default_of(f):
+    if f.default is not _DC_MISSING:
+        return f.default
+    if f.default_factory is not _DC_MISSING:
+        # The factory is the recipe and runs for each missing-key serving.
+        return _Factory(f.default_factory)
+    return MISSING
+
+
+def _struct_of_class(cls: type, cache: dict) -> Struct:
+    if cls in cache:
+        return cache[cls]
+
+    struct = Struct.__new__(Struct)
+    cache[cls] = struct
+    object.__setattr__(struct, "cls", cls)
+
+    hints = get_type_hints(cls, include_extras=True)
+
+    # InitVar enters construction but is absent from the instance, so no Field can represent it.
+    # The resolved hint carries that fact itself; ClassVar resolves to ClassVar, not InitVar.
+    initvars = sorted(n for n, h in hints.items() if isinstance(h, _InitVar))
+    if initvars:
+        raise TypeError(f"{initvars[0]}: InitVar fields are not supported")
+
+    flds = []
+    for f in dc_fields(cls):
+        if not f.init:
+            raise TypeError(f"{f.name}: init=False fields are not supported")
+        raw = _default_of(f)
+        fld = _field_of(f.name, hints[f.name], raw, cache)
+        flds.append(fld)
+
+    object.__setattr__(struct, "fields", tuple(flds))
+    struct.__post_init__()
+
+    return struct
+
+
+def _validate_cache(cache: dict) -> None:
+    # Recursive fields certify after the complete shape graph exists.
+    for struct in cache.values():
+        for f in struct.fields:
+            if not f._deferred:
+                continue
+            pytypes = [s.pytype for s in f.shape]
+            if len(pytypes) != len(set(pytypes)):
+                raise ValueError(f"Field {f.name!r}: duplicate option types in shape")
+            object.__setattr__(f, "default", _certify(f))
+            object.__setattr__(f, "_deferred", False)
+
+
+def struct_of(obj) -> Struct:
+    if is_dataclass(obj):
+        if not isinstance(obj, type):
+            raise TypeError(f"expected a dataclass type, got an instance of {type(obj).__name__}")
+        cache: dict[type, Struct] = {}
+        root = _struct_of_class(obj, cache)
+        _validate_cache(cache)
+        return root
+
+    if isinstance(obj, type):
+        raise TypeError(
+            f"{obj.__name__} is not a dataclass — add @dataclass; "
+            f"pytypehint reads standard dataclasses, it doesn't replace them")
+
+    raise TypeError(f"expected a dataclass type, got {obj!r}")
+
+
+def signature_of(fn) -> Signature:
+    if not inspect.isfunction(fn):
+        raise TypeError(
+            f"expected a plain function, got {fn!r} — bound methods, partials and "
+            f"callable objects are not supported: wrap the call in a plain function "
+            f"(def run(q: str): return service.search(q))")
+
+    if fn.__name__ == "<lambda>":
+        raise TypeError("lambdas have no usable name; use a named function")
+
+    hints = get_type_hints(fn, include_extras=True)
+    cache: dict[type, Struct] = {}
+    params = []
+
+    for i, (n, p) in enumerate(inspect.signature(fn).parameters.items()):
+        if p.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            raise TypeError(f"{n}: variadic parameters (*args/**kwargs) are not supported")
+
+        if p.kind is inspect.Parameter.POSITIONAL_ONLY:
+            raise TypeError(f"{n}: positional-only parameters are not supported")
+
+        # An unhinted leading self/cls identifies an unbound method.
+        if i == 0 and n in ("self", "cls") and n not in hints:
+            raise TypeError(
+                f"{n}: looks like an unbound method — pytypehint takes "
+                f"plain functions; wrap the call (def run(q: str): return "
+                f"service.search(q))")
+
+        if n not in hints:
+            raise TypeError(f"{n}: missing type hint")
+
+        default = MISSING if p.default is inspect.Parameter.empty else p.default
+
+        if type(default) is _DcField:
+            raise TypeError(
+                f"{n}: field() is dataclass syntax; in functions write the default "
+                f"directly — it is fresh through the schema")
+
+        params.append(_field_of(n, hints[n], default, cache))
+
+    _validate_cache(cache)
+    sig = Signature(name=fn.__name__, doc=fn.__doc__, params=tuple(params))
+    return sig

pytypehint/errors.py

@@ -0,0 +1,56 @@
+"""Structured validation errors.
+
+Every validation failure carries the coordinate where it happened as data, not
+only inside its message. `path` walks from the root of the supplied input to the
+value that failed; `leaf` is the failure itself, with no path attached. `str()`
+renders the two into the exact line the schema has always produced, so wrappers
+can keep matching on text or switch to the structure.
+"""
+
+
+def _render(path, leaf: str) -> str:
+    # Integers are list indexes and render as "[0]"; everything else is a key.
+    return "".join(f"[{s}]: " if type(s) is int else f"{s}: " for s in path) + leaf
+
+
+# BaseException.__reduce__ would rebuild from `args`, which holds the rendered
+# line — reconstruction would land on leaf=<whole line>, path=(), and only the
+# trailing state dict would put it right. Rebuild from the real arguments
+# instead, and keep the state so add_note() and wrapper attributes survive too.
+def _reduce(error):
+    return (type(error), (error.leaf, error.path), error.__dict__)
+
+
+class SchemaTypeError(TypeError):
+    """A value had the wrong type. Subclasses TypeError; existing handlers still catch it."""
+
+    def __init__(self, leaf: str, path: tuple = ()):
+        self.leaf = leaf
+        self.path: tuple = tuple(path)
+        # A single arg keeps str(error) equal to the rendered line.
+        super().__init__(_render(self.path, self.leaf))
+
+    def __reduce__(self):
+        return _reduce(self)
+
+
+class SchemaValueError(ValueError):
+    """A value had the right type but broke a constraint. Subclasses ValueError."""
+
+    def __init__(self, leaf: str, path: tuple = ()):
+        self.leaf = leaf
+        self.path: tuple = tuple(path)
+        super().__init__(_render(self.path, self.leaf))
+
+    def __reduce__(self):
+        return _reduce(self)
+
+
+def _prefixed(error: Exception, path: tuple) -> Exception:
+    """Re-raise `error` one level out, with `path` prepended and its leaf intact."""
+    if isinstance(error, (SchemaTypeError, SchemaValueError)):
+        return type(error)(error.leaf, (*path, *error.path))
+    # A foreign TypeError/ValueError — a user factory or __post_init__ — has no
+    # structure to preserve, so its whole message becomes the leaf.
+    cls = SchemaTypeError if isinstance(error, TypeError) else SchemaValueError
+    return cls(str(error), path)