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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.0.30
+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,8 @@ 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 |
 | **v3.0.28** | Patch release |

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

@@ -1795,6 +1795,8 @@ 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 |
 | **v3.0.28** | Patch release |

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

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.0.30"
+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.30 → matrx_orm-3.0.32}/src/matrx_orm/schema_builder/columns.py

@@ -1266,7 +1266,7 @@ class Column:
         )
         return self.calc_max_length
 
-    def to_python_model_field(self):
+    def to_python_model_field(self, forward_ref_tables: set[str] | None = None):
         field_options = []
         if self.is_primary_key:
             field_options.append("primary_key=True")
@@ -1315,7 +1315,9 @@ class Column:
             to_schema_arg = ""
             if fk_schema and fk_schema != "public":
                 to_schema_arg = f", to_schema='{fk_schema}'"
-            if related_model == self.utils.to_pascal_case(self.table_name):
+            is_self_ref = related_model == self.utils.to_pascal_case(self.table_name)
+            is_forward_ref = forward_ref_tables is not None and related_model in forward_ref_tables
+            if is_self_ref or is_forward_ref:
                 field_def = f"{self.name} = ForeignKey(to_model='{related_model}', to_column='{self.foreign_key_reference['column']}'{to_schema_arg}, {options_str})"
             else:
                 field_def = f"{self.name} = ForeignKey(to_model={related_model}, to_column='{self.foreign_key_reference['column']}'{to_schema_arg}, {options_str})"

{matrx_orm-3.0.30 → matrx_orm-3.0.32}/src/matrx_orm/schema_builder/diff_preview.py

@@ -361,6 +361,7 @@ def parse_models_file(path: str | Path) -> tuple[dict[str, TableSnapshot], dict[
         m2m_config: dict[str, dict[str, str]] = {}
         database: str | None = None
         table_name_override: str | None = None
+        db_schema: str | None = None
 
         for item in node.body:
             if isinstance(item, (ast.Assign, ast.AnnAssign)):
@@ -395,6 +396,13 @@ def parse_models_file(path: str | Path) -> tuple[dict[str, TableSnapshot], dict[
                         pass
                     continue
 
+                if attr_name == "_db_schema":
+                    try:
+                        db_schema = ast.literal_eval(value)
+                    except (ValueError, TypeError):
+                        pass
+                    continue
+
                 if attr_name == "_inverse_foreign_keys":
                     try:
                         ifk_config = ast.literal_eval(value)
@@ -416,6 +424,12 @@ def parse_models_file(path: str | Path) -> tuple[dict[str, TableSnapshot], dict[
                     field_type, kwargs = _parse_field_call(value)
                     fields[attr_name] = _kwargs_to_field_snapshot(attr_name, field_type, kwargs)
 
+        # Skip cross-schema stub models (e.g. Users with _db_schema="auth").
+        # They are hardcoded in generate_models() and don't correspond to any
+        # introspected table in the target schema.
+        if db_schema is not None:
+            continue
+
         snake_name = table_name_override or _pascal_to_snake(class_name)
 
         snapshot = TableSnapshot(
@@ -451,6 +465,33 @@ def _pascal_to_snake(name: str) -> str:
 # Table-to-snapshot converter — extract TableSnapshot from a schema_builder Table
 # ---------------------------------------------------------------------------
 
+def _normalize_python_default(value: Any) -> Any:
+    """Apply the same default-value normalization as Column.to_python_model_field().
+
+    The generator converts raw ``clean_default["python"]`` values before writing
+    them into model source code (e.g. the string ``"false"`` becomes the Python
+    boolean ``False``).  This function mirrors that logic so the snapshot
+    produced from a Table object is directly comparable to what the AST parser
+    extracts from generated code.
+    """
+    if isinstance(value, (bool, int, float, dict, list)):
+        return value
+    if isinstance(value, str):
+        if value == "false":
+            return False
+        if value == "true":
+            return True
+        try:
+            import ast as _ast
+            parsed = _ast.literal_eval(value)
+            if isinstance(parsed, (bool, int, float, dict, list)):
+                return parsed
+            return value
+        except (ValueError, SyntaxError):
+            return value
+    return value
+
+
 def table_to_snapshot(table: Any) -> TableSnapshot:
     """Convert a schema_builder.tables.Table into a TableSnapshot."""
     from matrx_orm.schema_builder.common import dt_utils
@@ -496,7 +537,7 @@ def table_to_snapshot(table: Any) -> TableSnapshot:
         if column.clean_default is not None:
             py_default = column.clean_default.get("python")
             if py_default is not None and py_default != "":
-                default_val = repr(py_default)
+                default_val = repr(_normalize_python_default(py_default))
 
         fields[column.name] = FieldSnapshot(
             name=column.name,

{matrx_orm-3.0.30 → 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,9 +892,60 @@ class Schema:
         py_structure = [self.get_string_user_model()]
         all_field_types = {"UUIDField", "CharField", "Model"}
 
+        # --- 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]
-            py_table_entry = table.to_python_model()
+            my_pos = _table_positions[table_name]
+            forward_ref_tables: set[str] = set()
+            for col in table.columns:
+                if col.foreign_key_reference:
+                    target_snake = col.foreign_key_reference["table"]
+                    target_pos = _table_positions.get(target_snake)
+                    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" 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
+            )
             py_structure.append(py_table_entry)
             all_field_types.update(table.unique_field_types)
 
@@ -900,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.30 → matrx_orm-3.0.32}/src/matrx_orm/schema_builder/tables.py

@@ -1079,9 +1079,15 @@ class Table:
                 }
         return m2m_config
 
-    def to_python_model(self):
+    def to_python_model(self, forward_ref_tables: set[str] | None = None):
         """
         Builds the Python class model string with dynamic foreign keys.
+
+        *forward_ref_tables* is an optional set of PascalCase model names that
+        will be defined later in the file.  FKs targeting these models are
+        emitted as string forward references (``to_model='Foo'``) instead of
+        bare class references (``to_model=Foo``), avoiding ``NameError`` from
+        circular FK dependencies.
         """
         py_fields = []
         self.unique_field_types = set()
@@ -1090,7 +1096,7 @@ class Table:
 
         # Process regular fields for the model
         for column in self.columns:
-            py_field = column.to_python_model_field()
+            py_field = column.to_python_model_field(forward_ref_tables=forward_ref_tables)
             py_fields.append(py_field)
 
             if column.foreign_key_reference:

{matrx_orm-3.0.30 → 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