metaobjects 1.0.4__tar.gz → 1.0.5__tar.gz

{metaobjects-1.0.4 → metaobjects-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: metaobjects
-Version: 1.0.4
+Version: 1.0.5
 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.0.4 → metaobjects-1.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "1.0.4"
+version = "1.0.5"
 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.0.4 → metaobjects-1.0.5}/src/metaobjects/__init__.py

@@ -35,7 +35,9 @@ from .meta.core.object.object_extract import (
     extract_schema_for,
 )
 from .meta.core.object.value_object import ValueObject
+from .meta_endpoint import META_ROUTE_PATH, meta_json
 from .naming import resolve_column_name
+from .serializer_json import canonical_serialize_effective
 
 # Module-level shortcuts: the 99% case for callers who don't need a
 # long-lived loader. Signatures + docstrings come straight from the
@@ -60,6 +62,10 @@ __all__ = [
     "load_uris",
     "load_string",
     "resolve_column_name",
+    # UI-1 — the metadata API contract (GET /_meta)
+    "META_ROUTE_PATH",
+    "meta_json",
+    "canonical_serialize_effective",
     # Runtime object model (Phase A)
     "ValueObject",
     "MetaObjectAware",

{metaobjects-1.0.4 → metaobjects-1.0.5}/src/metaobjects/apidocs/builder.py

@@ -43,10 +43,7 @@ from metaobjects.codegen.generators.m2m_codegen import (
     resolve_m2m_descriptors,
 )
 from metaobjects.codegen.generators.find_inbound import is_xml, response_shape
-from metaobjects.codegen.generators.payload_vo_generator import (
-    is_field_required,
-    resolve_payload_vo,
-)
+from metaobjects.codegen.value_objects import is_field_required, pkg_of, resolve_payload_vo
 from metaobjects.codegen.generators.tph_plan import is_tph_subtype
 from metaobjects.codegen.instance_artifacts import emits_instance_artifacts, is_abstract
 from metaobjects.source_resolution import primary_rdb_source
@@ -58,19 +55,6 @@ from metaobjects.meta.meta_data import MetaData
 from metaobjects.meta.persistence.source.source_constants import SOURCE_KIND_TABLE
 from metaobjects.meta.template import template_constants as tc
 from metaobjects.shared.base_types import TYPE_OBJECT, TYPE_TEMPLATE
-from metaobjects.shared.separators import PACKAGE_SEP
-
-
-def _pkg_of(node: MetaData) -> str:
-    """The effective package of a node — its ``resolution_key()`` minus the
-    trailing ``::<name>`` ("" for a root-level node). Duplicated (not imported) to
-    match the existing per-generator convention. Used to derive a template's
-    referrer package for ``resolve_payload_vo`` (#228) — see that function's
-    docstring for why this ancestor-walk-aware form is used instead of the
-    loader's bare ``tpl.package or tpl.file_default_package or ""``."""
-    key = node.resolution_key()
-    i = key.rfind(PACKAGE_SEP)
-    return "" if i == -1 else key[:i]
 
 
 # ---------------------------------------------------------------------------
@@ -105,7 +89,7 @@ def _payload_resolves(tmpl: MetaData, root: MetaData) -> MetaObject | None:
         return None
     # ADR-0042 (#228): the referrer is THIS template — a bare @payloadRef resolves
     # in ITS OWN package first.
-    return resolve_payload_vo(root, payload_ref, _pkg_of(tmpl))
+    return resolve_payload_vo(root, payload_ref, pkg_of(tmpl))
 
 
 def _is_email_kind(tmpl: MetaData) -> bool:
@@ -160,12 +144,12 @@ class PythonApiModelBuilder:
         # MODEL — only for concrete objects (an abstract object cannot be
         # instantiated → documented ⊆ generated). A value object → MODEL only.
         if not is_abstract(obj):
-            model = naming.model_class_name(obj.name)
+            model = naming.model_class_name(obj)
             symbols.append(
                 ApiSymbol(
                     name=model,
                     kind=ApiSymbolKind.MODEL,
-                    module=f"from .{module} import {model}",
+                    module=naming.model_import(obj),
                     signature=f"class {model}(BaseModel)",
                     usage=(
                         "the Pydantic v2 entity model"
@@ -178,12 +162,12 @@ class PythonApiModelBuilder:
         if entity and _is_writable_table_entity(obj, object_index):
             # VALIDATION — the Pydantic field constraints carried on the model
             # (required / max-length / range / pattern). Names the model class.
-            model = naming.model_class_name(obj.name)
+            model = naming.model_class_name(obj)
             symbols.append(
                 ApiSymbol(
                     name=model,
                     kind=ApiSymbolKind.VALIDATION,
-                    module=f"from .{module} import {model}",
+                    module=naming.model_import(obj),
                     signature=f"class {model}(BaseModel)",
                     usage="Pydantic field validation on the create/update shape",
                     fields=self._model_fields(obj),
@@ -285,15 +269,14 @@ class PythonApiModelBuilder:
         payload_vo = _payload_resolves(tmpl, root)
 
         if payload_vo is not None:
-            # PAYLOAD — the typed Pydantic record for the shape this template RENDERS.
-            payload_class = naming.payload_class_name(name)
+            # PAYLOAD — the shape this template RENDERS. ADR-0056: it IS the @payloadRef
+            # value object's own model, emitted by the entity generator.
+            payload_class = naming.model_class_name(payload_vo)
             symbols.append(
                 ApiSymbol(
                     name=payload_class,
                     kind=ApiSymbolKind.PAYLOAD,
-                    module=(
-                        f"from .{naming.payload_module_name(name)} import {payload_class}"
-                    ),
+                    module=naming.model_import(payload_vo),
                     signature=f"class {payload_class}(BaseModel)",
                     usage="the typed payload projection bound to the template",
                     fields=self._payload_fields(payload_vo),
@@ -310,7 +293,7 @@ class PythonApiModelBuilder:
                         name=render_fn,
                         kind=ApiSymbolKind.RENDER,
                         module=f"from .{module}_render_helper import {render_fn}",
-                        signature=f"def {render_fn}(payload, provider)",
+                        signature=f"def {render_fn}(payload: {payload_class}, provider)",
                         usage="renders the output template against a typed payload",
                         returns="EmailDocument" if _is_email_kind(tmpl) else "str",
                     )
@@ -320,23 +303,23 @@ class PythonApiModelBuilder:
         # to an output, and the gate is @responseRef PRESENCE rather than a format
         # value. Shares `response_shape` with the generators, so the docs can never
         # claim a symbol codegen suppressed.
-        inbound = response_shape(root, tmpl, _pkg_of(tmpl))
+        inbound = response_shape(root, tmpl, pkg_of(tmpl))
         if inbound is not None:
-            # The RESPONSE record the parser actually returns — not the @payloadRef
-            # request record documented above, which types what this prompt renders out.
-            response_class = naming.response_class_name(name)
-            symbols.append(
-                ApiSymbol(
-                    name=response_class,
-                    kind=ApiSymbolKind.PAYLOAD,
-                    module=(
-                        f"from .{naming.response_module_name(name)} import {response_class}"
-                    ),
-                    signature=f"class {response_class}(BaseModel)",
-                    usage="the typed response shape a model reply is parsed into",
-                    fields=self._payload_fields(inbound.vo),
+            # The RESPONSE shape the parser actually returns — the @responseRef value
+            # object's own model (ADR-0056). Documented once: when the prompt renders and
+            # parses the SAME value object, the model above already is it.
+            response_class = naming.model_class_name(inbound.vo)
+            if payload_vo is None or inbound.vo.resolution_key() != payload_vo.resolution_key():
+                symbols.append(
+                    ApiSymbol(
+                        name=response_class,
+                        kind=ApiSymbolKind.PAYLOAD,
+                        module=naming.model_import(inbound.vo),
+                        signature=f"class {response_class}(BaseModel)",
+                        usage="the typed response shape a model reply is parsed into",
+                        fields=self._payload_fields(inbound.vo),
+                    )
                 )
-            )
 
             # OUTPUT_PARSER — the strict ``parse_*``. ADR-0053: JSON-only, so an XML
             # reply gets no strict tier and documenting one would name a missing fn.
@@ -403,8 +386,8 @@ class PythonApiModelBuilder:
 
     def _payload_fields(self, vo: MetaObject) -> list[FieldShape]:
         """The payload model's documented field shapes — one row per field of the
-        ``@payloadRef`` value object, with optionality from ``is_field_required``
-        (shared with the payload-VO generator, so there is no skew)."""
+        value object, with optionality from ``is_field_required`` (the boundary the
+        value object's model draws between ``T`` and ``T | None``)."""
         rows: list[FieldShape] = []
         for f in vo.fields():
             if not isinstance(f, MetaField):

{metaobjects-1.0.4 → metaobjects-1.0.5}/src/metaobjects/apidocs/naming.py

@@ -7,26 +7,25 @@ generators delegate their name computation here, and the
 calling the SAME functions. So the documented name can never drift from the
 emitted name — they are computed once, in one place.
 
-Behaviour-preserving: each function reproduces exactly what the corresponding
-generator used to compute inline (``_snake_case`` / ``_plural_lowercase`` /
+Behaviour-preserving with ONE deliberate exception: :func:`route_path` no longer
+reproduces the old inline ``name.lower() + "s"``, because that spelling diverged
+from the other ports (see its docstring). Every other function reproduces exactly
+what the corresponding generator used to compute inline (``_snake_case`` /
 ``<Name>Repository`` / ``<ENTITY>_FILTER_FIELDS`` / ``parse_<snake>`` /
-``render_<snake>`` / ``render_<snake>_format`` / ``extract_<snake>`` …). The
-payload-class / payload-module names already lived in
-``payload_vo_generator`` (``payload_class_name`` / ``payload_module_name``); this
-seam re-exports them so the builder has one import surface.
+``render_<snake>`` / ``render_<snake>_format`` / ``extract_<snake>`` …). A model's
+class name — which, the generated package being flat, is also its module name — comes
+from :mod:`metaobjects.codegen.value_objects`, the module the entity generator itself
+asks (ADR-0056: a template's payload and response types ARE its value objects' models).
 """
 from __future__ import annotations
 
-from metaobjects.codegen.generators.payload_vo_generator import (
-    payload_class_name,
-    payload_module_name,
-    response_class_name,
-    response_module_name,
-)
+from metaobjects.codegen import value_objects
+from metaobjects.meta.meta_data import MetaData
+from metaobjects.naming import to_snake_case
 
 __all__ = [
     "snake_case",
-    "plural_lowercase",
+    "pluralize",
     "model_class_name",
     "router_module_name",
     "repository_class_name",
@@ -35,10 +34,7 @@ __all__ = [
     "filter_ops_const",
     "route_path",
     "pk_param",
-    "payload_class_name",
-    "payload_module_name",
-    "response_class_name",
-    "response_module_name",
+    "model_import",
     "render_helper_fn",
     "output_prompt_fn",
     "output_parser_fn",
@@ -64,14 +60,47 @@ def snake_case(name: str) -> str:
     return "".join(out)
 
 
-def plural_lowercase(name: str) -> str:
-    """``Author`` → ``authors``. Cross-port-aligned trivial pluralization."""
-    return name.lower() + "s"
+def _route_snake_case(name: str) -> str:
+    """``PostCategory`` → ``post_category``; ``HTTPServer`` → ``http_server``.
 
+    ACRONYM-AWARE, and deliberately NOT :func:`snake_case`. The trivial variant
+    above inserts a separator before every capital, which is right for a module
+    name but would emit ``h_t_t_p_server`` in a URL. Delegates to
+    :func:`metaobjects.naming.to_snake_case` — the port's acronym-aware loop,
+    documented there as byte-for-byte the other ports' rule (separate when the
+    previous character is lower or a digit, or when it is upper and the NEXT one
+    is lower, so a run of capitals stays together until the final one that
+    begins a word)."""
+    return to_snake_case(name)
 
-def model_class_name(obj_name: str) -> str:
-    """The emitted Pydantic model class name — the object's own short name."""
-    return obj_name
+
+def pluralize(name: str) -> str:
+    """``post_category`` → ``post_categories``; ``address`` → ``addresses``.
+
+    The cross-port pluralization contract, byte-identical in every port: a word
+    ending ``s``/``x``/``z``/``ch``/``sh`` takes ``es``; a consonant followed by
+    ``y`` becomes ``ies``; anything else takes ``s``. The cross-port
+    byte-identity covers the already-lowercased word :func:`route_path` feeds
+    in — suffix tests here run on a lowercased copy, unlike the JVM port's
+    case-sensitive ones, so mixed-case input may diverge."""
+    lowered = name.lower()
+    if lowered.endswith(("s", "x", "z", "ch", "sh")):
+        return name + "es"
+    if len(name) >= 2 and lowered[-1] == "y" and lowered[-2] not in "aeiou":
+        return name[:-1] + "ies"
+    return name + "s"
+
+
+def model_class_name(obj: MetaData) -> str:
+    """The emitted Pydantic model class name — the object's own short name, or a value
+    object's collision-qualified one (ADR-0044/0056)."""
+    return value_objects.model_class_name(obj)
+
+
+def model_import(obj: MetaData) -> str:
+    """``from .<Name> import <Name>`` — the import of *obj*'s generated model (the entity
+    generator writes ``<Name>.py``, so the module IS the class name)."""
+    return value_objects.model_import(obj)
 
 
 def router_module_name(obj_name: str) -> str:
@@ -100,9 +129,14 @@ def filter_ops_const(obj_name: str) -> str:
 
 
 def route_path(obj_name: str) -> str:
-    """The default REST base segment — the entity name pluralized + lowercased
-    (cross-port grammar; e.g. ``Author`` → ``authors``)."""
-    return plural_lowercase(obj_name)
+    """The default REST collection segment — the ENTITY NAME ``snake_case``d and
+    then pluralized (``Author`` → ``authors``, ``PostCategory`` →
+    ``post_categories``). Never the physical ``@table``.
+
+    One rule, identical in all five ports. It used to be ``name.lower() + "s"``
+    here, which served ``PostCategory`` at ``/postcategorys``; see
+    ``fixtures/api-contract-conformance/m2m/`` for the scenario that gates it."""
+    return pluralize(_route_snake_case(obj_name))
 
 
 def pk_param(obj_name: str) -> str:
@@ -168,15 +202,14 @@ def extractor_fn(template_name: str) -> str:
 def _pluralize(name: str) -> str:
     """Trivial cross-port pluralization (matches the TS ``pluralize`` /
     ``MetaSource._pluralize``), applied to a PascalCase entity name BEFORE
-    snake-casing (``GameSession`` → ``GameSessions``)."""
+    snake-casing (``GameSession`` → ``GameSessions``).
+
+    Delegates to :func:`pluralize` so this file states the cross-port inflector
+    contract once, not twice; the empty-string guard stays here because it is
+    this finder-naming helper's own contract, not ``pluralize``'s."""
     if not name:
         return name
-    lower = name.lower()
-    if lower.endswith(("s", "x", "z", "ch", "sh")):
-        return name + "es"
-    if len(name) >= 2 and lower[-1] == "y" and lower[-2] not in "aeiou":
-        return name[:-1] + "ies"
-    return name + "s"
+    return pluralize(name)
 
 
 def reverse_finder_fk_segment(fk_field_name: str) -> str: