dataeval-flow 0.1.0__py3-none-any.whl

dataeval_flow/_app/_model/_introspect.py

@@ -0,0 +1,280 @@
+"""Pydantic schema introspection for dynamic form generation.
+
+Walks Pydantic model fields and produces ``FieldDescriptor`` objects that
+the TUI can render as appropriate widgets (inputs, selects, checkboxes, etc.)
+without hard-coding knowledge of each workflow's parameter model.
+"""
+
+from __future__ import annotations
+
+import collections.abc
+import typing
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, get_args, get_origin
+
+from pydantic import BaseModel
+from pydantic.fields import FieldInfo
+from pydantic_core import PydanticUndefinedType
+
+
+class FieldKind(Enum):
+    """Widget hint for the TUI layer."""
+
+    STRING = "string"
+    INT = "int"
+    FLOAT = "float"
+    BOOL = "bool"
+    SELECT = "select"
+    MULTI_SELECT = "multi_select"
+    NESTED = "nested"
+    LIST = "list"
+
+
+@dataclass
+class FieldDescriptor:
+    """Metadata extracted from a single Pydantic field."""
+
+    name: str
+    kind: FieldKind
+    description: str
+    required: bool
+    default: Any = None
+    choices: list[str] = field(default_factory=list)
+    constraints: dict[str, Any] = field(default_factory=dict)
+    nested_model: type[BaseModel] | None = None
+    item_descriptors: list[FieldDescriptor] | None = None  # for lists of nested models
+    discriminator: str | None = None  # for discriminated unions
+    union_variants: dict[str, type[BaseModel]] | None = None  # discriminator value -> model
+
+
+def _unwrap_optional(annotation: Any) -> tuple[Any, bool]:
+    """Strip ``Optional[X]`` / ``X | None`` and return (inner_type, is_optional)."""
+    import types
+
+    origin = get_origin(annotation)
+    if origin is typing.Union or isinstance(annotation, types.UnionType):
+        args = [a for a in get_args(annotation) if a is not type(None)]
+        if len(args) == 1:
+            return args[0], True
+        return annotation, False
+    return annotation, False
+
+
+def _extract_literal_values(annotation: Any) -> list[str] | None:
+    """Return literal values if annotation is ``Literal[...]``."""
+    if get_origin(annotation) is typing.Literal:
+        return [str(v) for v in get_args(annotation)]
+    return None
+
+
+def _is_pydantic_model(tp: Any) -> bool:
+    return isinstance(tp, type) and issubclass(tp, BaseModel)
+
+
+def _extract_constraints(field_info: FieldInfo) -> dict[str, Any]:
+    """Pull numeric constraints (ge, le, gt, lt) from field metadata."""
+    constraints: dict[str, Any] = {}
+    for meta in field_info.metadata:
+        for attr in ("ge", "le", "gt", "lt", "min_length", "max_length"):
+            val = getattr(meta, attr, None)
+            if val is not None:
+                constraints[attr] = val
+    return constraints
+
+
+def _resolve_discriminated_union(
+    annotation: Any,
+    field_info: FieldInfo,
+) -> tuple[str | None, dict[str, type[BaseModel]] | None]:
+    """Detect discriminated unions and return (discriminator_field, {value: model})."""
+    disc = field_info.discriminator
+    if disc is None:
+        return None, None
+
+    disc_field = disc if isinstance(disc, str) else None
+    if disc_field is None:
+        return None, None
+
+    # The annotation is Annotated[Union[A, B, ...], Field(discriminator=...)]
+    inner = annotation
+    if get_origin(annotation) is typing.Annotated:
+        inner = get_args(annotation)[0]
+
+    import types as _types
+
+    union_args = get_args(inner) if (get_origin(inner) is typing.Union or isinstance(inner, _types.UnionType)) else []
+    variants: dict[str, type[BaseModel]] = {}
+    for variant in union_args:
+        if _is_pydantic_model(variant):
+            disc_info = variant.model_fields.get(disc_field)
+            if disc_info and disc_info.default is not None:
+                variants[str(disc_info.default)] = variant
+
+    return disc_field, variants if variants else None
+
+
+_PRIMITIVE_KINDS: dict[type, FieldKind] = {
+    bool: FieldKind.BOOL,
+    int: FieldKind.INT,
+    float: FieldKind.FLOAT,
+}
+
+
+def _introspect_list_field(
+    inner: Any,
+    name: str,
+    description: str,
+    required: bool,
+    default: Any,
+    constraints: dict[str, Any],
+) -> FieldDescriptor | None:
+    """Attempt to classify a list/Sequence annotation, returning a descriptor or None."""
+    list_args = get_args(inner)
+    if list_args:
+        list_inner = list_args[0]
+        list_literals = _extract_literal_values(list_inner)
+        if list_literals:
+            return FieldDescriptor(
+                name=name,
+                kind=FieldKind.MULTI_SELECT,
+                description=description,
+                required=required,
+                default=default,
+                choices=list_literals,
+                constraints=constraints,
+            )
+        if _is_pydantic_model(list_inner):
+            return FieldDescriptor(
+                name=name,
+                kind=FieldKind.LIST,
+                description=description,
+                required=required,
+                default=default,
+                nested_model=list_inner,
+                constraints=constraints,
+            )
+    # Check for list of discriminated union
+    if list_args and get_origin(list_args[0]) is typing.Annotated:
+        ann_args = get_args(list_args[0])
+        union_type = ann_args[0]
+        field_meta = [a for a in ann_args[1:] if isinstance(a, FieldInfo)]
+        import types as _types
+
+        if field_meta and (get_origin(union_type) is typing.Union or isinstance(union_type, _types.UnionType)):
+            d_field, d_variants = _resolve_discriminated_union(list_args[0], field_meta[0])
+            if d_field and d_variants:
+                return FieldDescriptor(
+                    name=name,
+                    kind=FieldKind.LIST,
+                    description=description,
+                    required=required,
+                    default=default,
+                    discriminator=d_field,
+                    union_variants=d_variants,
+                    constraints=constraints,
+                )
+    return None
+
+
+def introspect_model(model: type[BaseModel]) -> list[FieldDescriptor]:
+    """Walk a Pydantic model and return field descriptors for each field."""
+    descriptors: list[FieldDescriptor] = []
+
+    for name, field_info in model.model_fields.items():
+        annotation = field_info.annotation
+        if annotation is None:
+            continue
+
+        inner, is_optional = _unwrap_optional(annotation)
+
+        required = field_info.is_required()
+        raw_default = field_info.default
+        default = None if required or isinstance(raw_default, PydanticUndefinedType) else raw_default
+        description = field_info.description or ""
+        constraints = _extract_constraints(field_info)
+
+        # Check for discriminated union first
+        disc_field, union_variants = _resolve_discriminated_union(annotation, field_info)
+        if disc_field and union_variants:
+            descriptors.append(
+                FieldDescriptor(
+                    name=name,
+                    kind=FieldKind.NESTED,
+                    description=description,
+                    required=required,
+                    default=default,
+                    discriminator=disc_field,
+                    union_variants=union_variants,
+                )
+            )
+            continue
+
+        # Literal -> select
+        literal_vals = _extract_literal_values(inner)
+        if literal_vals:
+            descriptors.append(
+                FieldDescriptor(
+                    name=name,
+                    kind=FieldKind.SELECT,
+                    description=description,
+                    required=required,
+                    default=str(default) if default is not None else None,
+                    choices=literal_vals,
+                    constraints=constraints,
+                )
+            )
+            continue
+
+        # list[...] / Sequence[...]
+        if get_origin(inner) in (list, collections.abc.Sequence):
+            list_desc = _introspect_list_field(inner, name, description, required, default, constraints)
+            if list_desc:
+                descriptors.append(list_desc)
+                continue
+            # Plain list
+            descriptors.append(
+                FieldDescriptor(
+                    name=name,
+                    kind=FieldKind.LIST,
+                    description=description,
+                    required=required,
+                    default=default,
+                    constraints=constraints,
+                )
+            )
+            continue
+
+        # Nested BaseModel
+        if _is_pydantic_model(inner):
+            sub_descs = introspect_model(inner)
+            expandable_kinds = {FieldKind.BOOL, FieldKind.INT, FieldKind.FLOAT, FieldKind.STRING, FieldKind.SELECT}
+            expandable = sub_descs and all(d.kind in expandable_kinds and not d.required for d in sub_descs)
+            descriptors.append(
+                FieldDescriptor(
+                    name=name,
+                    kind=FieldKind.NESTED,
+                    description=description,
+                    required=required,
+                    default=default,
+                    nested_model=inner,
+                    constraints=constraints,
+                    item_descriptors=sub_descs if expandable else None,
+                )
+            )
+            continue
+
+        # Primitives
+        kind = _PRIMITIVE_KINDS.get(inner, FieldKind.STRING)
+        descriptors.append(
+            FieldDescriptor(
+                name=name,
+                kind=kind,
+                description=description,
+                required=required,
+                default=default,
+                constraints=constraints,
+            )
+        )
+
+    return descriptors

