metaobjects 0.9.0__py3-none-any.whl

metaobjects/render/extract/coerce.py

@@ -0,0 +1,279 @@
+"""Stage 7: canonicalize a raw scalar string per its FieldSpec.
+
+Returns the ``MALFORMED`` sentinel when the value is present but uncoercible.
+
+Cross-port number rules (parity with C#/TS, an accepted divergence from Java):
+
+- Non-finite (NaN / ±Infinity) → MALFORMED.
+- Radix-prefixed strings (``0x..`` / ``0b..`` / ``0o..``) are REJECTED. Python's
+  ``int(s, 0)`` would accept them but Java's ``Long.parseLong`` / C#'s
+  ``long.TryParse`` reject them — so the C# and TS ports added this guard; we match.
+- We do NOT replicate Java's ``Double.parseDouble`` suffix tolerance
+  (``"42d"`` / hex-float) — documented accepted divergence (same as C#/TS).
+"""
+from __future__ import annotations
+
+import math
+import re
+from typing import Final
+
+from metaobjects.render.extract.normalize import NONE as _NORMALIZE_NONE
+from metaobjects.render.extract.normalize import normalize_enum
+from metaobjects.render.extract.types import (
+    Coercion,
+    FieldKind,
+    FieldSpec,
+    ExtractOptions,
+    ExtractionReport,
+    Tolerance,
+)
+
+# Sentinel: the value was present but could not be coerced to the declared kind/vocabulary.
+MALFORMED: Final = object()
+
+# A canonical ASCII numeric literal (int / decimal / scientific). Python's int()/float()
+# are far more permissive than Java/C# numeric parsing — they accept underscore digit
+# grouping ("1_000", PEP 515), Unicode digits ("１２３"), and radix prefixes ("0x10"). Gating
+# on this ASCII-only pattern rejects all of those → MALFORMED, matching the strict cross-port
+# behavior (C#'s TryParse). `[0-9]` (not `\d`) keeps it ASCII-only.
+_ASCII_NUMERIC = re.compile(r"^[+-]?(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$")
+
+
+def value(
+    raw: str | None,
+    spec: FieldSpec,
+    opts: ExtractOptions,
+    field_path: str,
+    report: ExtractionReport,
+) -> object:
+    """Canonicalize ``raw`` to the native type described by ``spec``, or MALFORMED."""
+    if raw is None:
+        return MALFORMED
+
+    # OnField hook takes priority.
+    if opts.on_field is not None:
+        hooked = opts.on_field(field_path, raw, spec)
+        if hooked is not None:
+            report.add_coercion(Coercion(field_path, raw, str(hooked), "onField"))
+            return hooked
+
+    # Per-field runtime normalizer (bounded 20% surface). Keyed by path, then simple name.
+    norm = opts.normalizers.get(field_path)
+    if norm is None:
+        norm = opts.normalizers.get(spec.name)
+    if norm is not None:
+        normalized = norm(raw)
+        if normalized is not None:
+            report.add_coercion(Coercion(field_path, raw, str(normalized), "normalizer"))
+            return normalized
+
+    ci = opts.tolerance != Tolerance.STRICT
+    match spec.kind:
+        case FieldKind.ENUM:
+            return _coerce_enum(raw, spec, opts, field_path, report, ci)
+        case FieldKind.INT | FieldKind.LONG:
+            return _coerce_int(raw, spec, field_path, report, ci)
+        case FieldKind.DOUBLE:
+            return _coerce_double(raw, spec, field_path, report, ci)
+        case FieldKind.BOOLEAN:
+            return _coerce_bool(raw, ci)
+        case _:
+            return raw
+
+
+def scalar_coerce(raw: str | None, spec: FieldSpec) -> object:
+    """Phase B (generalized ``@default``): coerce a non-enum default string to a
+    field's scalar kind, with NO side effects (no normalizer/on_field hooks, no
+    clamp logging) — the value originates from metadata, not the model response.
+
+    Returns the coerced value or the ``MALFORMED`` sentinel. INT/LONG accept an
+    integer or a truncatable finite number; DOUBLE accepts any finite number;
+    BOOLEAN accepts ``true|false|yes|no|1|0``; STRING (and any other kind) passes
+    through verbatim. Mirrors the parse semantics of :func:`value` without its
+    range-clamp / report machinery (Java ``Coerce.scalar``).
+    """
+    if raw is None:
+        return MALFORMED
+    match spec.kind:
+        case FieldKind.INT | FieldKind.LONG:
+            trimmed = raw.strip()
+            if not _ASCII_NUMERIC.match(trimmed):
+                return MALFORMED
+            try:
+                return int(trimmed)
+            except ValueError:
+                pass
+            try:
+                d = float(trimmed)
+            except ValueError:
+                return MALFORMED
+            return math.trunc(d) if math.isfinite(d) else MALFORMED
+        case FieldKind.DOUBLE:
+            trimmed = raw.strip()
+            if not _ASCII_NUMERIC.match(trimmed):
+                return MALFORMED
+            try:
+                d = float(trimmed)
+            except ValueError:
+                return MALFORMED
+            return d if math.isfinite(d) else MALFORMED
+        case FieldKind.BOOLEAN:
+            t = raw.strip().lower()
+            if t in ("true", "yes", "1"):
+                return True
+            if t in ("false", "no", "0"):
+                return False
+            return MALFORMED
+        case _:
+            return raw  # STRING / ENUM / OBJECT — verbatim
+
+
+def _coerce_enum(
+    raw: str,
+    spec: FieldSpec,
+    opts: ExtractOptions,
+    path: str,
+    report: ExtractionReport,
+    ci: bool,
+) -> object:
+    """FR-011 enum coercion pipeline: exact → normalize → ``@enumAlias`` →
+    (reserved fuzzy) → ``@coerceDefault`` → MALFORMED.
+
+    Resolution mode is ``spec.normalize`` (default ``"strip"``); under STRICT
+    tolerance (``ci`` is False) normalization is forced to ``"none"`` (exact-only),
+    preserving the case-sensitive STRICT contract. The FR-010 case-insensitive
+    default is now mode ``"strip"``. Mirrors the TS/C#/Java ``coerceEnum``.
+    """
+    mode = spec.normalize if ci else _NORMALIZE_NONE
+
+    # 1. exact match.
+    if spec.enum_values is not None:
+        for v in spec.enum_values:
+            if v == raw:
+                return v
+
+    # 2. normalized match (skipped when mode == none).
+    if mode != _NORMALIZE_NONE and spec.enum_values is not None:
+        norm_raw = normalize_enum(raw, mode)
+        for v in spec.enum_values:
+            if normalize_enum(v, mode) == norm_raw:
+                report.add_coercion(Coercion(path, raw, v, "normalize"))
+                return v
+
+    # 3. @enumAlias — runtime aliases win over schema; alias keys matched under the mode.
+    runtime_target = _lookup_alias_in(raw, opts.aliases, mode)
+    if runtime_target is not None:
+        schema_target = _lookup_alias_in(raw, spec.enum_alias, mode)
+        kind = (
+            "runtime-alias-override"
+            if schema_target is not None and schema_target != runtime_target
+            else "alias"
+        )
+        report.add_coercion(Coercion(path, raw, runtime_target, kind))
+        return runtime_target
+    schema_target = _lookup_alias_in(raw, spec.enum_alias, mode)
+    if schema_target is not None:
+        report.add_coercion(Coercion(path, raw, schema_target, "alias"))
+        return schema_target
+
+    # 4. reserved fuzzy slot — NOT implemented (FR-011 spec "Out of scope").
+
+    # 5. @coerceDefault — present-but-uncoercible fallback to a valid member → DEFAULTED.
+    if (
+        spec.coerce_default is not None
+        and spec.enum_values is not None
+        and spec.coerce_default in spec.enum_values
+    ):
+        report.add_coercion(Coercion(path, raw, spec.coerce_default, "coerceDefault"))
+        return spec.coerce_default
+
+    # 6. MALFORMED.
+    return MALFORMED
+
+
+def _lookup_alias_in(raw: str, aliases: dict[str, str] | None, mode: str) -> str | None:
+    """Find ``raw`` in an alias map, matching keys exactly first then under ``mode``
+    normalization. Returns the target member, or ``None`` when no key matches."""
+    if not aliases:
+        return None
+    exact = aliases.get(raw)
+    if exact is not None:
+        return exact
+    if mode == _NORMALIZE_NONE:
+        return None
+    norm_raw = normalize_enum(raw, mode)
+    for key, target in aliases.items():
+        if normalize_enum(key, mode) == norm_raw:
+            return target
+    return None
+
+
+def _coerce_int(
+    raw: str, spec: FieldSpec, path: str, report: ExtractionReport, lenient: bool
+) -> object:
+    trimmed = raw.strip()
+    if not _ASCII_NUMERIC.match(trimmed):
+        return MALFORMED
+    # Integer parse first (matches Java Long.parseLong / C# long.TryParse), then a
+    # float fallback (matches Java's Double.parseDouble fallback).
+    try:
+        return _clamp(float(int(trimmed)), spec, path, report, as_long=True, lenient=lenient)
+    except ValueError:
+        pass
+    try:
+        d = float(trimmed)
+    except ValueError:
+        return MALFORMED
+    return _clamp(d, spec, path, report, as_long=True, lenient=lenient)
+
+
+def _coerce_double(
+    raw: str, spec: FieldSpec, path: str, report: ExtractionReport, lenient: bool
+) -> object:
+    trimmed = raw.strip()
+    if not _ASCII_NUMERIC.match(trimmed):
+        return MALFORMED
+    try:
+        d = float(trimmed)
+    except ValueError:
+        return MALFORMED
+    return _clamp(d, spec, path, report, as_long=False, lenient=lenient)
+
+
+def _clamp(
+    n: float, spec: FieldSpec, path: str, report: ExtractionReport, as_long: bool, lenient: bool
+) -> object:
+    """Apply the field's @min/@max range (sourced from its numeric validator). Under LENIENT
+    tolerance an out-of-range value is CLAMPED to the bound (recorded as a "clamp" coercion);
+    under STRICT tolerance it is MALFORMED (the validator's "value out of range" contract).
+    Cross-port: ports must match the lenient-clamp / strict-reject split."""
+    # Non-finite (NaN, ±Infinity) → MALFORMED (cross-port classification parity).
+    if not math.isfinite(n):
+        return MALFORMED
+    c = n
+    if spec.min is not None and c < spec.min:
+        c = spec.min
+    if spec.max is not None and c > spec.max:
+        c = spec.max
+    if c != n:
+        if not lenient:  # STRICT: out-of-range is invalid, not silently clamped
+            return MALFORMED
+        report.add_coercion(Coercion(path, _num_str(n), _num_str(c), "clamp"))
+    # Truncate toward zero for integer kinds (math.trunc / int()).
+    return math.trunc(c) if as_long else c
+
+
+def _num_str(n: float) -> str:
+    # Render integral floats without a trailing ".0" to read like Java/C# longs in notes.
+    if n == math.trunc(n) and math.isfinite(n):
+        return str(int(n))
+    return str(n)
+
+
+def _coerce_bool(raw: str, ci: bool) -> object:
+    t = raw.strip().lower() if ci else raw.strip()
+    if t in ("true", "yes", "1"):
+        return True
+    if t in ("false", "no", "0"):
+        return False
+    return MALFORMED

metaobjects/render/extract/extract.py

@@ -0,0 +1,211 @@
+"""Public entry point. Runs the extract pipeline; never throws."""
+from __future__ import annotations
+
+from metaobjects.render.extract import coerce as _coerce
+from metaobjects.render.extract import locate as _locate
+from metaobjects.render.extract import strip as _strip
+from metaobjects.render.extract.coerce import MALFORMED
+from metaobjects.render.extract.json_forgiving_reader import (
+    NULL_LITERAL,
+    TRUNCATED,
+    JsonForgivingReader,
+)
+from metaobjects.render.extract.types import (
+    Coercion,
+    FieldKind,
+    FieldExtraction,
+    FieldSpec,
+    Format,
+    ExtractOptions,
+    ExtractionOutcome,
+    ExtractSchema,
+    ExtractionReport,
+    Tolerance,
+)
+from metaobjects.render.extract.xml_forgiving_reader import TEXT_KEY, XmlForgivingReader
+
+
+def extract(
+    text: str | None,
+    schema: ExtractSchema,
+    opts: ExtractOptions | None = None,
+) -> ExtractionOutcome:
+    """Extract structured data from dirty ``text`` per ``schema``. Never raises."""
+    o = ExtractOptions.defaults() if opts is None else opts
+    report = ExtractionReport()
+    data: dict[str, object] = {}
+
+    stripped = _strip.strip(text)
+    ci = o.tolerance != Tolerance.STRICT
+
+    # XML rootless (opts.rootless): the payload's fields ARE the top-level elements — there
+    # is no enclosing root to locate — so parse the whole stripped text's top-level elements
+    # directly. Otherwise locate the <rootName> span as before. JSON is unaffected. Mirrors
+    # Java Extract.extract.
+    span: str | None
+    raw: dict[str, object]
+    if schema.format == Format.JSON:
+        span = _locate.json(stripped)
+        raw = {} if span is None else JsonForgivingReader().read(span)
+    elif o.rootless:
+        span = None if stripped == "" else stripped
+        raw = {} if span is None else XmlForgivingReader().read_rootless(stripped, ci)
+    else:
+        span = _locate.xml(stripped, schema.root_name, ci)
+        raw = {} if span is None else XmlForgivingReader().read(span, ci)
+
+    if not raw and (stripped == "" or span is None):
+        report.mark_empty()
+
+    _extract(schema.fields, raw, "", data, report, o, ci)
+    return ExtractionOutcome(data=data, report=report)
+
+
+def _extract(
+    fields: list[FieldSpec],
+    raw: dict[str, object],
+    prefix: str,
+    data: dict[str, object],
+    report: ExtractionReport,
+    o: ExtractOptions,
+    ci: bool,
+) -> None:
+    for f in fields:
+        path = f.name if prefix == "" else prefix + "." + f.name
+        # A @xmlText field reads the element's text body (carried under the #text sentinel when
+        # the element also has attributes), not a same-named child element.
+        present = raw.get(TEXT_KEY) if f.text_content else _lookup(raw, f.name, ci)
+        if present is None:
+            # FR-011 / Phase B: an absent field with a declared @default fills the
+            # value → DEFAULTED (which satisfies a @required field). Generalized to
+            # all field kinds: an enum default is its member string verbatim; a
+            # non-enum default is coerced to the field's kind via the PURE
+            # scalar_coerce (so @default "0" on field.int yields integer 0). A
+            # non-coercible non-enum default is treated as no default.
+            if f.default_value is not None:
+                coerced = (
+                    f.default_value
+                    if f.kind == FieldKind.ENUM
+                    else _coerce.scalar_coerce(f.default_value, f)
+                )
+                if coerced is not MALFORMED:
+                    data[f.name] = coerced
+                    report.add_coercion(Coercion(path, "", f.default_value, "default"))
+                    report.set(path, FieldExtraction.DEFAULTED)
+                    continue
+            report.set(
+                path,
+                FieldExtraction.LOST_REQUIRED if f.required else FieldExtraction.LOST_OPTIONAL,
+            )
+            continue
+        if present is TRUNCATED:  # present-but-garbled (empty/cut-off value)
+            report.set(path, FieldExtraction.MALFORMED)
+            continue
+        if present is NULL_LITERAL:
+            # The JSON null literal is the caller's explicit "no value": leave the field null
+            # (do NOT apply @default — an explicit null is a value, not an omission), matching a
+            # standard JSON bind. Without this the bare ``null`` token leaks as the string "null".
+            report.set(
+                path,
+                FieldExtraction.LOST_REQUIRED if f.required else FieldExtraction.LOST_OPTIONAL,
+            )
+            continue
+        if f.array:
+            # A single non-list value is treated as a one-element array (e.g. a single
+            # repeated-XML tag). Each element is coerced/recursed independently.
+            elements = present if isinstance(present, list) else [present]
+            out: list[object] = []
+            any_malformed = False
+            # Phase B (array-of-enum): an enum element flows through the SAME enum
+            # coercion pipeline a scalar enum uses (_extract_value → coerce.value →
+            # _coerce_enum) and is CLASSIFIED per element by indexed path (tags[0],
+            # tags[1], …) exactly as a scalar enum: EXTRACTED / DEFAULTED (via
+            # @coerceDefault) / MALFORMED. Non-enum scalar arrays keep their existing
+            # behavior (coerced element list, no per-element states).
+            enum_elements = f.kind == FieldKind.ENUM
+            for idx, el in enumerate(elements):
+                elem_path = f"{path}[{idx}]"
+                v = _extract_value(f, el, elem_path, report, o, ci)
+                if v is MALFORMED:
+                    any_malformed = True
+                    if enum_elements:
+                        report.set(elem_path, FieldExtraction.MALFORMED)
+                else:
+                    out.append(v)
+                    if enum_elements:
+                        report.set(elem_path, _classify_coerced(elem_path, report))
+            # Cross-port contract: a MALFORMED array still places its successfully-coerced
+            # elements into data (partial extraction), UNLIKE a MALFORMED scalar which is
+            # absent from data.
+            data[f.name] = out
+            report.set(
+                path, FieldExtraction.MALFORMED if any_malformed else FieldExtraction.EXTRACTED
+            )
+            continue
+        if isinstance(present, list):  # a list where a singular value was expected
+            report.set(path, FieldExtraction.MALFORMED)
+            continue
+        v = _extract_value(f, present, path, report, o, ci)
+        if v is MALFORMED:
+            report.set(path, FieldExtraction.MALFORMED)
+        else:
+            data[f.name] = v
+            # FR-011: a value reached via @coerceDefault (or @default) is DEFAULTED,
+            # not EXTRACTED.
+            report.set(path, _classify_coerced(path, report))
+
+
+def _classify_coerced(path: str, report: ExtractionReport) -> FieldExtraction:
+    """FR-011: classify a successfully-coerced field. DEFAULTED when its terminal
+    (last-logged) coercion for this path is a default-class fallback
+    (``coerceDefault`` / ``default``); EXTRACTED otherwise. Nested objects (which log
+    no coercion of their own) classify as EXTRACTED. Mirrors the TS/C#/Java classify."""
+    terminal_kind: str | None = None
+    for c in report.coercions():
+        if c.field_path == path:
+            terminal_kind = c.kind
+    return (
+        FieldExtraction.DEFAULTED
+        if terminal_kind in ("coerceDefault", "default")
+        else FieldExtraction.EXTRACTED
+    )
+
+
+def _extract_value(
+    f: FieldSpec,
+    present: object,
+    path: str,
+    report: ExtractionReport,
+    o: ExtractOptions,
+    ci: bool,
+) -> object:
+    """Coerce one (non-array) element: nested recursion or scalar coercion."""
+    if present is NULL_LITERAL:
+        # A JSON null array element (e.g. [1, null, 3]) carries no value → drop it as malformed
+        # rather than letting the sentinel stringify.
+        return MALFORMED
+    if f.kind == FieldKind.OBJECT:
+        if f.nested is not None and isinstance(present, dict):
+            nested_data: dict[str, object] = {}
+            _extract(f.nested.fields, present, path, nested_data, report, o, ci)
+            return nested_data
+        return MALFORMED  # object expected but scalar/non-map present
+    # A text element that also carried XML attributes is represented by XmlForgivingReader
+    # as a dict with the body under TEXT_KEY. A scalar field reads that text (attributes
+    # ignored for scalars — preserving pre-attribute-support behaviour).
+    if isinstance(present, dict) and TEXT_KEY in present:
+        present = present[TEXT_KEY]
+    raw_str = present if isinstance(present, str) else str(present)
+    return _coerce.value(raw_str, f, o, path, report)
+
+
+def _lookup(raw: dict[str, object], name: str, ci: bool) -> object | None:
+    """Case-folding lookup honoring tolerance."""
+    if name in raw:
+        return raw[name]
+    if ci:
+        lower = name.lower()
+        for k, v in raw.items():
+            if k.lower() == lower:
+                return v
+    return None

