matrx-orm 3.0.31__tar.gz → 3.0.32__tar.gz

{matrx_orm-3.0.31 → matrx_orm-3.0.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.0.31
+Version: 3.0.32
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching. Works with any PostgreSQL database.
 Project-URL: Homepage, https://github.com/armanisadeghi/matrx-orm
 Project-URL: Repository, https://github.com/armanisadeghi/matrx-orm
@@ -1838,6 +1838,7 @@ When you run the schema builder against a database that has `vector(n)` columns,
 
 | Version | Highlights |
 |---|---|
+| **v3.0.32** | Patch release |
 | **v3.0.31** | Patch release |
 | **v3.0.30** | Patch release |
 | **v3.0.29** | Patch release |

{matrx_orm-3.0.31 → matrx_orm-3.0.32}/README.md

@@ -1795,6 +1795,7 @@ When you run the schema builder against a database that has `vector(n)` columns,
 
 | Version | Highlights |
 |---|---|
+| **v3.0.32** | Patch release |
 | **v3.0.31** | Patch release |
 | **v3.0.30** | Patch release |
 | **v3.0.29** | Patch release |

{matrx_orm-3.0.31 → matrx_orm-3.0.32}/pyproject.toml

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

{matrx_orm-3.0.31 → matrx_orm-3.0.32}/src/matrx_orm/schema_builder/schema.py

@@ -778,12 +778,62 @@ class Schema:
     _database = \"{self.database_project}\"\n"""
         return users_model
 
-    def get_string_model_registry(self, sorted_tables: list[str]) -> str:
-        # Only register the models that are actually defined in this file.
-        # When include_tables / exclude_tables is active, sorted_tables is the
-        # filtered subset — registering the full schema would produce NameErrors
-        # for every class that wasn't generated.
+    def _utils_for_stubs(self):
+        return self.utils
+
+    def _generate_stub_model(self, table_name: str) -> str:
+        """Return a minimal Model stub for *table_name*.
+
+        If the table was introspected (i.e. exists in ``self.tables``), the
+        stub includes the real PK column(s) and their types.  Otherwise a
+        generic ``id = UUIDField(primary_key=True, null=False)`` is emitted.
+
+        The stub carries ``_unfetchable = True`` so the ORM never tries to
+        query through it (the real table may not be in scope).
+        """
+        utils = self._utils_for_stubs()
+        pascal_name = utils.to_pascal_case(table_name)
+
+        if table_name in self.tables:
+            table = self.tables[table_name]
+            pk_lines = []
+            for col in table.columns:
+                if col.is_primary_key:
+                    pk_lines.append(
+                        f"    {col.name} = {col.python_field_type}"
+                        f"(primary_key=True, null=False)"
+                    )
+            if not pk_lines:
+                pk_lines = ["    id = UUIDField(primary_key=True, null=False)"]
+        else:
+            pk_lines = ["    id = UUIDField(primary_key=True, null=False)"]
+
+        pk_block = "\n".join(pk_lines)
+        return (
+            f"class {pascal_name}(Model):\n"
+            f"{pk_block}\n"
+            f"    _table_name = \"{table_name}\"\n"
+            f"    _database = \"{self.database_project}\"\n"
+            f"    _unfetchable = True\n"
+        )
+
+    def get_string_model_registry(
+        self,
+        sorted_tables: list[str],
+        stub_model_names: set[str] | None = None,
+    ) -> str:
+        # Register every model class defined in the file: included tables,
+        # stub models for FK dependencies, and the Users stub.
         all_models = [self.tables[t].name_pascal for t in sorted_tables]
+        if stub_model_names:
+            utils = self._utils_for_stubs()
+            for sn in sorted(stub_model_names):
+                pascal = (
+                    self.tables[sn].name_pascal
+                    if sn in self.tables
+                    else utils.to_pascal_case(sn)
+                )
+                all_models.append(pascal)
         all_models.append("Users")  # Users stub is always generated
 
         model_registry_string = (
@@ -842,10 +892,40 @@ class Schema:
         py_structure = [self.get_string_user_model()]
         all_field_types = {"UUIDField", "CharField", "Model"}
 
-        # Build a position map so each table knows which models are defined
-        # after it in the file.  FKs to those models must use string forward
-        # references to avoid NameError from circular dependencies.
+        # --- Stub generation for FK targets outside the filtered set ----------
+        # When include_tables / exclude_tables is active, included tables may
+        # reference models that aren't being generated.  We emit minimal stub
+        # classes for those targets so FK declarations resolve without NameError
+        # and resolve_model() can find them in the registry at runtime.
+        sorted_set = set(sorted_tables)
+        _stub_model_names: set[str] = set()
+
+        if self._include_tables is not None or self._exclude_tables is not None:
+            for table_name in sorted_tables:
+                table = self.tables[table_name]
+                for col in table.columns:
+                    if col.foreign_key_reference:
+                        target_snake = col.foreign_key_reference["table"]
+                        fk_schema = col.foreign_key_reference.get("schema")
+                        if fk_schema and fk_schema != "public":
+                            continue  # cross-schema (e.g. auth.users) — stub already exists
+                        if target_snake not in sorted_set:
+                            _stub_model_names.add(target_snake)
+
+            for stub_table_name in sorted(_stub_model_names):
+                py_structure.append(
+                    self._generate_stub_model(stub_table_name)
+                )
+
+        # --- Build position map for forward-reference detection ---------------
+        # Stubs are defined before any included table (position -1 conceptually),
+        # so they never need forward references.
         _table_positions = {name: i for i, name in enumerate(sorted_tables)}
+        _defined_stubs = {
+            self.tables[s].name_pascal if s in self.tables
+            else self._utils_for_stubs().to_pascal_case(s)
+            for s in _stub_model_names
+        }
 
         for table_name in sorted_tables:
             table = self.tables[table_name]
@@ -855,9 +935,13 @@ class Schema:
                 if col.foreign_key_reference:
                     target_snake = col.foreign_key_reference["table"]
                     target_pos = _table_positions.get(target_snake)
-                    if target_pos is None or target_pos > my_pos:
+                    if target_pos is not None and target_pos > my_pos:
+                        forward_ref_tables.add(
+                            table.utils.to_pascal_case(target_snake)
+                        )
+                    elif target_pos is None:
                         target_pascal = table.utils.to_pascal_case(target_snake)
-                        if target_pascal != "Users":
+                        if target_pascal != "Users" and target_pascal not in _defined_stubs:
                             forward_ref_tables.add(target_pascal)
             py_table_entry = table.to_python_model(
                 forward_ref_tables=forward_ref_tables or None
@@ -917,7 +1001,9 @@ class Schema:
                 color="cyan",
             )
 
-        py_structure.append(self.get_string_model_registry(sorted_tables))
+        py_structure.append(
+            self.get_string_model_registry(sorted_tables, _stub_model_names)
+        )
 
         main_code = "\n".join(py_structure)
         additional_code = "\n".join(py_manager_structure)

{matrx_orm-3.0.31 → matrx_orm-3.0.32}/tests/sample_project/matrx_orm.yaml

@@ -90,6 +90,25 @@ generate:
     # This dramatically reduces git noise on large schemas. Default: false.
     # skip_unchanged_managers: true
     manager_flags:
+      # models_module_path — the Python import path used in each generated
+      # manager file to import the model class from models.py.
+      #
+      # Default: "db.models"  →  from db.models import MyModel
+      #
+      # Override this when the generated db/ package is not at the root of your
+      # Python path. For example, if your project is structured as a package:
+      #
+      #   mypackage/
+      #     db/
+      #       models.py
+      #       managers/
+      #
+      # and you import things as `from mypackage.db.models import ...`, set:
+      #
+      #   models_module_path: "mypackage.db.models"
+      #
+      # models_module_path: "db.models"
+      #
       include_core_relations: true      # FK/IFK fetch methods (load_by_*, fetch_fk, fetch_ifk)
       include_filter_fields: true       # filter_by_* methods for indexed/common lookup fields
       include_active_relations: false   # active-record style relation traversal