metaobjects 1.0.12__tar.gz → 1.1.0__tar.gz

{metaobjects-1.0.12 → metaobjects-1.1.0}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.5
 Name: metaobjects
-Version: 1.0.12
+Version: 1.1.0
 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
 Project-URL: Documentation, https://github.com/metaobjectsdev/metaobjects/tree/main/docs
 Project-URL: Issues, https://github.com/metaobjectsdev/metaobjects/issues
+Project-URL: Changelog, https://github.com/metaobjectsdev/metaobjects/blob/main/CHANGELOG.md
 Author-email: Doug Mealing <doug@metaobjects.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -31,6 +32,9 @@ Provides-Extra: integration
 Requires-Dist: fastapi>=0.110; extra == 'integration'
 Requires-Dist: httpx>=0.27; extra == 'integration'
 Requires-Dist: pg8000>=1.31; extra == 'integration'
+Requires-Dist: pymysql>=1.1; extra == 'integration'
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
 Description-Content-Type: text/markdown
 
 # MetaObjects (Python)
@@ -80,10 +84,22 @@ The primary public API is the **loader** (`load_directory` / `load_uris` /
 distribution also ships the Python implementations of the other pillars used by the CLI
 and tooling: `codegen` (Pydantic + FastAPI emit — reference generators you own:
 `metaobjects eject <name>` copies one into your repo), `render` (Mustache + payload-VO +
-verify), and `runtime` (a DB-API 2 `ObjectManager` — pg8000 / psycopg — no SQLAlchemy).
+verify), and `runtime` (a DB-API 2 `ObjectManager` — pg8000 / psycopg on Postgres, the standard library's `sqlite3` on SQLite, PyMySQL on MySQL 8 (`pip install metaobjects[mysql]`) — no SQLAlchemy).
 Schema migrations are owned by the TypeScript `meta` CLI (ADR-0015); there is
 **no `migrate` module** in this distribution.
 
+### Physical names
+
+Table and column names are one project setting, `naming` in `.metaobjects/config.json`
+(`columns` and `tables`, each `snake_case` by default or `literal`). `metaobjects gen` and
+`verify` read it, and so do `load_directory`, `load_uris` and `load_string(..., project_dir=...)`:
+they search upward from the metadata directory for that file, so the `ObjectManager` queries the
+names the code was generated for. If you keep a database whose columns are named exactly like the
+fields, add `"naming": { "columns": "literal" }`. With no config file found the loader warns once
+and uses `snake_case`; `metaobjects.naming.attach_naming(root, project_dir)` sets it explicitly and
+wins. See [the upgrade guide](../../docs/features/migrations/upgrading-1.0-to-1.1.md) and
+[physical naming](../../docs/features/migrations/physical-naming.md).
+
 ## Authoring formats
 
 - **Canonical JSON** (`*.json`) — the cross-language interchange shape.

{metaobjects-1.0.12 → metaobjects-1.1.0}/README.md

@@ -45,10 +45,22 @@ The primary public API is the **loader** (`load_directory` / `load_uris` /
 distribution also ships the Python implementations of the other pillars used by the CLI
 and tooling: `codegen` (Pydantic + FastAPI emit — reference generators you own:
 `metaobjects eject <name>` copies one into your repo), `render` (Mustache + payload-VO +
-verify), and `runtime` (a DB-API 2 `ObjectManager` — pg8000 / psycopg — no SQLAlchemy).
+verify), and `runtime` (a DB-API 2 `ObjectManager` — pg8000 / psycopg on Postgres, the standard library's `sqlite3` on SQLite, PyMySQL on MySQL 8 (`pip install metaobjects[mysql]`) — no SQLAlchemy).
 Schema migrations are owned by the TypeScript `meta` CLI (ADR-0015); there is
 **no `migrate` module** in this distribution.
 
+### Physical names
+
+Table and column names are one project setting, `naming` in `.metaobjects/config.json`
+(`columns` and `tables`, each `snake_case` by default or `literal`). `metaobjects gen` and
+`verify` read it, and so do `load_directory`, `load_uris` and `load_string(..., project_dir=...)`:
+they search upward from the metadata directory for that file, so the `ObjectManager` queries the
+names the code was generated for. If you keep a database whose columns are named exactly like the
+fields, add `"naming": { "columns": "literal" }`. With no config file found the loader warns once
+and uses `snake_case`; `metaobjects.naming.attach_naming(root, project_dir)` sets it explicitly and
+wins. See [the upgrade guide](../../docs/features/migrations/upgrading-1.0-to-1.1.md) and
+[physical naming](../../docs/features/migrations/physical-naming.md).
+
 ## Authoring formats
 
 - **Canonical JSON** (`*.json`) — the cross-language interchange shape.

{metaobjects-1.0.12 → metaobjects-1.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "1.0.12"
+version = "1.1.0"
 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"
@@ -47,6 +47,7 @@ Homepage = "https://metaobjects.dev"
 Repository = "https://github.com/metaobjectsdev/metaobjects"
 Documentation = "https://github.com/metaobjectsdev/metaobjects/tree/main/docs"
 Issues = "https://github.com/metaobjectsdev/metaobjects/issues"
+Changelog = "https://github.com/metaobjectsdev/metaobjects/blob/main/CHANGELOG.md"
 
 [project.optional-dependencies]
 dev = ["pytest>=8", "mypy>=1.10", "ruff>=0.6", "pydantic>=2"]
@@ -56,7 +57,16 @@ dev = ["pytest>=8", "mypy>=1.10", "ruff>=0.6", "pydantic>=2"]
 # TS/Java pattern of bypassing testcontainers wrappers entirely); the
 # api-contract harness drives a FastAPI Author API in-process via the
 # starlette TestClient (httpx).
-integration = ["pg8000>=1.31", "fastapi>=0.110", "httpx>=0.27"]
+integration = ["pg8000>=1.31", "PyMySQL>=1.1", "fastapi>=0.110", "httpx>=0.27"]
+# MySQL for the ObjectManager (`metaobjects.runtime.MySqlDriver`). PyMySQL is pure Python,
+# so like pg8000 it installs without native build dependencies. SQLite needs nothing: the
+# driver wraps the standard library's `sqlite3`.
+mysql = ["PyMySQL>=1.1"]
+
+[[tool.mypy.overrides]]
+# PyMySQL ships no type information.
+module = ["pymysql", "pymysql.*"]
+ignore_missing_imports = true
 
 [build-system]
 requires = ["hatchling"]

{metaobjects-1.0.12 → metaobjects-1.1.0}/src/metaobjects/apidocs/__init__.py

@@ -19,7 +19,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 # Path math is leaf-level (no generator imports) — safe to expose eagerly.
-from metaobjects.apidocs.paths import (
+from metaobjects.codegen.runtime.api_docs_paths import (
     Layout,
     doc_page_output_path,
     model_cross_href,
@@ -28,7 +28,7 @@ from metaobjects.apidocs.paths import (
 )
 
 if TYPE_CHECKING:  # pragma: no cover - import-time only for type checkers
-    from metaobjects.apidocs.api_model import (
+    from metaobjects.codegen.runtime.api_docs_model import (
         ApiModel,
         ApiSymbol,
         ApiSymbolKind,
@@ -36,8 +36,8 @@ if TYPE_CHECKING:  # pragma: no cover - import-time only for type checkers
         FieldShape,
         UnitExample,
     )
-    from metaobjects.apidocs.builder import PythonApiModelBuilder, build_api_model
-    from metaobjects.apidocs.renderer import (
+    from metaobjects.codegen.runtime.api_docs_builder import PythonApiModelBuilder, build_api_model
+    from metaobjects.codegen.runtime.api_docs_renderer import (
         PythonApiDocsRenderer,
         render_agent_api,
         render_index,
@@ -46,18 +46,18 @@ if TYPE_CHECKING:  # pragma: no cover - import-time only for type checkers
 
 # Lazily-resolved exports → their defining submodule.
 _LAZY: dict[str, str] = {
-    "ApiModel": "api_model",
-    "ApiSymbol": "api_model",
-    "ApiSymbolKind": "api_model",
-    "ApiUnit": "api_model",
-    "FieldShape": "api_model",
-    "UnitExample": "api_model",
-    "PythonApiModelBuilder": "builder",
-    "build_api_model": "builder",
-    "PythonApiDocsRenderer": "renderer",
-    "render_unit_page": "renderer",
-    "render_index": "renderer",
-    "render_agent_api": "renderer",
+    "ApiModel": "api_docs_model",
+    "ApiSymbol": "api_docs_model",
+    "ApiSymbolKind": "api_docs_model",
+    "ApiUnit": "api_docs_model",
+    "FieldShape": "api_docs_model",
+    "UnitExample": "api_docs_model",
+    "PythonApiModelBuilder": "api_docs_builder",
+    "build_api_model": "api_docs_builder",
+    "PythonApiDocsRenderer": "api_docs_renderer",
+    "render_unit_page": "api_docs_renderer",
+    "render_index": "api_docs_renderer",
+    "render_agent_api": "api_docs_renderer",
 }
 
 __all__ = [
@@ -87,5 +87,5 @@ def __getattr__(name: str) -> Any:
         raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
     import importlib
 
-    mod = importlib.import_module(f"{__name__}.{submodule}")
+    mod = importlib.import_module(f"metaobjects.codegen.runtime.{submodule}")
     return getattr(mod, name)

metaobjects-1.1.0/src/metaobjects/apidocs/api_model.py

@@ -0,0 +1,4 @@
+"""Deprecated: moved to :mod:`metaobjects.codegen.runtime.api_docs_model`."""
+from metaobjects.codegen._moved import alias
+
+alias(__name__, "metaobjects.codegen.runtime.api_docs_model")

metaobjects-1.1.0/src/metaobjects/apidocs/builder.py

@@ -0,0 +1,4 @@
+"""Deprecated: moved to :mod:`metaobjects.codegen.runtime.api_docs_builder`."""
+from metaobjects.codegen._moved import alias
+
+alias(__name__, "metaobjects.codegen.runtime.api_docs_builder")

{metaobjects-1.0.12 → metaobjects-1.1.0}/src/metaobjects/apidocs/naming.py

@@ -3,7 +3,7 @@ generated identifier the api-docs builder documents.
 
 This mirrors the Java ``SpringNaming`` / C# ``CSharpNaming`` pattern: the real
 generators delegate their name computation here, and the
-:class:`~metaobjects.apidocs.builder.PythonApiModelBuilder` enumerates symbols by
+:class:`~metaobjects.codegen.runtime.api_docs_builder.PythonApiModelBuilder` enumerates symbols by
 calling the SAME functions. So the documented name can never drift from the
 emitted name — they are computed once, in one place.
 
@@ -74,6 +74,52 @@ def _route_snake_case(name: str) -> str:
     return to_snake_case(name)
 
 
+_ALREADY_PLURAL_EXCLUDED_PRECEDING_CHARS = "suia"
+"""The four letters that precede a genuinely SINGULAR "...s" ending in the common
+patterns this codebase's entity names hit — status, address, bonus, alias, gas,
+analysis. Anything else before a final "s" reads as already-plural."""
+
+
+def _is_already_plural(word: str) -> bool:
+    """True when ``word`` already reads as a plural noun, so running it through
+    the ordinary suffix rule would double it — the real defect this exists to
+    fix: ``program_purchase_stats`` -> ``program_purchase_statses`` shipped as a
+    REST collection path in an adopter's app.
+
+    Heuristic, not a dictionary: a word ending in ``s`` is already-plural UNLESS
+    the character immediately before that final ``s`` is one of s/u/i/a
+    (case-insensitive). Covers stats, settings, details, news, analytics,
+    series, photos; leaves status, address, bonus, alias, gas, analysis on the
+    ordinary suffix path (unchanged).
+
+    Known miss, deliberately not fixed here: a genuinely singular word ending in
+    "...s" with none of those four letters before it reads as already-plural too
+    — ``lens`` -> ``lens`` (correct plural ``lenses``). Fixing that needs a real
+    dictionary, which this is not; the heuristic optimizes for the shape the
+    doubling defect actually hits (entity names that are already a plural
+    concept)."""
+    if len(word) < 2:
+        return False
+    lowered = word.lower()
+    if lowered[-1] != "s":
+        return False
+    return lowered[-2] not in _ALREADY_PLURAL_EXCLUDED_PRECEDING_CHARS
+
+
+def _pluralize_legacy_suffix_only(name: str) -> str:
+    """FROZEN — byte-for-byte the pre-fix suffix-only pluralization rule, with no
+    already-plural detection. Exposed only so :func:`pluralize` can fall back to
+    it. The DEFAULT PHYSICAL name fallback lives in a completely separate,
+    independently-frozen implementation (``meta_source._pluralize``) — this is
+    NOT that one, and the two must never be merged into a single call site."""
+    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 pluralize(name: str) -> str:
     """``post_category`` → ``post_categories``; ``address`` → ``addresses``.
 
@@ -82,13 +128,16 @@ def pluralize(name: str) -> str:
     ``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"
+    case-sensitive ones, so mixed-case input may diverge.
+
+    Adds already-plural detection (:func:`_is_already_plural`) on top of that
+    historical suffix rule (:func:`_pluralize_legacy_suffix_only`) — API/code-
+    surface pluralization only; the DEFAULT PHYSICAL table name fallback is
+    frozen separately (``meta_source._pluralize``), so an existing adopter
+    database never sees a proposed rename."""
+    if _is_already_plural(name):
+        return name
+    return _pluralize_legacy_suffix_only(name)
 
 
 def model_class_name(obj: MetaData) -> str:

metaobjects-1.1.0/src/metaobjects/apidocs/paths.py

@@ -0,0 +1,4 @@
+"""Deprecated: moved to :mod:`metaobjects.codegen.runtime.api_docs_paths`."""
+from metaobjects.codegen._moved import alias
+
+alias(__name__, "metaobjects.codegen.runtime.api_docs_paths")

metaobjects-1.1.0/src/metaobjects/apidocs/renderer.py

@@ -0,0 +1,4 @@
+"""Deprecated: moved to :mod:`metaobjects.codegen.runtime.api_docs_renderer`."""
+from metaobjects.codegen._moved import alias
+
+alias(__name__, "metaobjects.codegen.runtime.api_docs_renderer")