metaobjects 0.9.0__py3-none-any.whl

metaobjects/codegen/runner.py

@@ -0,0 +1,110 @@
+"""run_gen — the codegen orchestrator. Mirrors codegen-ts/src/runner.ts."""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Callable
+
+from metaobjects.meta.meta_root import MetaRoot
+from metaobjects.meta.meta_data import MetaData
+from metaobjects.meta.core.object.meta_object import MetaObject
+from metaobjects.shared.base_types import TYPE_OBJECT
+from .config import GenConfig
+from .generator import GenContext, Generator
+from .overwrite_policy import decide_and_write
+
+_VALID_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+@dataclass
+class RunGenResult:
+    files: list[tuple[str, str]] = field(default_factory=list)  # (path, status)
+    warnings: list[str] = field(default_factory=list)
+
+
+def _objects(root: MetaData) -> list[MetaObject]:
+    return [c for c in root.own_children()
+            if c.type == TYPE_OBJECT and isinstance(c, MetaObject)]
+
+
+def _matcher(gen: Generator) -> Callable[[MetaObject], bool]:
+    flt = getattr(gen, "filter", None)
+    if callable(flt):
+        return flt  # type: ignore[no-any-return]
+
+    def _all(_e: MetaObject) -> bool:
+        return True
+
+    return _all
+
+
+def _warn_collector(name: str, sink: list[str]) -> Callable[[str], None]:
+    def warn(msg: str) -> None:
+        sink.append(f"[{name}] {msg}")
+
+    return warn
+
+
+def run_gen(
+    config: GenConfig,
+    metadata: MetaData,
+    *,
+    generators: list[Generator],
+    entity_filter: list[str] | None = None,
+    merge_strategy: str = "overwrite",
+) -> RunGenResult:
+    result = RunGenResult()
+    if not isinstance(metadata, MetaRoot):
+        raise ValueError("run_gen: metadata must be a loaded MetaRoot.")
+
+    objs = _objects(metadata)
+    if entity_filter is not None:
+        objs = [o for o in objs if o.name in entity_filter]
+
+    if not objs:
+        reason = (
+            "no object children match the provided entity_filter"
+            if entity_filter is not None
+            else "root has no object children"
+        )
+        result.warnings.append(f"No entities to generate — {reason}.")
+        return result
+
+    safe: list[MetaObject] = []
+    for o in objs:
+        if not _VALID_NAME.match(o.name):
+            result.warnings.append(
+                f"Skipping entity with unsafe name {o.name!r} — must match ^[A-Za-z_]\\w*$."
+            )
+            continue
+        safe.append(o)
+    if not safe:
+        return result
+
+    emitted: dict[str, tuple[str, str]] = {}  # full_path -> (content, generated_by)
+    for gen in generators:
+        ctx = GenContext(
+            entities=safe,
+            loaded_root=metadata,
+            matches=_matcher(gen),
+            config=config,
+            warn=_warn_collector(gen.name, result.warnings),
+        )
+        for f in gen.generate(ctx):
+            full = os.path.join(config.out_dir, f.path)
+            if full in emitted:
+                raise ValueError(
+                    f"Output path collision: {full!r} emitted by "
+                    f"{emitted[full][1]!r} and {gen.name!r}."
+                )
+            emitted[full] = (f.content, gen.name)
+
+    for full, (content, _by) in emitted.items():
+        status = decide_and_write(full, content, merge_strategy)
+        result.files.append((full, status))
+        if status == "refused":
+            result.warnings.append(
+                f"Refused to overwrite {full}: file exists without the @generated header."
+            )
+    return result

metaobjects/codegen/runtime/__init__.py

@@ -0,0 +1,6 @@
+"""Runtime helpers shipped alongside generated routers.
+
+Generated code imports from this package directly — the helpers are part of
+the public surface of `metaobjects.codegen`. Keep imports here minimal and
+substrate-neutral (no FastAPI / SQLAlchemy / pg8000 dependencies).
+"""

metaobjects/codegen/runtime/filter_parser.py

