matrx-orm 3.1.201__tar.gz → 3.1.202__tar.gz

{matrx_orm-3.1.201 → matrx_orm-3.1.202}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.201
+Version: 3.1.202
 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.201 → matrx_orm-3.1.202}/matrx_orm/schema_builder/diff_preview.py

@@ -725,6 +725,7 @@ def preview_schema_changes(
     from matrx_orm.core.config import register_database_from_env
     from matrx_orm.schema_builder.common import DEBUG_CONFIG, OutputConfig
     from matrx_orm.schema_builder.schema import entry_manager_flags
+    from matrx_orm.schema_builder.excluded_targets import excluded_targets, modeled_schemas
     from matrx_orm.schema_builder.schema_manager import SchemaManager
 
     caller_dir = Path(sys.argv[0]).parent.resolve()
@@ -804,6 +805,12 @@ def preview_schema_changes(
             include_tables=include_tables,
             exclude_tables=exclude_tables,
             manager_flags=manager_flags,
+            excluded_fk_targets=excluded_targets(cfg.get("generate", []), db_name),
+            modeled_schemas=modeled_schemas(
+                cfg.get("generate", []),
+                db_name,
+                next((d.get("additional_schemas") or [] for d in cfg.get("databases", []) if d.get("name") == db_name), []),
+            ),
         )
         manager.initialize()
 

matrx_orm-3.1.202/matrx_orm/schema_builder/excluded_targets.py

@@ -0,0 +1,93 @@
+"""A table excluded from generation is excluded as a REFERENCE target too.
+
+``exclude_tables`` under a schema's ``generate[]`` entry keeps that table's model out of the
+schema's file. A table in ANOTHER schema (or the same one) whose foreign key points at it would
+still emit ``ForeignKey(to_model='<Excluded>')`` and a ``get_*_with_related('<schema>.<table>')``
+manager method — a lazy reference that resolves to nothing at runtime and a relation that reads a
+table the host chose not to model. So every reference to an excluded table is dropped at load:
+the column generates as its plain type, and the relation (both directions) is not emitted.
+
+The excluded set is qualified (``schema.table``) and spans every ``generate[]`` entry of the same
+database, because the referencing table usually lives in another schema's run.
+
+The same holds for a table in a schema the host never models: a foreign key follows its table's
+oid, so once a retired table moves to ``graveyard`` every reference to it reads
+``to_schema='graveyard'`` — a class the registry can never hold. A reference whose target schema
+is neither generated nor one of the database's ``additional_schemas`` is dropped the same way.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+
+def excluded_targets(generate_list: Iterable[dict[str, Any]], database: str) -> frozenset[str]:
+    """Every ``schema.table`` an ``exclude_tables`` list names for ``database``."""
+    out: set[str] = set()
+    for entry in generate_list:
+        if entry.get("database") != database:
+            continue
+        schema = entry.get("schema") or "public"
+        for table in entry.get("exclude_tables") or ():
+            out.add(f"{schema}.{table}")
+    return frozenset(out)
+
+
+def modeled_schemas(
+    generate_list: Iterable[dict[str, Any]], database: str, additional_schemas: Iterable[str] = ()
+) -> frozenset[str]:
+    """Every schema the host models for ``database``: the generated ones and its additional schemas."""
+    out = {"public", *additional_schemas}
+    out.update(e.get("schema") or "public" for e in generate_list if e.get("database") == database)
+    return frozenset(out)
+
+
+def drop_references_to(
+    excluded: frozenset[str] | set[str],
+    *,
+    schema: str,
+    processed_objects: list[dict[str, Any]],
+    full_relationships: list[dict[str, Any]],
+    modeled: frozenset[str] | set[str] | None = None,
+) -> list[str]:
+    """Remove every reference to an excluded table, or into a schema outside ``modeled``, in place.
+
+    Returns what was dropped, for the log. ``modeled=None`` keeps every schema.
+    """
+    if not excluded and modeled is None:
+        return []
+
+    def gone(target_schema: str, table: str) -> bool:
+        return f"{target_schema}.{table}" in excluded or (modeled is not None and target_schema not in modeled)
+
+    dropped: list[str] = []
+    for obj in processed_objects:
+        for column in obj.get("table_columns") or ():
+            fk = column.get("foreign_key_reference")
+            if not isinstance(fk, dict) or not fk.get("table"):
+                continue
+            target_schema = fk.get("schema") or "public"
+            if gone(target_schema, fk["table"]):
+                column["foreign_key_reference"] = None
+                dropped.append(
+                    f"{obj.get('schema')}.{obj.get('name')}.{column.get('name')} -> {target_schema}.{fk['table']}"
+                )
+    for rel in full_relationships:
+        fks = rel.get("foreign_keys")
+        if isinstance(fks, dict):
+            for key in [
+                k
+                for k, v in fks.items()
+                if isinstance(v, dict) and gone(v.get("foreign_schema") or schema, v.get("foreign_table") or k)
+            ]:
+                fks.pop(key)
+        refs = rel.get("referenced_by")
+        if isinstance(refs, dict):
+            # Keys of referenced_by are always tables of THIS schema (bare names).
+            for key in [k for k in refs if f"{schema}.{k}" in excluded]:
+                refs.pop(key)
+    return dropped
+
+
+__all__ = ["drop_references_to", "excluded_targets", "modeled_schemas"]

{matrx_orm-3.1.201 → matrx_orm-3.1.202}/matrx_orm/schema_builder/runner.py

@@ -19,6 +19,7 @@ from dotenv import load_dotenv
 from matrx_utils import vcprint
 
 from matrx_orm.core.config import DatabaseConfigError, register_database_from_env
+from matrx_orm.schema_builder.excluded_targets import excluded_targets, modeled_schemas
 from matrx_orm.schema_builder.common import (
     DEBUG_CONFIG,
     GenerationOutputOverrides,
@@ -386,6 +387,12 @@ def run_schema_generation(
                 output_config=output_config,
                 include_tables=include_tables,
                 exclude_tables=exclude_tables,
+                excluded_fk_targets=excluded_targets(cfg.get("generate", []), db_name),
+                modeled_schemas=modeled_schemas(
+                    cfg.get("generate", []),
+                    db_name,
+                    next((d.get("additional_schemas") or [] for d in cfg.get("databases", []) if d.get("name") == db_name), []),
+                ),
                 manager_flags=manager_flags,
                 skip_unchanged_managers=skip_unchanged_managers,
                 output_overrides=output_overrides,

{matrx_orm-3.1.201 → matrx_orm-3.1.202}/matrx_orm/schema_builder/schema_manager.py

@@ -39,6 +39,8 @@ class SchemaManager:
         manager_flags: dict | None = None,
         skip_unchanged_managers: bool = False,
         output_overrides: GenerationOutputOverrides | None = None,
+        excluded_fk_targets: frozenset[str] | set[str] | None = None,
+        modeled_schemas: frozenset[str] | set[str] | None = None,
     ):
         if additional_schemas is None:
             # Read from the registered database config if a project name is provided;
@@ -93,6 +95,13 @@ class SchemaManager:
         self._exclude_tables: set[str] | None = (
             set(exclude_tables) if exclude_tables is not None else None
         )
+        #: ``schema.table`` names excluded from generation in ANY generate[] entry of this database:
+        #: a reference to one is dropped at load (``excluded_targets.drop_references_to``).
+        self._excluded_fk_targets: frozenset[str] = frozenset(excluded_fk_targets or ())
+        #: Schemas the host models; a reference into any other (``graveyard``) is dropped the same way.
+        self._modeled_schemas: frozenset[str] | None = (
+            frozenset(modeled_schemas) if modeled_schemas is not None else None
+        )
 
         vcprint(
             self.schema, title="SCHEMA MANAGER] with schema", verbose=self.verbose, color="blue"
@@ -160,6 +169,23 @@ class SchemaManager:
             self.overview_analysis,
         ) = get_db_objects(self.schema.name, self.database_project)
 
+        if self._excluded_fk_targets or self._modeled_schemas is not None:
+            from matrx_orm.schema_builder.excluded_targets import drop_references_to
+
+            dropped = drop_references_to(
+                self._excluded_fk_targets,
+                schema=self.schema.name or "public",
+                processed_objects=self.processed_objects,
+                full_relationships=self.full_relationships,
+                modeled=self._modeled_schemas,
+            )
+            if dropped:
+                vcprint(
+                    f"[MATRX ORM] {len(dropped)} reference(s) to an excluded or unmodeled table generate as plain "
+                    f"columns: {', '.join(dropped)}",
+                    color="yellow",
+                )
+
         # NOTE: no filtering here — all relationship/overview data loads in full so
         # that topological sort, FK resolution, and relationship analysis are always
         # correct.  The filter is applied in Schema.generate_models() just before

{matrx_orm-3.1.201 → matrx_orm-3.1.202}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.201"
+version = "3.1.202"
 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.202/tests/schema/test_excluded_fk_targets.py

@@ -0,0 +1,128 @@
+"""A table excluded from generation is excluded as a reference target too (excluded_targets).
+
+The host excludes workbench.udt_datasets; extend.wbx_pattern.target_user_table_id and
+workbench.udt_workbooks' inverse relation point at it. Without the rule the generated extend file
+says ``ForeignKey(to_model='UdtDatasets')`` (a lazy reference that resolves to nothing) and the
+managers grow ``get_*_with_related('workbench.udt_datasets')``.
+"""
+
+from __future__ import annotations
+
+from matrx_orm.schema_builder.excluded_targets import drop_references_to, excluded_targets
+
+GENERATE = [
+    {"database": "main", "schema": "workbench", "exclude_tables": ["udt_datasets"]},
+    {"database": "main", "schema": "extend"},
+    {"database": "cms", "schema": "public", "exclude_tables": ["udt_datasets"]},
+]
+
+
+def _extend_objects() -> list[dict]:
+    return [
+        {
+            "schema": "extend",
+            "name": "wbx_pattern",
+            "table_columns": [
+                {"name": "id", "foreign_key_reference": None},
+                {
+                    "name": "target_user_table_id",
+                    "foreign_key_reference": {"table": "udt_datasets", "schema": "workbench", "column": "id"},
+                },
+                {
+                    "name": "organization_id",
+                    "foreign_key_reference": {"table": "organizations", "schema": "iam", "column": "id"},
+                },
+            ],
+        }
+    ]
+
+
+def _extend_relationships() -> list[dict]:
+    return [
+        {
+            "table_name": "wbx_pattern",
+            "foreign_keys": {
+                "workbench.udt_datasets": {"foreign_schema": "workbench", "foreign_table": "udt_datasets"},
+                "iam.organizations": {"foreign_schema": "iam", "foreign_table": "organizations"},
+            },
+            "referenced_by": {},
+        }
+    ]
+
+
+def test_the_excluded_set_is_qualified_and_per_database() -> None:
+    assert excluded_targets(GENERATE, "main") == frozenset({"workbench.udt_datasets"})
+    assert excluded_targets(GENERATE, "cms") == frozenset({"public.udt_datasets"})
+
+
+def test_a_reference_to_an_excluded_table_becomes_a_plain_column() -> None:
+    objects, rels = _extend_objects(), _extend_relationships()
+    dropped = drop_references_to(
+        excluded_targets(GENERATE, "main"), schema="extend", processed_objects=objects, full_relationships=rels
+    )
+    columns = {c["name"]: c["foreign_key_reference"] for c in objects[0]["table_columns"]}
+    assert columns["target_user_table_id"] is None
+    assert columns["organization_id"] == {"table": "organizations", "schema": "iam", "column": "id"}
+    assert list(rels[0]["foreign_keys"]) == ["iam.organizations"]
+    assert dropped == ["extend.wbx_pattern.target_user_table_id -> workbench.udt_datasets"]
+
+
+def test_an_inverse_relation_from_an_excluded_table_is_dropped_in_its_own_schema() -> None:
+    rels = [
+        {
+            "table_name": "udt_workbooks",
+            "foreign_keys": {},
+            "referenced_by": {"udt_datasets": {"column": "workbook_id"}, "udt_workbook_snapshots": {"column": "workbook_id"}},
+        },
+        {
+            "table_name": "udt_dataset_templates",
+            "foreign_keys": {"udt_workbooks": {"foreign_schema": "workbench", "foreign_table": "udt_workbooks"}},
+            "referenced_by": {},
+        },
+    ]
+    drop_references_to(excluded_targets(GENERATE, "main"), schema="workbench", processed_objects=[], full_relationships=rels)
+    assert list(rels[0]["referenced_by"]) == ["udt_workbook_snapshots"]
+    assert list(rels[1]["foreign_keys"]) == ["udt_workbooks"]
+
+
+def test_without_an_exclusion_nothing_changes() -> None:
+    objects, rels = _extend_objects(), _extend_relationships()
+    assert drop_references_to(frozenset(), schema="extend", processed_objects=objects, full_relationships=rels) == []
+    assert objects == _extend_objects() and rels == _extend_relationships()
+
+
+def test_the_schema_manager_applies_the_rule_at_load(monkeypatch) -> None:
+    """The generator's own load path drops the reference (red when SchemaManager ignores the set)."""
+    from matrx_orm.schema_builder import schema_manager as sm
+
+    monkeypatch.setattr(
+        sm, "get_db_objects", lambda schema, project: (_extend_objects(), _extend_relationships(), {}, set(), {})
+    )
+    manager = sm.SchemaManager(
+        schema="extend", database_project=None, additional_schemas=[],
+        excluded_fk_targets=excluded_targets(GENERATE, "main"),
+    )
+    manager.set_all_schema_data()
+    column = next(c for c in manager.processed_objects[0]["table_columns"] if c["name"] == "target_user_table_id")
+    assert column["foreign_key_reference"] is None
+    assert list(manager.full_relationships[0]["foreign_keys"]) == ["iam.organizations"]
+
+
+def test_a_reference_into_an_unmodeled_schema_becomes_a_plain_column() -> None:
+    """After step two the FK follows the table into graveyard: to_schema='graveyard' is never a model."""
+    from matrx_orm.schema_builder.excluded_targets import modeled_schemas
+
+    objects = _extend_objects()
+    objects[0]["table_columns"][1]["foreign_key_reference"]["schema"] = "graveyard"
+    rels = _extend_relationships()
+    rels[0]["foreign_keys"] = {
+        "graveyard.udt_datasets": {"foreign_schema": "graveyard", "foreign_table": "udt_datasets"},
+        "iam.organizations": {"foreign_schema": "iam", "foreign_table": "organizations"},
+    }
+    modeled = modeled_schemas(GENERATE, "main", ["iam", "auth"])
+    assert "graveyard" not in modeled and {"workbench", "extend", "iam", "auth", "public"} <= modeled
+    drop_references_to(frozenset(), schema="extend", processed_objects=objects, full_relationships=rels, modeled=modeled)
+    columns = {c["name"]: c["foreign_key_reference"] for c in objects[0]["table_columns"]}
+    assert columns["target_user_table_id"] is None
+    assert columns["organization_id"] is not None
+    assert list(rels[0]["foreign_keys"]) == ["iam.organizations"]