dataeval_flow/_app/_model/_item.py

@@ -0,0 +1,213 @@
+"""Item assembly, field collection, step-builder validation/coercion, and action constants.
+
+Pure functions shared by both the TUI and CLI for building config item
+dicts, collecting/coercing field values, and validating step parameters.
+No UI or state dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from dataeval_flow._app._model._coerce import (
+    _split_type_alternatives,
+    coerce_field_value,
+    coerce_value,
+    validate_value,
+)
+from dataeval_flow._app._model._introspect import FieldDescriptor
+from dataeval_flow._app._model._registry import (
+    STEP_BUILDER_SECTIONS,
+    get_discriminator_field,
+)
+
+__all__ = [
+    "DELETE_SENTINEL",
+    "SKIP",
+    "build_item_dict",
+    "coerce_step_params",
+    "collect_field_value",
+    "collect_multi_select_value",
+    "diagnose_collect_failure",
+    "finalize_item",
+    "validate_step_params",
+]
+
+# Sentinel indicating a field value should be omitted from the result dict.
+SKIP = object()
+
+# ---------------------------------------------------------------------------
+# Sentinel for delete actions
+# ---------------------------------------------------------------------------
+
+DELETE_SENTINEL = "__DELETE__"
+
+
+# ---------------------------------------------------------------------------
+# Item assembly helpers
+# ---------------------------------------------------------------------------
+
+
+def finalize_item(section: str, item: dict[str, Any]) -> dict[str, Any]:
+    """Apply section-specific defaults to an assembled item dict.
+
+    Currently handles tasks defaulting to ``enabled=True``.
+    """
+    if section == "tasks":
+        item.setdefault("enabled", True)
+    return item
+
+
+def build_item_dict(
+    section: str,
+    name: str,
+    variant_value: str | None,
+    field_values: dict[str, Any],
+) -> dict[str, Any]:
+    """Assemble a config item dict from its component parts.
+
+    Combines name, discriminator, and field values into a single dict,
+    then applies section-specific defaults via :func:`finalize_item`.
+    """
+    item: dict[str, Any] = {"name": name}
+    disc_field = get_discriminator_field(section)
+    if disc_field and variant_value:
+        item[disc_field] = variant_value
+    item.update(field_values)
+    return finalize_item(section, item)
+
+
+# ---------------------------------------------------------------------------
+# Step-builder validation and coercion (pure functions)
+# ---------------------------------------------------------------------------
+
+
+def validate_step_params(params: list[Any], values: dict[str, str | bool | None]) -> list[str]:
+    """Validate step parameter values. Returns a list of error messages.
+
+    *params* is a list of ``ParamInfo``-like objects with ``name``,
+    ``type_hint``, ``required``, and ``choices`` attributes.
+    *values* maps param names to raw string values (or ``None``).
+    Params whose name is not in *values* are skipped (widget not found).
+    """
+    errors: list[str] = []
+    for p in params:
+        if p.name not in values:
+            continue
+        val = values.get(p.name)
+        if p.choices:
+            if p.required and not val:
+                errors.append(f"'{p.name}' is required (select a value).")
+        elif p.type_hint == "bool":
+            pass  # booleans are always valid
+        else:
+            if p.required and not val:
+                errors.append(f"'{p.name}' is required.")
+            elif val:
+                val_str = str(val)
+                alternatives = _split_type_alternatives(p.type_hint)
+                if not any(validate_value(val_str, alt) for alt in alternatives):
+                    expected = " or ".join(alternatives)
+                    errors.append(f"'{p.name}' must be {expected} (got '{val_str}').")
+    return errors
+
+
+def coerce_step_params(params: list[Any], values: dict[str, str | bool | None]) -> dict[str, Any]:
+    """Coerce raw string values for step parameters. Returns the result dict.
+
+    *params* is a list of ``ParamInfo``-like objects.
+    *values* maps param names to raw string values (or ``None``).
+    Params whose name is not in *values* are skipped (widget not found).
+    """
+    result: dict[str, Any] = {}
+    for p in params:
+        if p.name not in values:
+            continue
+        val = values.get(p.name)
+        if p.choices:
+            if val:
+                result[p.name] = val
+        elif p.type_hint == "bool":
+            bool_val = values.get(p.name)
+            if isinstance(bool_val, bool):
+                default = p.default if isinstance(p.default, bool) else False
+                if bool_val != default:
+                    result[p.name] = bool_val
+        else:
+            if val:
+                result[p.name] = coerce_value(str(val), p.type_hint)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Field value collection (pure logic, no widget access)
+# ---------------------------------------------------------------------------
+
+
+def collect_field_value(desc: FieldDescriptor, raw: str) -> Any:
+    """Coerce a raw string from a widget into a typed value.
+
+    Returns :data:`SKIP` if the value is empty/should be omitted.
+    """
+    if not raw:
+        return SKIP
+    return coerce_field_value(raw, desc)
+
+
+def collect_json_value(raw: str) -> Any:
+    """Parse a raw JSON string. Returns :data:`SKIP` if empty."""
+    if not raw:
+        return SKIP
+    try:
+        return json.loads(raw)
+    except (ValueError, TypeError):
+        return raw
+
+
+def collect_multi_select_value(
+    selected: list[str],
+    section: str,
+    field_name: str,
+) -> Any:
+    """Process a multi-select result. Returns :data:`SKIP` if empty.
+
+    For task sources, a single-element list is unwrapped to a plain string.
+    """
+    if not selected:
+        return SKIP
+    if len(selected) == 1 and section == "tasks" and field_name == "sources":
+        return selected[0]
+    return selected
+
+
+def collect_bool_value(value: bool, default: Any) -> Any:
+    """Return *value* if it differs from *default*, otherwise :data:`SKIP`."""
+    resolved_default = default if isinstance(default, bool) else False
+    return value if value != resolved_default else SKIP
+
+
+# ---------------------------------------------------------------------------
+# Validation error diagnosis (pure logic)
+# ---------------------------------------------------------------------------
+
+
+def diagnose_collect_failure(
+    section: str,
+    name: str,
+    steps: list[dict[str, Any]],
+    descriptors: list[FieldDescriptor],
+    result: dict[str, Any] | None,
+) -> str:
+    """Return a human-readable error message when ``_collect_raw`` returns None."""
+    if not name:
+        return "Name is required."
+    if section in STEP_BUILDER_SECTIONS and not steps:
+        return "Add at least one step."
+    disc_field = get_discriminator_field(section)
+    if disc_field:
+        return f"{disc_field.replace('_', ' ')} is required."
+    missing = [d.name for d in descriptors if d.required and d.name not in (result or {})]
+    if missing:
+        return f"Required: {', '.join(missing)}"
+    return "Invalid input."