@@ -0,0 +1,193 @@
+"""Runtime helper shipped alongside the generated FastAPI routers. Parses
+the cross-port FR-009 filter grammar ``filter[<field>][<op>]=<value>`` (and
+the ``filter[<field>]=<value>`` sugar form for ``eq``) against a per-entity
+allowlist.
+
+This module is part of ``metaobjects.codegen``'s public runtime surface —
+generated routers import + call into it directly. It is intentionally
+substrate-agnostic: ``parse_filter`` returns a list of ``FilterPredicate``
+records that the consumer's repository implementation translates to its
+persistence DSL of choice (SQLAlchemy, asyncpg, pg8000, etc.).
+
+Returned ``FilterParseResult`` is either:
+
+* ``predicates`` populated + ``error_envelope`` ``None`` — success path; the
+  generated router passes ``predicates`` into the repository.
+* ``error_envelope`` non-``None`` (one of ``invalid_filter_field`` /
+  ``invalid_filter_op`` / ``invalid_filter_value``) — the generated router
+  raises ``HTTPException(status_code=400, detail=result.error_envelope)``.
+
+Mirror of the Java ``FilterParser`` / Kotlin ``KotlinFilterAllowlistGenerator`` /
+C# ``FilterParser`` ports — same wire grammar, same error envelopes, same
+substrate-neutral predicate shape.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Mapping
+from urllib.parse import unquote_plus
+
+
+# Sentinel returned by `_coerce_value` on a parse failure.
+_INVALID_VALUE = object()
+
+# Error envelope keys — must stay identical across all ports.
+_ERR_FIELD = "invalid_filter_field"
+_ERR_OP = "invalid_filter_op"
+_ERR_VALUE = "invalid_filter_value"
+
+
+@dataclass(frozen=True)
+class FilterPredicate:
+    """A single validated filter clause from the URL.
+
+    The ``value`` field holds either:
+
+    * a ``bool`` (only for the ``isNull`` op),
+    * a ``list[str]`` (only for the ``in`` op — comma-separated values trimmed),
+    * a ``str`` (for ``eq`` / ``ne`` / ``gt`` / ``gte`` / ``lt`` / ``lte`` /
+      ``like`` — raw URL-decoded text, the repository binds it via
+      parameterized SQL so the driver picks the column type).
+    """
+
+    field: str
+    op: str
+    value: Any
+
+
+@dataclass(frozen=True)
+class FilterParseResult:
+    """Outcome of parsing the ``filter[...]`` query params.
+
+    Exactly one of ``predicates`` (success) / ``error_envelope`` (failure)
+    is populated. On error, ``predicates`` is an empty list.
+    """
+
+    predicates: list[FilterPredicate] = field(default_factory=list)
+    error_envelope: dict[str, str] | None = None
+
+
+def parse_filter(
+    query_params: Iterable[tuple[str, str]] | Mapping[str, str],
+    allowed_fields: Iterable[str],
+    ops_by_field: Mapping[str, Iterable[str]],
+) -> FilterParseResult:
+    """Parse the ``filter[<field>][<op>]=<value>`` grammar from query params.
+
+    ``query_params`` is the FastAPI ``Request.query_params`` object (a
+    multi-dict-like that yields ``(key, value)`` pairs when iterated as
+    ``.multi_items()``). For testing, a plain ``list[tuple[str, str]]`` works
+    too — anything iterable that yields the raw key/value pairs in URL
+    order. A plain ``Mapping`` collapses repeats (last-value-wins), which is
+    fine for tests that don't repeat keys.
+
+    Returns a ``FilterParseResult`` — on success, ``predicates`` carries the
+    validated + coerced filter list (preserving URL order); on failure,
+    ``error_envelope`` is one of the cross-port envelopes
+    (``invalid_filter_field`` / ``invalid_filter_op`` /
+    ``invalid_filter_value``).
+    """
+    allowed_set = set(allowed_fields)
+    ops_map: dict[str, frozenset[str]] = {
+        k: frozenset(v) for k, v in ops_by_field.items()
+    }
+
+    pairs = _as_pairs(query_params)
+
+    out: list[FilterPredicate] = []
+    for raw_key, raw_value in pairs:
+        # FastAPI's `Request.query_params` already URL-decodes both halves.
+        # If callers pass raw URL-encoded pairs (e.g. from a hand-built test),
+        # this is a no-op; if they pass pre-decoded text, also a no-op.
+        key = raw_key
+        value = raw_value
+        if not key.startswith("filter["):
+            continue
+
+        # Parse `filter[field]` or `filter[field][op]`. Bracket payload is
+        # opaque per the spec (no nested brackets).
+        first_close = key.find("]", 7)
+        if first_close < 0:
+            continue
+        field_name = key[7:first_close]
+        rest = first_close + 1
+        if rest >= len(key):
+            op = "eq"
+        elif key[rest] == "[":
+            second_close = key.find("]", rest + 1)
+            if second_close < 0:
+                continue
+            op = key[rest + 1 : second_close]
+        else:
+            continue
+
+        if field_name not in allowed_set:
+            return FilterParseResult(error_envelope={"error": _ERR_FIELD})
+        ops = ops_map.get(field_name)
+        if ops is None or op not in ops:
+            return FilterParseResult(error_envelope={"error": _ERR_OP})
+        coerced = _coerce_value(value, op)
+        if coerced is _INVALID_VALUE:
+            return FilterParseResult(error_envelope={"error": _ERR_VALUE})
+        out.append(FilterPredicate(field=field_name, op=op, value=coerced))
+
+    return FilterParseResult(predicates=out)
+
+
+def _coerce_value(raw: str, op: str) -> Any:
+    """Normalize a raw URL-decoded string into a typed value for ``op``.
+
+    The concrete substrate type (number vs string vs date) is left for the
+    repository to handle — this parser only normalizes the structural shape:
+    a ``list[str]`` for ``in``, a ``bool`` for ``isNull``, and a raw ``str``
+    for the scalar comparison ops.
+    """
+    if op == "isNull":
+        if raw == "true":
+            return True
+        if raw == "false":
+            return False
+        return _INVALID_VALUE
+    if op == "in":
+        return [p.strip() for p in raw.split(",")]
+    # For eq/ne/gt/gte/lt/lte/like the parser passes through the raw string
+    # value; the repository binds it via parameterized SQL (where the driver
+    # handles the coercion to the column type).
+    return raw
+
+
+def _as_pairs(
+    query_params: Iterable[tuple[str, str]] | Mapping[str, str],
+) -> list[tuple[str, str]]:
+    """Normalize a Mapping / FastAPI MultiDict / list-of-pairs to pairs."""
+    # FastAPI's `QueryParams` exposes `multi_items()` returning a list of
+    # `(key, value)` tuples preserving URL order + repeats.
+    multi_items = getattr(query_params, "multi_items", None)
+    if callable(multi_items):
+        return [(str(k), str(v)) for k, v in multi_items()]
+    if isinstance(query_params, Mapping):
+        return [(str(k), str(v)) for k, v in query_params.items()]
+    # Already an iterable of pairs.
+    return [(str(k), str(v)) for k, v in query_params]
+
+
+def parse_filter_qs(
+    raw_query: str | None,
+    allowed_fields: Iterable[str],
+    ops_by_field: Mapping[str, Iterable[str]],
+) -> FilterParseResult:
+    """Convenience wrapper that takes a raw URL query string (without leading
+    ``?``) and parses it via ``parse_filter``. Useful for tests + non-FastAPI
+    consumers."""
+    if not raw_query:
+        return FilterParseResult(predicates=[])
+    pairs: list[tuple[str, str]] = []
+    for pair in raw_query.split("&"):
+        if not pair:
+            continue
+        eq = pair.find("=")
+        if eq < 0:
+            pairs.append((unquote_plus(pair), ""))
+        else:
+            pairs.append((unquote_plus(pair[:eq]), unquote_plus(pair[eq + 1 :])))
+    return parse_filter(pairs, allowed_fields, ops_by_field)

metaobjects/codegen/type_map.py

@@ -0,0 +1,84 @@
+"""Field-subtype → Python/Pydantic type mapping (sub-project A)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from metaobjects.meta.core.field.meta_field import MetaField
+from metaobjects.meta.core.field import field_constants as fc
+from metaobjects.shared.structural import KEY_IS_ARRAY
+
+
+@dataclass(frozen=True)
+class PyType:
+    expr: str                          # the annotation text, e.g. "str", "list[PostBrief]"
+    imports: tuple[str, ...] = ()      # stdlib import lines this type needs
+
+
+_SCALAR: dict[str, PyType] = {
+    fc.FIELD_SUBTYPE_STRING: PyType("str"),
+    fc.FIELD_SUBTYPE_INT: PyType("int"),
+    fc.FIELD_SUBTYPE_LONG: PyType("int"),
+    fc.FIELD_SUBTYPE_DOUBLE: PyType("float"),
+    fc.FIELD_SUBTYPE_FLOAT: PyType("float"),
+    fc.FIELD_SUBTYPE_BOOLEAN: PyType("bool"),
+    fc.FIELD_SUBTYPE_DECIMAL: PyType("Decimal", ("from decimal import Decimal",)),
+    fc.FIELD_SUBTYPE_CURRENCY: PyType("int"),  # integer minor units — wire contract
+    fc.FIELD_SUBTYPE_DATE: PyType("datetime.date", ("import datetime",)),
+    fc.FIELD_SUBTYPE_TIME: PyType("datetime.time", ("import datetime",)),
+    fc.FIELD_SUBTYPE_TIMESTAMP: PyType("datetime.datetime", ("import datetime",)),
+    # R6 Plan 2a — field.uuid binds the idiomatic native uuid.UUID (ADR-0001),
+    # surfaced at build time. Wire/storage form stays a lowercase-canonical string.
+    fc.FIELD_SUBTYPE_UUID: PyType("uuid.UUID", ("import uuid",)),
+}
+
+
+def field_is_array(field: MetaField) -> bool:
+    """Array-ness from either form: the node property (programmatic build) or the
+    `@isArray` attr (how metadata loads from JSON — the conformance-fixture form)."""
+    return field.is_array or field.attr(KEY_IS_ARRAY) is True
+
+
+def _py_str_literal(value: str) -> str:
+    """A double-quoted Python string literal (JSON-safe escaping) for embedding an
+    enum member into a ``Literal[...]`` annotation — quote-style is stable across
+    ruff formatting."""
+    import json
+
+    return json.dumps(str(value), ensure_ascii=False)
+
+
+def effective_enum_values(field: MetaField) -> list[str]:
+    """The string members of an enum field's ``@values`` — EFFECTIVE (own, else
+    inherited via the ``extends`` super chain). A field that extends an abstract
+    ``field.enum`` resolves the parent's ``@values`` here, mirroring the TS
+    ``enumValues`` (which reads the effective attr). Empty when absent."""
+    v = field.attrs().get(fc.FIELD_ATTR_VALUES)
+    if isinstance(v, (list, tuple)):
+        return [str(x) for x in v]
+    return []
+
+
+def py_type_for(field: MetaField) -> PyType:
+    """The (non-optional) Python annotation for a field, wrapping arrays in list[...].
+
+    A ``field.enum`` with effective ``@values`` types as ``Literal[...]`` (value-
+    constrained, Pydantic runtime-validated) rather than bare ``str``; an enum array
+    becomes ``list[Literal[...]]``. An enum WITHOUT declared values falls back to
+    ``str``."""
+    if field.sub_type == fc.FIELD_SUBTYPE_OBJECT:
+        ref = field.attr(fc.FIELD_ATTR_OBJECT_REF)
+        base = PyType(str(ref)) if ref else PyType("object")
+    elif field.sub_type == fc.FIELD_SUBTYPE_ENUM:
+        values = effective_enum_values(field)
+        if values:
+            # Double-quoted members so the annotation reads identically whether or not
+            # the emitted module is ruff-formatted (ruff normalizes to double quotes).
+            members = ", ".join(_py_str_literal(v) for v in values)
+            base = PyType(f"Literal[{members}]", ("from typing import Literal",))
+        else:
+            base = PyType("str")
+    else:
+        base = _SCALAR.get(field.sub_type, PyType("str"))
+    if field_is_array(field):
+        return PyType(f"list[{base.expr}]", base.imports)
+    return base