matrx-orm 3.1.26__tar.gz → 3.1.28__tar.gz

{matrx_orm-3.1.26 → matrx_orm-3.1.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.26
+Version: 3.1.28
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current

{matrx_orm-3.1.26 → matrx_orm-3.1.28}/matrx_orm/core/MODULE_README.md

@@ -28,6 +28,15 @@ python utils/code_context/generate_module_readme.py src/matrx_orm/core --mode si
 
 ## Architecture
 
+### Pydantic bridge default invariant
+
+`pydantic_bridge.py` derives input/output schemas from ORM fields. Every
+non-`None` static field default is normalized through that field's `to_python`
+conversion before it is attached to the generated Pydantic schema. This keeps
+defaults canonical even though Pydantic does not validate defaults by default
+(for example, `DecimalField(default=0)` exposes `Decimal("0")`, not an `int`) and
+prevents serializer type warnings at API boundaries.
+
 > **Fill this in.** Describe the execution flow and layer map for this module.
 > See `utils/code_context/MODULE_README_SPEC.md` for the recommended format.
 >

{matrx_orm-3.1.26 → matrx_orm-3.1.28}/matrx_orm/core/pydantic_bridge.py

@@ -210,7 +210,6 @@ def _field_annotation(field: Any, *, partial: bool) -> tuple[Any, Any]:
     from matrx_orm.core.fields import (  # noqa: PLC0415
         DateField,
         DateTimeField,
-        EnumField,
         ForeignKey,
         TimeField,
     )
@@ -218,15 +217,15 @@ def _field_annotation(field: Any, *, partial: bool) -> tuple[Any, Any]:
     py_type = field.python_type()
 
     def _default() -> Any:
-        """ORM field defaults for EnumField are often bare strings
-        (``default='internal'`` in generated models). Pydantic v2 does not
-        re-validate defaults, so a string default on an Enum-typed field
-        survives onto the instance and ``model_dump()`` emits
-        ``PydanticSerializationUnexpectedValue``. Coerce via ``to_python``
-        so the schema default is a real enum member.
+        """Coerce ORM defaults into each field's canonical Python type.
+
+        Pydantic v2 does not re-validate defaults. Generated model defaults
+        therefore otherwise retain their DB-literal types (for example ``0``
+        on a DecimalField or ``"internal"`` on an EnumField), and
+        ``model_dump()`` emits ``PydanticSerializationUnexpectedValue``.
         """
         value = field.get_default()
-        if isinstance(field, EnumField) and value is not None:
+        if value is not None:
             try:
                 return field.to_python(value)
             except (TypeError, ValueError):

matrx_orm-3.1.28/matrx_orm/operations/db_functions.py

@@ -0,0 +1,78 @@
+"""Generic Postgres function-call primitive.
+
+Databases increasingly own logic as ``schema.fn_*`` functions (identity
+upserts, jsonb merges, ingestion RPCs). Application code must never
+re-implement them and must never hand-write ``SELECT ... FROM schema.fn(...)``
+strings — this module is the ONE place that renders that statement.
+
+``call_db_function`` executes ``SELECT * FROM <schema.fn>($1, $2, ...)`` on a
+model's database (or a named database config) and returns the result rows as
+plain dicts. It routes through ``AsyncDatabaseManager.execute_write`` because
+DB functions may write; a read-only function is simply a write that touches
+nothing.
+
+Argument encoding: scalars bind as-is; ``dict``/``list`` arguments are JSON
+encoded and cast ``::jsonb`` in the rendered statement (the overwhelmingly
+common composite argument type for these functions). A function needing a
+different composite cast gets a new explicit parameter here — never a raw SQL
+call site.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover
+    from matrx_orm.core.base import Model
+
+# schema-qualified (or bare) SQL function identifier — the only shape we ever
+# interpolate into the statement. Everything else binds as a parameter.
+_FUNCTION_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$")
+
+
+def _render_call(function_name: str, args: tuple[Any, ...]) -> tuple[str, list[Any]]:
+    if not _FUNCTION_NAME_RE.match(function_name):
+        raise ValueError(f"call_db_function: invalid function name {function_name!r}")
+    placeholders: list[str] = []
+    values: list[Any] = []
+    for index, arg in enumerate(args, start=1):
+        if isinstance(arg, dict | list):
+            placeholders.append(f"${index}::jsonb")
+            values.append(json.dumps(arg, ensure_ascii=False, default=str))
+        else:
+            placeholders.append(f"${index}")
+            values.append(arg)
+    sql = f"SELECT * FROM {function_name}({', '.join(placeholders)})"
+    return sql, values
+
+
+async def call_db_function(
+    database: type[Model] | str,
+    function_name: str,
+    *args: Any,
+) -> list[dict[str, Any]]:
+    """``SELECT * FROM <function_name>($1, ...)`` → ``list[dict]``.
+
+    Args:
+        database: a matrx-orm ``Model`` subclass (the call runs on its
+            database) or a database config name string.
+        function_name: bare or schema-qualified function identifier
+            (e.g. ``"seo.fn_upsert_keyword"``). Validated — never user input.
+        *args: positional function arguments. ``dict``/``list`` values are
+            JSON-encoded and cast ``::jsonb``; everything else binds directly.
+
+    Returns the function's result set as plain dicts (a scalar-returning
+    function yields one row with one column named after the function).
+    """
+    sql, values = _render_call(function_name, args)
+
+    from matrx_orm.core.async_db_manager import AsyncDatabaseManager
+
+    config = database if isinstance(database, str) else database.get_database_name()
+    rows = await AsyncDatabaseManager.execute_write(config, sql, *values)
+    return [dict(row) for row in rows]
+
+
+__all__ = ["call_db_function"]

{matrx_orm-3.1.26 → matrx_orm-3.1.28}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.26"
+version = "3.1.28"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching"
 readme = "README.md"
 license = { text = "MIT" }

matrx_orm-3.1.28/tests/level1/test_pydantic_bridge.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import warnings
+from decimal import Decimal
+
+from matrx_orm import (
+    DecimalField,
+    Model,
+    TextField,
+    UUIDField,
+    build_input_schema,
+    validate_model_input,
+)
+
+
+class CostedRecord(Model):
+    _table_name = "costed_record"
+    _database = "test"
+
+    id = UUIDField(primary_key=True)
+    name = TextField(null=False)
+    total_cost = DecimalField(null=False, default=0)
+
+
+def test_decimal_default_is_canonical_before_pydantic_serialization() -> None:
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        validated = validate_model_input(CostedRecord, {"name": "example"})
+
+    assert validated == {"name": "example"}
+    schema = build_input_schema(CostedRecord)
+    assert schema(name="example").total_cost == Decimal("0")
+    assert not [w for w in caught if "Pydantic serializer warnings" in str(w.message)]

matrx_orm-3.1.28/tests/test_db_functions.py

@@ -0,0 +1,43 @@
+"""Render-layer tests for the generic DB function-call primitive."""
+
+import json
+
+import pytest
+
+from matrx_orm.operations.db_functions import _render_call
+
+
+def test_scalar_args_bind_positionally():
+    sql, values = _render_call("seo.fn_upsert_keyword", ("botox cost", "en"))
+    assert sql == "SELECT * FROM seo.fn_upsert_keyword($1, $2)"
+    assert values == ["botox cost", "en"]
+
+
+def test_dict_and_list_args_encode_as_jsonb():
+    research = {"primary": "botox", "children": ["botox cost"]}
+    sql, values = _render_call("seo.fn_ingest_keyword_research", (research, "en", None))
+    assert sql == "SELECT * FROM seo.fn_ingest_keyword_research($1::jsonb, $2, $3)"
+    assert json.loads(values[0]) == research
+    assert values[1:] == ["en", None]
+
+
+def test_bare_function_name_allowed():
+    sql, values = _render_call("now", ())
+    assert sql == "SELECT * FROM now()"
+    assert values == []
+
+
+@pytest.mark.parametrize(
+    "bad",
+    [
+        "seo.fn_upsert_keyword; drop table x",
+        "seo.fn(*)",
+        "a.b.c",
+        "",
+        "seo.fn upsert",
+        "seo.fn_upsert_keyword()",
+    ],
+)
+def test_invalid_function_names_rejected(bad):
+    with pytest.raises(ValueError):
+        _render_call(bad, ())