matrx-orm 3.1.4__tar.gz → 3.1.5__tar.gz

{matrx_orm-3.1.4 → matrx_orm-3.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.4
+Version: 3.1.5
 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.4 → matrx_orm-3.1.5}/matrx_orm/core/expressions.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
+from datetime import date, datetime
+from decimal import Decimal
 from typing import Any, TYPE_CHECKING
+from uuid import UUID
 
 if TYPE_CHECKING:
     pass
@@ -533,6 +536,70 @@ def _render_func_arg(arg: Any, params: list[Any]) -> str:
     return f"${len(params)}"
 
 
+# ---------------------------------------------------------------------------
+# Type-anchoring for bound literals in a CASE branch
+# ---------------------------------------------------------------------------
+#
+# Postgres infers a bare `$N`'s type from its surrounding context. A CASE whose
+# THEN/ELSE branches are ALL bound params has NO anchor to infer from, so it
+# falls back to `text` — and asyncpg then refuses to encode a Python int/bool/
+# float into that text slot:
+#
+#     invalid input for query argument $5: 0 (expected str, got int)
+#
+# Verified live (project txzxabzwovsujtloxrus):
+#     PREPARE p AS SELECT 1 FROM t ORDER BY CASE WHEN lower(name) = $1
+#                                                THEN $2 ELSE $3 END;
+#     -> parameter_types = {text,text,text}      # $2/$3 silently become text
+#     ... THEN $2::bigint ELSE $3::bigint END
+#     -> parameter_types = {text,bigint,bigint}  # anchored
+#
+# So a CASE-branch literal is bound WITH an explicit cast: the value stays
+# parameterized (zero injection surface) and Postgres gets its type anchor.
+# Anywhere else (`col = $N`, `func($N)`) the column/signature already supplies
+# the anchor, which is why this is scoped to CASE rather than applied to every
+# bound literal — a blanket `::text` would break `uuid_col = $N`.
+#
+# Order matters: bool before int (bool IS a subclass of int), datetime before
+# date (datetime IS a subclass of date).
+_PG_LITERAL_CASTS: tuple[tuple[type, str], ...] = (
+    (bool, "boolean"),
+    (int, "bigint"),
+    (float, "double precision"),
+    (Decimal, "numeric"),
+    (datetime, "timestamptz"),
+    (date, "date"),
+    (UUID, "uuid"),
+)
+
+
+def _pg_cast_for_literal(value: Any) -> str | None:
+    """The Postgres type to anchor a bound Python literal to, or None if unknown."""
+    for py_type, pg_type in _PG_LITERAL_CASTS:
+        if isinstance(value, py_type):
+            return pg_type
+    return None
+
+
+def _render_case_result(arg: Any, params: list[Any]) -> str:
+    """Render a CASE THEN/ELSE branch, type-anchoring any bound literal.
+
+    Identical to :func:`_render_func_arg` for columns/expressions; the ONLY
+    difference is that a bound literal gets an explicit `::type` cast, because a
+    CASE branch is a context Postgres cannot infer a param's type from.
+    """
+    if arg is None:
+        # An unadorned NULL is unknown-typed too, but it unifies with whatever
+        # the sibling branch resolves to — no cast needed, and none is possible.
+        return "NULL"
+    if isinstance(arg, str) or hasattr(arg, "as_sql") or isinstance(arg, F):
+        # Bare strings are column names, per the Func-arg convention.
+        return _render_func_arg(arg, params)
+    params.append(arg)
+    cast = _pg_cast_for_literal(arg)
+    return f"${len(params)}::{cast}" if cast else f"${len(params)}"
+
+
 # ---------------------------------------------------------------------------
 # Case / When — conditional CASE WHEN ... THEN ... ELSE ... END expression
 # ---------------------------------------------------------------------------
@@ -552,8 +619,13 @@ class When:
 
     Usage::
 
-        When("lower(e.name) = $1", phrase, then=0)                    # -> WHEN lower(e.name) = $1 THEN $2
+        When("lower(e.name) = $1", phrase, then=0)                    # -> WHEN lower(e.name) = $1 THEN $2::bigint
         When("ed.src_id = ANY($1::uuid[])", ids, then="ed.dst_id")    # then = bare column, not bound