metaobjects/render/extract/extract_map.py

@@ -0,0 +1,61 @@
+"""Null-safe coercions from a ExtractionOutcome data map onto typed values.
+
+Generated ``extract(...)`` code calls these helpers. Python has a single ``int``
+type, so ``as_int`` and ``as_long`` are intentionally identical (both
+``Optional[int]``, truncating toward zero). ``bool`` is excluded from the numeric
+helpers (it is an ``int`` subclass in Python, but a boolean is never a number here).
+"""
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+
+
+def as_string(d: Mapping[str, object], k: str) -> str | None:
+    if k not in d:
+        return None
+    v = d[k]
+    if v is None:
+        return None
+    return v if isinstance(v, str) else str(v)
+
+
+def as_int(d: Mapping[str, object], k: str) -> int | None:
+    return _as_int(d, k)
+
+
+def as_long(d: Mapping[str, object], k: str) -> int | None:
+    # Python has one int type; as_int and as_long are the same (truncate toward zero).
+    return _as_int(d, k)
+
+
+def _as_int(d: Mapping[str, object], k: str) -> int | None:
+    v = d.get(k)
+    if isinstance(v, bool):
+        return None
+    if isinstance(v, int):
+        return v
+    if isinstance(v, float):
+        return math.trunc(v)
+    return None
+
+
+def as_double(d: Mapping[str, object], k: str) -> float | None:
+    v = d.get(k)
+    if isinstance(v, bool):
+        return None
+    if isinstance(v, (int, float)):
+        return float(v)
+    return None
+
+
+def as_bool(d: Mapping[str, object], k: str) -> bool | None:
+    v = d.get(k)
+    return v if isinstance(v, bool) else None
+
+
+def as_string_list(d: Mapping[str, object], k: str) -> list[str | None] | None:
+    v = d.get(k)
+    if not isinstance(v, list):
+        return None
+    return [None if e is None else (e if isinstance(e, str) else str(e)) for e in v]