overture-schema-codegen 0.1.1.dev0__py3-none-any.whl

overture/schema/codegen/extraction/field.py

@@ -0,0 +1,172 @@
+"""Tree-shaped IR for model field types.
+
+`FieldShape` is a discriminated union -- `Primitive`, `LiteralScalar`,
+`AnyScalar`, `ModelRef`, `UnionRef`, `ArrayOf`, `MapOf`, `NewTypeShape`
+-- nested to describe arbitrary list / dict / NewType wrapping. Each
+variant carries its own constraints (where meaningful), and walkers
+encounter each constraint at the layer it targets.
+
+The three terminal scalar variants (`Primitive`, `LiteralScalar`,
+`AnyScalar`) are grouped under the `Scalar` type alias for consumers
+that only need to ask "is this a leaf?".
+
+`NewTypeShape` wraps an inner shape, so its position relative to
+`ArrayOf` is structural: `NewTypeShape(inner=ArrayOf(...))` is a
+NewType over `list[X]`, while `ArrayOf(element=NewTypeShape(...))`
+is a list of NewType-wrapped values. Consumers pattern-match on
+shape to distinguish the two.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeAlias
+
+if TYPE_CHECKING:
+    from .specs import RecordSpec, UnionSpec
+
+__all__ = [
+    "AnyScalar",
+    "ArrayOf",
+    "ConstraintSource",
+    "FieldShape",
+    "LiteralScalar",
+    "MapOf",
+    "ModelRef",
+    "NewTypeShape",
+    "Primitive",
+    "Scalar",
+    "UnionRef",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class ConstraintSource:
+    """A constraint paired with the NewType that contributed it.
+
+    `source_ref` and `source_name` identify the NewType that declared
+    the constraint; both are `None` for constraints contributed directly
+    on a field annotation rather than through a NewType. `constraint`
+    is the raw metadata object from `Annotated[..., constraint]`.
+    """
+
+    source_ref: object | None
+    source_name: str | None
+    constraint: object
+
+
+@dataclass(frozen=True, slots=True)
+class Primitive:
+    """Terminal type with a registry lookup key.
+
+    Covers primitives (`int32`, `str`), enums, Pydantic built-ins
+    (`HttpUrl`, `EmailStr`), and `BaseModel` subclasses that weren't
+    resolved to a `ModelRef` (e.g. when no `model_resolver` was
+    supplied).
+    """
+
+    base_type: str
+    source_type: type | None = None
+    constraints: tuple[ConstraintSource, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class LiteralScalar:
+    """`Literal[X, ...]` terminal."""
+
+    values: tuple[object, ...]
+    constraints: tuple[ConstraintSource, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class AnyScalar:
+    """`typing.Any` terminal."""
+
+    constraints: tuple[ConstraintSource, ...] = ()
+
+
+Scalar: TypeAlias = Primitive | LiteralScalar | AnyScalar
+"""Terminal shape: a value that doesn't wrap another shape.
+
+Consumers that just need "is this a leaf?" check `isinstance(x, Scalar)`;
+consumers that need terminal-specific data narrow to a variant.
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class ModelRef:
+    """Reference to a Pydantic sub-model.
+
+    `starts_cycle` marks the back-edge of a cycle in the model graph;
+    consumers that recurse into models must stop at cycle starts.
+    """
+
+    model: RecordSpec
+    starts_cycle: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class UnionRef:
+    """Reference to a discriminated union of models."""
+
+    union: UnionSpec
+
+
+@dataclass(frozen=True, slots=True)
+class ArrayOf:
+    """Sequence of values sharing a single element shape.
+
+    Nested arrays are nested `ArrayOf` instances; there is no numeric
+    depth field. `constraints` carries array-level validation rules
+    (length, uniqueness). Per-element constraints live on `element`
+    and its descendants.
+    """
+
+    element: FieldShape
+    constraints: tuple[ConstraintSource, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class MapOf:
+    """Mapping from a key shape to a value shape.
+
+    `constraints` carries map-level validation rules. Per-key and
+    per-value constraints live on `key` / `value` respectively.
+    """
+
+    key: FieldShape
+    value: FieldShape
+    constraints: tuple[ConstraintSource, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class NewTypeShape:
+    """A NewType wrapper around an inner shape.
+
+    Position relative to other wrappers is meaningful:
+    `NewTypeShape(inner=ArrayOf(...))` is a NewType over `list[X]`;
+    `ArrayOf(element=NewTypeShape(...))` is a list of NewType-wrapped
+    values. Consumers distinguish the two by pattern, not a numeric
+    offset.
+
+    Constraints contributed by the NewType chain attach to the
+    `Scalar` / `ArrayOf` / `MapOf` layer they target, not to the
+    wrapper itself. `name` and `ref` identify the NewType for linking
+    without owning constraint state.
+    """
+
+    name: str
+    ref: object
+    inner: FieldShape
+
+
+FieldShape: TypeAlias = (
+    Primitive
+    | LiteralScalar
+    | AnyScalar
+    | ModelRef
+    | UnionRef
+    | ArrayOf
+    | MapOf
+    | NewTypeShape
+)

overture/schema/codegen/extraction/field_constraints.py

@@ -0,0 +1,185 @@
+"""Convert field-level constraints to display text.
+
+Handles constraints from Annotated metadata and NewType wrappers:
+Ge, Gt, Interval, Le, Lt, ArrayMinLen, ArrayMaxLen, ScalarMinLen,
+ScalarMaxLen, GeometryTypeConstraint, Reference, and custom constraint
+classes.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+
+from annotated_types import Ge, Gt, Interval, Le, Lt, MultipleOf
+
+from overture.schema.system.geometric import GeometryTypeConstraint
+from overture.schema.system.ref import Reference
+
+from .docstring import first_docstring_line
+from .length_constraints import ArrayMaxLen, ArrayMinLen, ScalarMaxLen, ScalarMinLen
+from .literal_alternatives import LiteralAlternatives
+from .specs import TypeIdentity
+from .type_analyzer import ConstraintSource
+
+__all__ = [
+    "constraint_display_text",
+    "describe_field_constraint",
+]
+
+# Bound attribute -> mathematical symbol for prose rendering.
+_BOUND_OPS: tuple[tuple[str, str], ...] = (
+    ("ge", "≥"),
+    ("gt", ">"),
+    ("le", "≤"),
+    ("lt", "<"),
+)
+
+
+def _first_bound(obj: object) -> str | None:
+    """Return backticked notation for the first set bound, or None."""
+    for attr, op in _BOUND_OPS:
+        val = getattr(obj, attr, None)
+        if val is not None:
+            return f"`{op} {val}`"
+    return None
+
+
+def _describe_interval(iv: Interval) -> str:
+    """Format an Interval as readable bound notation."""
+    lower_val = iv.ge if iv.ge is not None else iv.gt
+    lower_op = "≤" if iv.ge is not None else "<"
+    upper_val = iv.le if iv.le is not None else iv.lt
+    upper_op = "≤" if iv.le is not None else "<"
+
+    if lower_val is not None and upper_val is not None:
+        return f"`{lower_val} {lower_op} x {upper_op} {upper_val}`"
+
+    return _first_bound(iv) or ""
+
+
+def _is_opaque_constraint(constraint: object) -> bool:
+    """Check whether the constraint has no custom __repr__ (renders as just its class name)."""
+    return type(constraint).__repr__ is object.__repr__
+
+
+def _geometry_type_label(value: str) -> str:
+    """Convert a GeometryType value to PascalCase display name.
+
+    >>> _geometry_type_label("line_string")
+    'LineString'
+    """
+    return "".join(part.title() for part in value.split("_"))
+
+
+def describe_field_constraint(
+    constraint: object,
+    link_fn: Callable[[TypeIdentity], str] | None = None,
+) -> str:
+    """Return a display string for a field-level constraint object.
+
+    *link_fn* resolves a TypeIdentity to a markdown link string (e.g.
+    `` [`Name`](path) ``). When None, names render as inline code.
+    """
+    if isinstance(constraint, GeometryTypeConstraint):
+        labels = ", ".join(
+            _geometry_type_label(gt.value) for gt in constraint.allowed_types
+        )
+        return f"Allowed geometry types: {labels}"
+    if isinstance(constraint, Reference):
+        rel_value: str = constraint.relationship.value  # type: ignore[assignment]
+        rel_label = rel_value.replace("_", " ")
+        target = constraint.relatee
+        target_id = TypeIdentity.of(target)
+        target_str = link_fn(target_id) if link_fn else f"`{target.__name__}`"
+        if constraint.role:
+            role_label = constraint.role.replace("_", " ")
+            return f"References {target_str} ({rel_label}, {role_label})"
+        return f"References {target_str} ({rel_label})"
+    if isinstance(constraint, Interval):
+        desc = _describe_interval(constraint)
+        if desc:
+            return desc
+    elif isinstance(constraint, (Ge, Gt, Le, Lt)):
+        result = _first_bound(constraint)
+        if result is not None:
+            return result
+    if isinstance(constraint, MultipleOf):
+        if constraint.multiple_of == 1:
+            return "Must be a whole number"
+        return f"Must be a multiple of {constraint.multiple_of}"
+    if isinstance(constraint, (ArrayMinLen, ScalarMinLen)):
+        return f"Minimum length: {constraint.min_length}"
+    if isinstance(constraint, (ArrayMaxLen, ScalarMaxLen)):
+        return f"Maximum length: {constraint.max_length}"
+    if isinstance(constraint, LiteralAlternatives):
+        return "Also accepts: " + ", ".join(f"`{v!r}`" for v in constraint.values)
+
+    if _is_opaque_constraint(constraint):
+        return f"`{type(constraint).__name__}`"
+    return f"`{constraint}`"
+
+
+def _constraint_class_description(constraint: object) -> str | None:
+    """Extract the first docstring line from a custom constraint class.
+
+    Returns None for builtins and classes without docstrings.
+    """
+    constraint_type = type(constraint)
+    if constraint_type.__module__ == "builtins":
+        return None
+    line = first_docstring_line(constraint_type.__doc__)
+    return line or None
+
+
+# re.UNICODE is the implicit default on compiled `str` patterns; rendering it
+# would stamp a noise `(?u)` group onto every pattern. Every other flag with a
+# visible matching effect is surfaced in the documented pattern. Unlike the
+# pyspark dispatch (`compiled_pattern_source`) -- which must reject flags
+# Spark's rlike cannot honor -- display is faithful for known flags and never
+# fails: a flag absent from this table is dropped from the rendered group, not
+# raised on. A new flag added to pyspark's supported set with a visible effect
+# belongs here too, or docs will hide that pattern's real behavior.
+_DISPLAY_FLAG_LETTERS: tuple[tuple[re.RegexFlag, str], ...] = (
+    (re.IGNORECASE, "i"),
+    (re.MULTILINE, "m"),
+    (re.DOTALL, "s"),
+    (re.VERBOSE, "x"),
+    (re.ASCII, "a"),
+)
+
+
+def _inline_flag_prefix(flags: int) -> str:
+    """Render set regex flags as an inline group like `(?im)`, or "" if none."""
+    letters = "".join(c for flag, c in _DISPLAY_FLAG_LETTERS if flags & flag)
+    return f"(?{letters})" if letters else ""
+
+
+def _constraint_pattern(constraint: object) -> str | None:
+    """Return a constraint's compiled regex as displayable source, or None.
+
+    Prepends an inline-flag group (e.g. `(?i)` for case-insensitivity) so a
+    flagged pattern reads as the regex that actually matches rather than its
+    bare, misleading source. Returns None when `constraint.pattern` is not a
+    compiled `re.Pattern`.
+    """
+    compiled = getattr(constraint, "pattern", None)
+    if not isinstance(compiled, re.Pattern):
+        return None
+    return f"{_inline_flag_prefix(compiled.flags)}{compiled.pattern}"
+
+
+def constraint_display_text(
+    cs: ConstraintSource,
+    link_fn: Callable[[TypeIdentity], str] | None = None,
+) -> str:
+    """Build display text for a constraint, combining description/pattern when available."""
+    description = _constraint_class_description(cs.constraint)
+    if _is_opaque_constraint(cs.constraint) and description:
+        cls_name = type(cs.constraint).__name__
+        pattern = _constraint_pattern(cs.constraint)
+        if pattern:
+            return f"{description} (`{cls_name}`, pattern: `{pattern}`)"
+        return f"{description} (`{cls_name}`)"
+
+    return describe_field_constraint(cs.constraint, link_fn=link_fn)

overture/schema/codegen/extraction/field_walk.py

@@ -0,0 +1,275 @@
+"""Generic traversal helpers over `FieldShape` trees.
+
+`shape_children` (one-level child enumeration) and `walk_shape`
+(pre-order DFS) cover open-ended traversals; `terminal_of`,
+`terminal_scalar`, `list_depth`, `newtype_name`, and `all_constraints`
+cover the most common derived views. `ModelRef` and `UnionRef` are
+leaves -- the walker does not cross model or union boundaries
+automatically; that's a per-consumer decision.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from enum import Enum
+
+from typing_extensions import assert_never
+
+from .field import (
+    AnyScalar,
+    ArrayOf,
+    ConstraintSource,
+    FieldShape,
+    LiteralScalar,
+    MapOf,
+    ModelRef,
+    NewTypeShape,
+    Primitive,
+    Scalar,
+    UnionRef,
+)
+
+__all__ = [
+    "all_constraints",
+    "enum_source",
+    "has_array_layer",
+    "list_depth",
+    "map_key_value_constraints",
+    "newtype_name",
+    "shape_children",
+    "terminal_model_ref",
+    "terminal_of",
+    "terminal_primitive",
+    "terminal_scalar",
+    "terminal_union_ref",
+    "walk_shape",
+]
+
+
+def terminal_of(shape: FieldShape) -> FieldShape:
+    """Unwrap `ArrayOf` and `NewTypeShape` layers to find the terminal shape.
+
+    Returns the innermost shape that isn't a sequence or NewType wrapper.
+    `Scalar`, `ModelRef`, `UnionRef`, and `MapOf` count as terminals.
+    """
+    while True:
+        match shape:
+            case ArrayOf(element=inner) | NewTypeShape(inner=inner):
+                shape = inner
+            case (
+                Primitive()
+                | LiteralScalar()
+                | AnyScalar()
+                | ModelRef()
+                | UnionRef()
+                | MapOf()
+            ):
+                return shape
+            case _:
+                assert_never(shape)
+
+
+def terminal_scalar(shape: FieldShape) -> Scalar | None:
+    """Return the terminal `Scalar`, or `None` for non-scalar terminals."""
+    terminal = terminal_of(shape)
+    return terminal if isinstance(terminal, Scalar) else None
+
+
+def terminal_primitive(shape: FieldShape) -> Primitive | None:
+    """Return the terminal `Primitive`, or `None` for non-primitive terminals.
+
+    Like `terminal_scalar`, but returns `None` for `LiteralScalar` and
+    `AnyScalar` — use this when the caller needs `base_type` or
+    `source_type`, which only exist on `Primitive`.
+    """
+    terminal = terminal_of(shape)
+    return terminal if isinstance(terminal, Primitive) else None
+
+
+def terminal_model_ref(shape: FieldShape) -> ModelRef | None:
+    """Return the terminal `ModelRef`, or `None` for non-model terminals."""
+    terminal = terminal_of(shape)
+    return terminal if isinstance(terminal, ModelRef) else None
+
+
+def terminal_union_ref(shape: FieldShape) -> UnionRef | None:
+    """Return the terminal `UnionRef`, or `None` for non-union terminals."""
+    terminal = terminal_of(shape)
+    return terminal if isinstance(terminal, UnionRef) else None
+
+
+def enum_source(shape: FieldShape) -> type[Enum] | None:
+    """Return the `Enum` class backing a `Primitive`, or `None`.
+
+    Returns the `Enum` subclass stored in `Primitive.source_type` when
+    `shape` is a `Primitive` and `source_type` is an `Enum` subclass.
+    Returns `None` for every other shape, including wrappers: a
+    `NewTypeShape` wrapping an enum-backed `Primitive` returns `None`,
+    not the inner enum.
+
+    Parameters
+    ----------
+    shape
+        The shape to inspect.
+
+    Returns
+    -------
+    type[Enum] or None
+        The `Enum` class when `shape` is a `Primitive` backed by one,
+        `None` otherwise.
+    """
+    if not isinstance(shape, Primitive):
+        return None
+    src = shape.source_type
+    if isinstance(src, type) and issubclass(src, Enum):
+        return src
+    return None
+
+
+def shape_children(shape: FieldShape) -> Iterator[FieldShape]:
+    """Yield direct child shapes within *shape* (one level deep).
+
+    `Scalar`, `ModelRef`, and `UnionRef` have no children.
+    """
+    match shape:
+        case ArrayOf(element=element):
+            yield element
+        case MapOf(key=key, value=value):
+            yield key
+            yield value
+        case NewTypeShape(inner=inner):
+            yield inner
+        case Primitive() | LiteralScalar() | AnyScalar() | ModelRef() | UnionRef():
+            return
+        case _:
+            assert_never(shape)
+
+
+def walk_shape(shape: FieldShape, visit: Callable[[FieldShape], None]) -> None:
+    """Pre-order traversal of a `FieldShape` tree.
+
+    Visits *shape*, then descends into each direct child via
+    `shape_children`. Stops at `ModelRef` / `UnionRef` -- recursion
+    across model boundaries is the caller's choice.
+    """
+    visit(shape)
+    for child in shape_children(shape):
+        walk_shape(child, visit)
+
+
+def list_depth(shape: FieldShape) -> int:
+    """Total number of `ArrayOf` layers in *shape*, looking through `NewTypeShape`.
+
+    A NewType wrapping a list counts the same as a list wrapping a
+    NewType.
+    """
+    depth = 0
+    cur = shape
+    while True:
+        match cur:
+            case ArrayOf(element=element):
+                depth += 1
+                cur = element
+            case NewTypeShape(inner=inner):
+                cur = inner
+            case (
+                Primitive()
+                | LiteralScalar()
+                | AnyScalar()
+                | ModelRef()
+                | UnionRef()
+                | MapOf()
+            ):
+                return depth
+            case _:
+                assert_never(cur)
+
+
+def has_array_layer(shape: FieldShape) -> bool:
+    """Whether *shape* has any `ArrayOf` layer, looking through `NewTypeShape`.
+
+    Prefer this over `list_depth(shape) > 0` -- callers that only need
+    "is this array-shaped" don't need to count layers.
+    """
+    cur = shape
+    while isinstance(cur, NewTypeShape):
+        cur = cur.inner
+    return isinstance(cur, ArrayOf)
+
+
+def newtype_name(shape: FieldShape) -> str | None:
+    """Return the outermost `NewTypeShape` name, looking through `ArrayOf` layers."""
+    cur: FieldShape = shape
+    while isinstance(cur, ArrayOf):
+        cur = cur.element
+    match cur:
+        case NewTypeShape(name=name):
+            return name
+        case (
+            Primitive()
+            | LiteralScalar()
+            | AnyScalar()
+            | ModelRef()
+            | UnionRef()
+            | MapOf()
+        ):
+            return None
+        case _:
+            assert_never(cur)
+
+
+def all_constraints(shape: FieldShape) -> tuple[ConstraintSource, ...]:
+    """Concatenate the field's own constraints from every layer of *shape*.
+
+    Walks `NewTypeShape` and `ArrayOf` wrappers to gather constraints
+    that apply to this field. Stops at `MapOf` (key/value constraints
+    belong to nested key/value shapes, not to the enclosing field) and
+    at `ModelRef` / `UnionRef` (which carry no constraints). Constraints
+    from outer `ArrayOf` layers appear before constraints from inner
+    layers, matching the structural order of the shape tree.
+    """
+    collected: list[ConstraintSource] = []
+    cur = shape
+    while True:
+        match cur:
+            case ArrayOf(element=inner, constraints=cs):
+                collected.extend(cs)
+                cur = inner
+            case NewTypeShape(inner=inner):
+                cur = inner
+            case (
+                Primitive(constraints=cs)
+                | LiteralScalar(constraints=cs)
+                | AnyScalar(constraints=cs)
+            ):
+                collected.extend(cs)
+                return tuple(collected)
+            case MapOf(constraints=cs):
+                collected.extend(cs)
+                return tuple(collected)
+            case ModelRef() | UnionRef():
+                return tuple(collected)
+            case _:
+                assert_never(cur)
+
+
+def map_key_value_constraints(
+    shape: FieldShape,
+) -> tuple[tuple[ConstraintSource, ...], tuple[ConstraintSource, ...]]:
+    """Return a `MapOf` terminal's (key_constraints, value_constraints), or `((), ())`.
+
+    Looks through `NewTypeShape` / `ArrayOf` wrappers to find a `MapOf`,
+    then gathers each side's constraints with `all_constraints`. This
+    surfaces per-key and per-value rules that `all_constraints` on the
+    enclosing field deliberately stops short of (it treats `MapOf` as a
+    terminal). Returns `((), ())` when *shape* has no `MapOf` terminal.
+    """
+    cur = shape
+    while True:
+        match cur:
+            case NewTypeShape(inner=inner) | ArrayOf(element=inner):
+                cur = inner
+            case MapOf(key=key, value=value):
+                return all_constraints(key), all_constraints(value)
+            case _:
+                return (), ()

overture/schema/codegen/extraction/length_constraints.py

@@ -0,0 +1,49 @@
+"""Internal typed length-constraint classes.
+
+`annotated_types.MaxLen` and `annotated_types.MinLen` are polysemous:
+`MaxLen(10)` on a `str` constrains character count, while `MaxLen(10)`
+on a `list[X]` constrains cardinality. The codegen extractor splits
+them by attachment layer so each variant carries its own dispatch:
+`ArrayMinLen` / `ArrayMaxLen` for `ArrayOf` layers, `ScalarMinLen` /
+`ScalarMaxLen` for scalar layers.
+
+These are codegen-internal classes -- schema authors continue to write
+the normal Pydantic form (`Field(min_length=n)` / `Field(max_length=n)`),
+which Pydantic lowers into the `annotated_types.MinLen` / `MaxLen`
+metadata described above. The wrapping into these layer-typed variants
+happens inside `type_analyzer.attach_constraints` when the constraint
+reaches its target layer.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from annotated_types import MaxLen, MinLen
+
+__all__ = [
+    "ArrayMaxLen",
+    "ArrayMinLen",
+    "ScalarMaxLen",
+    "ScalarMinLen",
+]
+
+
+@dataclass(frozen=True)
+class ArrayMinLen(MinLen):
+    """Cardinality lower bound for an `ArrayOf` layer."""
+
+
+@dataclass(frozen=True)
+class ArrayMaxLen(MaxLen):
+    """Cardinality upper bound for an `ArrayOf` layer."""
+
+
+@dataclass(frozen=True)
+class ScalarMinLen(MinLen):
+    """Character-count lower bound for a scalar layer."""
+
+
+@dataclass(frozen=True)
+class ScalarMaxLen(MaxLen):
+    """Character-count upper bound for a scalar layer."""