+
+    A bound ``then``/``default`` literal is rendered WITH an explicit ``::type``
+    cast — a CASE branch gives Postgres no type to infer from, so an unadorned
+    ``$N`` silently resolves to ``text`` and asyncpg then rejects a Python int
+    ("expected str, got int"). See :func:`_render_case_result`.
     """
 
     def __init__(self, condition: str, *condition_params: Any, then: Any) -> None:
@@ -569,7 +641,7 @@ class When:
             params.extend(self.condition_params)
         else:
             cond_sql = self.condition
-        then_sql = _render_func_arg(self.then, params)
+        then_sql = _render_case_result(self.then, params)
         return f"WHEN {cond_sql} THEN {then_sql}"
 
     def __repr__(self) -> str:
@@ -615,7 +687,7 @@ class Case:
         for w in self.whens:
             parts.append(w.as_sql(params))
         if self.default is not None:
-            parts.append(f"ELSE {_render_func_arg(self.default, params)}")
+            parts.append(f"ELSE {_render_case_result(self.default, params)}")
         parts.append("END")
         return " ".join(parts)
 

{matrx_orm-3.1.4 → matrx_orm-3.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.4"
+version = "3.1.5"
 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.4 → matrx_orm-3.1.5}/tests/level1/test_case_when.py

@@ -48,14 +48,14 @@ def test_case_rejects_non_when_args():
 def test_single_when_with_literal_then_and_default():
     params: list = []
     sql = Case(When("status = 'paid'", then=1), default=0).as_sql(params)
-    assert sql == "CASE WHEN status = 'paid' THEN $1 ELSE $2 END"
+    assert sql == "CASE WHEN status = 'paid' THEN $1::bigint ELSE $2::bigint END"
     assert params == [1, 0]
 
 
 def test_when_condition_with_bound_param():
     params: list = []
     sql = Case(When("lower(e.name) = $1", "acme corp", then=0), default=1).as_sql(params)
-    assert sql == "CASE WHEN lower(e.name) = $1 THEN $2 ELSE $3 END"
+    assert sql == "CASE WHEN lower(e.name) = $1 THEN $2::bigint ELSE $3::bigint END"
     assert params == ["acme corp", 0, 1]
 
 
@@ -75,7 +75,7 @@ def test_when_then_bare_column_name_not_bound():
 def test_no_default_omits_else_clause():
     params: list = []
     sql = Case(When("x = 1", then=0)).as_sql(params)
-    assert sql == "CASE WHEN x = 1 THEN $1 END"
+    assert sql == "CASE WHEN x = 1 THEN $1::bigint END"
     assert "ELSE" not in sql
 
 
@@ -86,14 +86,14 @@ def test_multiple_when_branches():
         When("tier = 'silver'", then=2),
         default=1,
     ).as_sql(params)
-    assert sql == "CASE WHEN tier = 'gold' THEN $1 WHEN tier = 'silver' THEN $2 ELSE $3 END"
+    assert sql == "CASE WHEN tier = 'gold' THEN $1::bigint WHEN tier = 'silver' THEN $2::bigint ELSE $3::bigint END"
     assert params == [3, 2, 1]
 
 
 def test_condition_params_shift_past_existing_params():
     params: list = ["existing"]
     sql = Case(When("name = $1", "bob", then=1), default=0).as_sql(params)
-    assert sql == "CASE WHEN name = $2 THEN $3 ELSE $4 END"
+    assert sql == "CASE WHEN name = $2 THEN $3::bigint ELSE $4::bigint END"
     assert params == ["existing", "bob", 1, 0]
 
 
@@ -110,7 +110,7 @@ def test_nested_case():
     params: list = []
     inner = Case(When("b = 1", then=2), default=3)
     sql = Case(When("a = 1", then=inner), default=0).as_sql(params)
-    assert sql == "CASE WHEN a = 1 THEN CASE WHEN b = 1 THEN $1 ELSE $2 END ELSE $3 END"
+    assert sql == "CASE WHEN a = 1 THEN CASE WHEN b = 1 THEN $1::bigint ELSE $2::bigint END ELSE $3::bigint END"
     assert params == [2, 3, 0]
 
 
@@ -167,7 +167,7 @@ def test_case_in_order_by():
         "-amount",
     )
     sql, params = QueryExecutor(qb._build_query())._build_query()
-    assert "ORDER BY CASE WHEN status = $1 THEN $2 ELSE $3 END ASC, amount DESC" in sql
+    assert "ORDER BY CASE WHEN status = $1 THEN $2::bigint ELSE $3::bigint END ASC, amount DESC" in sql
     assert params == ["paid", 0, 1]
 
 
@@ -181,7 +181,7 @@ def test_case_in_order_by_with_nulls_last():
     )
     sql, params = QueryExecutor(qb._build_query())._build_query()
     assert (
-        "ORDER BY CASE WHEN lower(status) = $1 THEN $2 ELSE $3 END ASC, "
+        "ORDER BY CASE WHEN lower(status) = $1 THEN $2::bigint ELSE $3::bigint END ASC, "
         "amount DESC NULLS LAST" in sql
     )
     assert params == ["paid", 0, 1]
@@ -264,3 +264,83 @@ def test_join_without_on_params_still_works_unchanged():
     sql, params = QueryExecutor(qb._build_query())._build_query()
     assert "INNER JOIN rag.kg_entities AS e2 ON e2.id = ed.src_id" in sql
     assert params == []
+
+
+# ── Type anchoring: the bug this cast exists to prevent ──────────────────────
+#
+# REGRESSION GUARD. Do NOT "simplify" the `::type` casts out of a CASE branch.
+#
+# Postgres infers a bare `$N`'s type from context. A CASE whose THEN/ELSE
+# branches are ALL bound params has NO context to infer from, so PG resolves
+# them to `text` — and asyncpg then refuses to encode a Python int:
+#
+#     asyncpg.exceptions.DataError:
+#     invalid input for query argument $5: 0 (expected str, got int)
+#
+# Verified live (project txzxabzwovsujtloxrus):
+#     ORDER BY CASE WHEN lower(name) = $1 THEN $2      ELSE $3      END
+#         -> parameter_types = {text,text,text}        # WRONG, and silent
+#     ORDER BY CASE WHEN lower(name) = $1 THEN $2::bigint ELSE $3::bigint END
+#         -> parameter_types = {text,bigint,bigint}    # anchored
+#
+# This shipped broken: every matrx-rag `rag_search` call died in _entity_recall
+# (2026-07-13). The tests above had PINNED the unanchored SQL, so the suite was
+# green while the feature was 100% down.
+
+
+def test_bound_case_literals_are_type_anchored_not_bare_params():
+    """A bound THEN/ELSE literal MUST carry an explicit cast — a bare `$N` in a
+    CASE branch is silently typed `text` by Postgres and blows up on an int."""
+    params: list = []
+    sql = Case(When("lower(e.name) = $1", "acme", then=0), default=1).as_sql(params)
+    # The int literals are bound (never inlined) AND anchored.
+    assert "THEN $2::bigint" in sql
+    assert "ELSE $3::bigint" in sql
+    assert params == ["acme", 0, 1]
+    # No branch may render as a bare, unanchored parameter.
+    assert "THEN $2 " not in sql and not sql.endswith("THEN $2")
+    assert "ELSE $3 " not in sql and "ELSE $3 END" not in sql
+
+
+@pytest.mark.parametrize(
+    "value,expected_cast",
+    [
+        (0, "bigint"),
+        (42, "bigint"),
+        (True, "boolean"),          # bool BEFORE int — bool is a subclass of int
+        (False, "boolean"),
+        (1.5, "double precision"),
+    ],
+)
+def test_case_literal_cast_per_python_type(value, expected_cast):
+    params: list = []
+    sql = Case(When("x = 1", then=value)).as_sql(params)
+    assert sql == f"CASE WHEN x = 1 THEN $1::{expected_cast} END"
+    assert params == [value]
+
+
+def test_bool_then_is_boolean_not_bigint():
+    """Guards the isinstance ordering: `isinstance(True, int)` is True, so a
+    naive int-first map would render a bool as ::bigint."""
+    params: list = []
+    sql = Case(When("x = 1", then=True), default=False).as_sql(params)
+    assert "::boolean" in sql
+    assert "::bigint" not in sql
+
+
+def test_string_then_is_still_a_bare_column_not_a_cast_param():
+    """The str-is-a-column-name convention is UNCHANGED by the anchoring —
+    a str `then` must not suddenly start binding as `$N::text`."""
+    params: list = []
+    sql = Case(When("a = 1", then="ed.dst_id"), default="ed.src_id").as_sql(params)
+    assert sql == "CASE WHEN a = 1 THEN ed.dst_id ELSE ed.src_id END"
+    assert params == []
+
+
+def test_none_then_renders_null_not_an_anchorless_param():
+    """A bound NULL is unknown-typed too; render it inline so it unifies with
+    the sibling branch instead of becoming another text param."""
+    params: list = []
+    sql = Case(When("a = 1", then=None), default=5).as_sql(params)
+    assert sql == "CASE WHEN a = 1 THEN NULL ELSE $1::bigint END"
+    assert params == [5]