metaobjects 1.1.2__tar.gz → 1.1.4__tar.gz

{metaobjects-1.1.2 → metaobjects-1.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: metaobjects
-Version: 1.1.2
+Version: 1.1.4
 Summary: Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port.
 Project-URL: Homepage, https://metaobjects.dev
 Project-URL: Repository, https://github.com/metaobjectsdev/metaobjects

{metaobjects-1.1.2 → metaobjects-1.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "1.1.2"
+version = "1.1.4"
 description = "Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port."
 readme = "README.md"
 requires-python = ">=3.11"

{metaobjects-1.1.2 → metaobjects-1.1.4}/src/metaobjects/codegen/generators/router_generator.py

@@ -658,6 +658,12 @@ def _auth_docstring_paragraph(*, read_only: bool) -> str:
     )
 
 
+#: The most rows a report list answers when no cap is configured, the same default in every
+#: port. With no ``limit`` a report answers every row up to the cap and is refused above it,
+#: never truncated.
+DEFAULT_REPORT_MAX_ROWS = 10_000
+
+
 class RouterGenerator:
     """One ``<entity_snake>_router.py`` per routed object (FastAPI ``APIRouter``):
     full CRUD for a writable source, read-only for a view-backed one.
@@ -689,6 +695,13 @@ class RouterGenerator:
 
     name = "router-generator"
 
+    def __init__(self, report_max_rows: int = DEFAULT_REPORT_MAX_ROWS) -> None:
+        """*report_max_rows* is the row cap of a served report's list route: with no ``limit``
+        the route answers every row up to it, and one more row (or a ``limit`` above it) is
+        ``400 {"error": "report_too_large", "maxRows": N}``. Reports only; an entity's list
+        keeps its paging."""
+        self.report_max_rows = report_max_rows
+
     def _emit_repository_protocol(
         self, repo_class: str, m2m: list[M2mDescriptor], pk_type: str
     ) -> list[str]:
@@ -758,12 +771,81 @@ class RouterGenerator:
         create_autoset: list[str] = (),
         update_autoset: list[str] = (),
         frozen_strip: list[str] = (),
+        report_max_rows: int | None = None,
     ) -> list[str]:
         """One CRUD route handler block, dispatched by *name*
         (``list`` / ``get`` / ``create`` / ``update`` / ``delete``). Override to
         change a handler's body / decorators / response shape. *model_name* /
         *patch_model* are the generated create + all-optional PATCH Pydantic models
-        used to run field constraints on POST / PATCH (FR-036)."""
+        used to run field constraints on POST / PATCH (FR-036). *report_max_rows* is
+        passed only for a served report's ``list``: every row up to that cap, refused above it."""
+        if name == "list" and report_max_rows is not None:
+            return [
+                '@router.get("")',
+                f"def list_{plural}(",
+                "    request: Request,",
+                f"    repo: Annotated[{repo_class}, Depends(get_repository)],",
+                "    limit: str | None = Query(None),",
+                "    offset: str | None = Query(None),",
+                "    sort: str | None = Query(None),",
+                '    with_count: int | None = Query(None, alias="withCount"),',
+                ") -> Any:",
+                f"    max_rows = {report_max_rows}",
+                "    too_large = JSONResponse(",
+                '        status_code=400, content={"error": "report_too_large", "maxRows": max_rows}',
+                "    )",
+                "    requested_limit: int | None = None",
+                "    if limit is not None:",
+                "        if not (limit.isascii() and limit.isdigit()) or int(limit) < 1:",
+                "            return JSONResponse(",
+                "                status_code=400,",
+                "                content={",
+                '                    "error": "pagination.invalid_value",',
+                '                    "param": "limit",',
+                '                    "value": limit,',
+                '                    "expected": f"an integer from 1 to {max_rows}",',
+                "                },",
+                "            )",
+                "        requested_limit = int(limit)",
+                "        if requested_limit > max_rows:",
+                "            return too_large",
+                "    actual_offset = 0",
+                "    if offset is not None:",
+                "        if not (offset.isascii() and offset.isdigit()):",
+                "            return JSONResponse(",
+                "                status_code=400,",
+                "                content={",
+                '                    "error": "pagination.invalid_value",',
+                '                    "param": "offset",',
+                '                    "value": offset,',
+                '                    "expected": "a non-negative integer (0 or more)",',
+                "                },",
+                "            )",
+                "        actual_offset = int(offset)",
+                "    sort_clause: _SortClause | None = None",
+                "    if sort is not None:",
+                "        sort_clause = _parse_sort(sort)",
+                "        if sort_clause is None:",
+                '            return JSONResponse(status_code=400, content={"error": "invalid_sort", "field": sort.split(":", 1)[0]})',
+                f"    filter_result = parse_filter(request.query_params, {fields_const}, {ops_const})",
+                "    if filter_result.error_envelope is not None:",
+                "        return JSONResponse(status_code=400, content=filter_result.error_envelope)",
+                "    predicates, decimal_error = coerce_decimal_predicates(",
+                "        filter_result.predicates, _DECIMAL_FIELDS",
+                "    )",
+                "    if decimal_error is not None:",
+                "        return JSONResponse(status_code=400, content=decimal_error)",
+                "    # With no limit the repository is asked for one row past the cap, so the",
+                "    # refusal comes before any body is written.",
+                "    fetch_limit = requested_limit if requested_limit is not None else max_rows + 1",
+                "    rows = repo.list(fetch_limit, actual_offset, sort_clause, predicates)",
+                "    if requested_limit is None and len(rows) > max_rows:",
+                "        return too_large",
+                "    if with_count == 1:",
+                "        total = repo.count(predicates)",
+                '        return {"rows": render_wire(rows, _WIRE), "total": total}',
+                "    return render_wire(rows, _WIRE)",
+            ]
         if name == "list":
             return [
                 '@router.get("")',
@@ -1803,6 +1885,9 @@ class RouterGenerator:
             # handlers do not read these; they are required by the shared signature.
             model_name="",
             patch_model="",
+            # Only a report is capped; passed for it alone so an adopter's `_emit_route_handler`
+            # override that does not take the keyword keeps working for a projection.
+            **({"report_max_rows": self.report_max_rows} if is_report else {}),
         )
         for i, hname in enumerate(("list", "get") if item_route else ("list",)):
             if i > 0:
@@ -1856,11 +1941,12 @@ def render_router(
     return RouterGenerator().render_router(entity, object_index, column_naming)
 
 
-def router_generator() -> Generator:
+def router_generator(report_max_rows: int = DEFAULT_REPORT_MAX_ROWS) -> Generator:
     """Generator factory: one ``<entity_snake>_router.py`` per routed object —
-    full CRUD for a writable source, read-only for a view-backed one.
+    full CRUD for a writable source, read-only for a view-backed one. *report_max_rows*
+    is the row cap of a served report's list route (default 10000).
 
     Returns a :class:`RouterGenerator` (subclassable extension seam). Skips objects
     without a ``source.rdb`` child and the non-collection read-only kinds
     (storedProc / tableFunction)."""
-    return RouterGenerator()
+    return RouterGenerator(report_max_rows)

{metaobjects-1.1.2 → metaobjects-1.1.4}/src/metaobjects/loader/validate_reporting.py

@@ -96,6 +96,8 @@ from ..meta.core.reporting.reporting_constants import (
     AGG_MIN,
     AGG_SUM,
     FILTER_RELATIVE_NOW,
+    FILTER_RELATIVE_START_OF,
+    RELATIVE_START_OF_UNITS,
     GRAIN_HOUR,
     ISO_DURATION_RE,
     MEASURE_SUBTYPE_AGGREGATE,
@@ -310,7 +312,7 @@ def _is_document_field(field: MetaData) -> bool:
 
 def _is_relative_value(v: object) -> TypeGuard[dict[str, object]]:
     """An object operand carrying a ``now`` key — a relative-date value, well-formed
-    (exactly ``{ now }``) or not. A malformed one is refused, never read as data."""
+    (``{ now }`` plus an optional ``startOf``) or not. A malformed one is refused, never read as data."""
     return isinstance(v, dict) and FILTER_RELATIVE_NOW in v
 
 
@@ -861,10 +863,10 @@ def _check_filter(
             relative = _relative_operand(operand)
             if relative is None:
                 continue
-            if len(relative) != 1:
+            if not set(relative) <= {FILTER_RELATIVE_NOW, FILTER_RELATIVE_START_OF}:
                 err(
                     f"@filter on '{key}' has a malformed relative date {_js_json(relative)}; a relative date is "
-                    f'exactly {{ now: "<ISO-8601 duration>" }} with no other keys.'
+                    f'{{ now: "<ISO-8601 duration>" }} with an optional startOf, and no other keys.'
                 )
                 continue
             if field.sub_type not in _TEMPORAL_FIELD_SUBTYPES:
@@ -885,6 +887,14 @@ def _check_filter(
                     f"@filter on '{key}' has relative date '{_quote_value(duration)}', which is not an ISO-8601 "
                     f"duration (e.g. '-P7D', '-PT12H')."
                 )
+                continue
+            if FILTER_RELATIVE_START_OF in relative:
+                start_of = relative[FILTER_RELATIVE_START_OF]
+                if not isinstance(start_of, str) or start_of not in RELATIVE_START_OF_UNITS:
+                    err(
+                        f"@filter on '{key}' has startOf '{_quote_value(start_of)}'; startOf is one of "
+                        f"{', '.join(RELATIVE_START_OF_UNITS)}."
+                    )
 
 
 # ---------------------------------------------------------------------------

{metaobjects-1.1.2 → metaobjects-1.1.4}/src/metaobjects/meta/core/reporting/reporting_constants.py

@@ -107,6 +107,13 @@ REPORT_DIMENSION_GRAIN_SEPARATOR = ":"
 #: Legal only in the ``@filter`` of a ``segment``, ``measure.aggregate`` or ``object.report``.
 FILTER_RELATIVE_NOW = "now"
 
+#: The optional second key of a relative-date value: ``{ "now": "-P90D", "startOf": "day" }``
+#: truncates the instant (after the duration is applied) to the start of that UTC calendar unit.
+FILTER_RELATIVE_START_OF = "startOf"
+
+#: The calendar units ``startOf`` accepts. A week is the ISO week, Monday start.
+RELATIVE_START_OF_UNITS: tuple[str, ...] = ("day", "week", "month")
+
 #: A signed ISO-8601 duration (``-P7D``, ``P1Y2M``, ``-PT12H``). The lookaheads refuse
 #: the degenerate ``P`` and ``PT`` forms (a designator with no component). The pattern
 #: is the rule table's verbatim; ``\Z`` stands in for JS ``$`` (Python ``$`` would also

{metaobjects-1.1.2 → metaobjects-1.1.4}/src/metaobjects/registry_manifest.py

@@ -255,7 +255,7 @@ def _sorted_children(definition: TypeDefinition) -> list[dict[str, object]]:
     return children
 
 
-METAMODEL_VERSION = "1.1"
+METAMODEL_VERSION = "1.2"
 """Rolled-up spec-version for the cross-port registry manifest.
 
 ``"0"`` = pre-1.0 / unstable (semver major-0). Flips to ``"1.0"`` at the

{metaobjects-1.1.2 → metaobjects-1.1.4}/src/metaobjects/runtime/dialect.py

@@ -68,6 +68,12 @@ class Dialect:
         """``col LIKE pattern`` with the pattern verbatim and the match case-SENSITIVE."""
         return f"{quoted_column} LIKE {self.placeholder}", [pattern]
 
+    def order_term(self, quoted_column: str, descending: bool) -> str:
+        """One ``ORDER BY`` term with nulls LARGER than any value: ASC puts them last, DESC
+        first, on every engine. That is Postgres's own default, so this is its native form;
+        SQLite and MySQL would put nulls first on ASC."""
+        return f"{quoted_column} {'DESC NULLS FIRST' if descending else 'ASC NULLS LAST'}"
+
     def false_predicate(self) -> str:
         return "FALSE"
 
@@ -270,6 +276,11 @@ class MySqlDialect(Dialect):
     default_values = "() VALUES ()"
     unbounded_limit = "18446744073709551615"
 
+    def order_term(self, quoted_column: str, descending: bool) -> str:
+        # No NULLS FIRST/LAST on MySQL: a leading `col IS NULL` key (0 for a value, 1 for null).
+        d = "DESC" if descending else "ASC"
+        return f"({quoted_column} IS NULL) {d}, {quoted_column} {d}"
+
     def quote(self, ident: str) -> str:
         if "`" in ident:
             raise ValueError(f"unsafe identifier: {ident}")

{metaobjects-1.1.2 → metaobjects-1.1.4}/src/metaobjects/runtime/object_manager.py

@@ -634,8 +634,7 @@ class ObjectManager:
             for field_name, direction in sort:
                 f = entity.find_field(field_name)
                 col = _column_of(f, self._column_naming) if f is not None else field_name
-                d = "DESC" if direction.lower() == "desc" else "ASC"
-                order_parts.append(f"{self._d.quote(col)} {d}")
+                order_parts.append(self._d.order_term(self._d.quote(col), direction.lower() == "desc"))
             if order_parts:
                 sql += " ORDER BY " + ", ".join(order_parts)
         if limit is not None:

{metaobjects-1.1.2 → metaobjects-1.1.4}/tests/integration/generated_report_app.py

@@ -42,6 +42,7 @@ from metaobjects import MetaDataLoader
 from .corpus_config import attach_corpus_wire
 from metaobjects.codegen.config import GenConfig
 from metaobjects.codegen.generator_registry import GeneratorBuildContext, list_generators
+from metaobjects.codegen.generators.router_generator import router_generator
 from metaobjects.codegen.runner import run_gen
 from metaobjects.codegen.runtime.filter_parser import FilterPredicate
 from metaobjects.naming import attach_naming
@@ -60,7 +61,11 @@ SERVED_REPORTS: dict[str, str] = {
     "SalesBySku": "sales_by_sku",
     "ProductRefunds": "product_refunds",
     "TicketsByTags": "tickets_by_tags",
+    "ReadingLog": "reading_log",
 }
+#: The row cap every lane builds its report routers with: ``ReadingLog`` has one row more, so the
+#: cap scenarios tell "exactly the cap" from "past it" (``report/README.md``).
+REPORT_CORPUS_MAX_ROWS = 60
 #: The sourceless report: generated nowhere, mounted nowhere.
 UNSERVED_REPORT = "InvoiceDays"
 
@@ -121,7 +126,9 @@ def generate_reports(corpus_root: Path, model: LaneModel = REPORT_MODEL) -> Gene
     templates = tmp / "templates"
     templates.mkdir()
     generators = [
-        entry.factory(GeneratorBuildContext(template_root=str(templates)))
+        router_generator(REPORT_CORPUS_MAX_ROWS)
+        if entry.name == "routes"
+        else entry.factory(GeneratorBuildContext(template_root=str(templates)))
         for entry in list_generators()
         if entry.name in _GENERATORS
     ]

{metaobjects-1.1.2 → metaobjects-1.1.4}/tests/integration/test_api_contract_report.py

@@ -102,7 +102,7 @@ def test_exactly_the_served_reports_are_generated() -> None:
     allowlist and router (and the names module is not a route concern, so it is not asked
     for here: only the three generators the lane runs)."""
     emitted = generate_reports(_CORPUS).emitted
-    assert len(SERVED_REPORTS) == 10
+    assert len(SERVED_REPORTS) == 11
     for report, stem in SERVED_REPORTS.items():
         assert f"{report}.py" in emitted
         assert f"{stem}_filter_allowlist.py" in emitted

{metaobjects-1.1.2 → metaobjects-1.1.4}/tests/runtime/test_object_manager_dialects.py

@@ -113,7 +113,7 @@ def test_sqlite_read_uses_qmark_placeholders_and_double_quotes() -> None:
     sql, params = rec.sql[-1]
     assert sql == (
         'SELECT "id", "label", "qty", "active", "price", "ref", "madeOn", "seenAt" FROM "items" '
-        'WHERE "qty" >= ? AND "label" = ? ORDER BY "qty" DESC LIMIT 5 OFFSET 10'
+        'WHERE "qty" >= ? AND "label" = ? ORDER BY "qty" DESC NULLS FIRST LIMIT 5 OFFSET 10'
     )
     assert params == (2, "a")
 
@@ -264,7 +264,7 @@ def test_mysql_read_uses_backticks_and_percent_placeholders() -> None:
     sql, params = conn.sql[-1]
     assert sql == (
         "SELECT `id`, `label`, `qty`, `active`, `price`, `ref`, `madeOn`, `seenAt` FROM `items` "
-        "WHERE `qty` >= %s AND `label` LIKE BINARY %s ORDER BY `qty` ASC "
+        "WHERE `qty` >= %s AND `label` LIKE BINARY %s ORDER BY (`qty` IS NULL) ASC, `qty` ASC "
         "LIMIT 18446744073709551615 OFFSET 4"
     )
     assert params == (2, "A%")
@@ -415,3 +415,14 @@ def test_a_mysql_decimal_operand_is_cast_to_a_decimal() -> None:
     sql, _ = _op_clause("amount", "in", [Decimal("1"), Decimal("2")], f, MYSQL)
     assert sql.count("CAST(%s AS DECIMAL(65,30))") == 2
     assert _op_clause("amount", "eq", Decimal("1.5"), f, POSTGRES)[0] == '"amount" = %s'
+
+
+def test_order_term_puts_nulls_largest_on_every_dialect() -> None:
+    from metaobjects.runtime.dialect import MySqlDialect, PostgresDialect, SqliteDialect
+
+    for d in (PostgresDialect(), SqliteDialect()):
+        assert d.order_term('"c"', False) == '"c" ASC NULLS LAST'
+        assert d.order_term('"c"', True) == '"c" DESC NULLS FIRST'
+    my = MySqlDialect()
+    assert my.order_term("`c`", False) == "(`c` IS NULL) ASC, `c` ASC"
+    assert my.order_term("`c`", True) == "(`c` IS NULL) DESC, `c` DESC"

{metaobjects-1.1.2 → metaobjects-1.1.4}/tests/runtime/test_object_manager_report.py

@@ -152,7 +152,7 @@ def test_filter_sort_limit_on_derived_fields() -> None:
         "ProgramMinutes", {"weeks": {"gte": 2}}, sort=[("totalMinutes", "desc")], limit=1
     )
     sql = drv.sql[0]
-    assert sql.endswith('FROM "v_program_minutes" WHERE "weeks" >= %s ORDER BY "totalMinutes" DESC LIMIT 1')
+    assert sql.endswith('FROM "v_program_minutes" WHERE "weeks" >= %s ORDER BY "totalMinutes" DESC NULLS FIRST LIMIT 1')
     assert drv.params[0] == (2,)
 
 

{metaobjects-1.1.2 → metaobjects-1.1.4}/tests/unit/test_reporting_accessors.py

@@ -333,7 +333,7 @@ def test_malformed_relative_value_is_refused() -> None:
         (
             ErrorCode.ERR_BAD_ATTR_FILTER,
             "report 'acme::shop::DailyRevenue': @filter on 'purchasedAt' has a malformed relative date "
-            '{"now":"-P7D","x":1}; a relative date is exactly { now: "<ISO-8601 duration>" } with no other keys.',
+            '{"now":"-P7D","x":1}; a relative date is { now: "<ISO-8601 duration>" } with an optional startOf, and no other keys.',
         )
     ]
 

{metaobjects-1.1.2 → metaobjects-1.1.4}/uv.lock

@@ -259,7 +259,7 @@ wheels = [
 
 [[package]]
 name = "metaobjects"
-version = "1.1.2"
+version = "1.1.4"
 source = { editable = "." }
 dependencies = [
     { name = "pyyaml" },