matrx-orm 3.1.6__tar.gz → 3.1.7__tar.gz

{matrx_orm-3.1.6 → matrx_orm-3.1.7}/BASE_CLASS_METHODS.md

@@ -1,5 +1,21 @@
 # ORM Manager Base Class Methods
 
+> **`QueryBuilder` chaining is clone-on-chain (copy-on-write), like Django's
+> `QuerySet`.** Every chain method (`.filter()`, `.exclude()`, `.order_by()`,
+> `.join()`, `.annotate()`, `.filter_raw()`, ...) returns a NEW `QueryBuilder`
+> and never mutates the one it was called on. It is safe to save a base
+> queryset and branch off it multiple times — each branch is independent:
+>
+> ```python
+> base = Model.filter(doc_id=x)
+> raw_count   = await base.exclude(raw_text="").count()
+> clean_count = await base.exclude(cleaned_text="").count()  # independent of raw_count
+> ```
+>
+> The one thing to remember: always use the RETURN VALUE of a chain call. A
+> bare `qb.filter(x=1)` statement (return discarded) is a no-op on `qb`
+> itself — reassign (`qb = qb.filter(x=1)`) or chain directly.
+
 > **Model-direct aliases (single-table work).** For small, isolated, single-table
 > work you do NOT need the manager — the generated `Model` class itself exposes
 > the same vocabulary as classmethods: `load_by_id(id)`, `load_by_id_or_none(id)`,

{matrx_orm-3.1.6 → matrx_orm-3.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.6
+Version: 3.1.7
 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.6 → matrx_orm-3.1.7}/matrx_orm/query/builder.py

@@ -127,46 +127,68 @@ class QueryBuilder(Generic[ModelT]):
     """Lazy, chainable query spec — built up via `.filter()`/`.exclude()`/etc,
     executed on `.all()`/`.count()`/`.exists()`/`.values()`/....
 
-    ⚠️ **MUTATES IN PLACE, DOES NOT CLONE.** Every chain method
-    (`.filter()`, `.exclude()`, `.join()`, `.annotate()`, `.filter_raw()`,
-    `.order_by()`, `.limit()`, ...) appends to `self`'s internal lists/dicts
-    and returns `self` — it is Django-`QuerySet`-SHAPED but NOT
-    Django-`QuerySet`-SAFE: Django clones on every chain call so branching
-    off a saved queryset is side-effect-free; this builder does not, so
-    branching off a saved builder ACCUMULATES.
-
-    Concretely, this is a bug, not a style nit::
-
-        pages_qs = Model.filter(doc_id=x)
-        a = await pages_qs.exclude(raw_text="").count()
-        b = await pages_qs.exclude(cleaned_text="").count()  # BUG: still has
-            # the raw_text exclude from the line above — `b` silently counts
-            # "NOT raw_text AND NOT cleaned_text", not just "NOT cleaned_text".
-
-    (This exact shape shipped in `aidream/services/rag/library_status.py`;
-    see the fix + comment there for the corrected pattern.)
-
-    **The safe patterns:**
-      - Reassign every time: `qb = qb.filter_raw(...)` (fine — no branching
-        off a shared base after the reassignment).
-      - Build a FRESH queryset for each independent read:
-        `await Model.filter(x=1).exclude(a="").count()` and
-        `await Model.filter(x=1).exclude(b="").count()` as two separate
-        expressions, never sharing a `pages_qs`-style variable across calls
-        that each need a different filter set.
-      - If you truly need to branch off one shared base, don't reuse the
-        builder object itself — reissue `Model.filter(...)` (or whatever
-        built the base) for each branch.
-
-    This is intentional current behavior, not an oversight to "just fix" —
-    switching to clone-on-chain is a real, wide-blast-radius ORM change
-    (every `matrx-*` package + `aidream/services/*` calls this) that needs
-    its own audited migration, not a silent semantic flip. Tracked as a
-    platform follow-up; see `tests/level1/test_querybuilder_mutation_semantics.py`
-    for the pinned-current-behavior regression test that must be updated
-    (not just deleted) the day this changes.
+    **Clone-on-chain (copy-on-write) — Django-`QuerySet`-SAFE.** Every chain
+    method (`.filter()`, `.exclude()`, `.join()`, `.annotate()`,
+    `.filter_raw()`, `.order_by()`, `.limit()`, ...) returns a NEW
+    `QueryBuilder` that shares nothing mutable with `self` — the original
+    builder is never modified. This matches Django's `QuerySet`: branching
+    off a saved queryset is side-effect-free, and reusing a variable across
+    independent calls no longer accumulates state.
+
+    ::
+
+        base = Model.filter(doc_id=x)
+        raw_count   = await base.exclude(raw_text="").count()
+        clean_count = await base.exclude(cleaned_text="").count()
+        # Independent — `clean_count` does NOT carry the raw_text exclude.
+        # `base` itself is untouched by either branch.
+
+    (Before this, the two branches above bled into each other — the exact
+    shape that shipped a real count-corruption bug in
+    `aidream/services/rag/library_status.py`, worked around there by
+    building fresh querysets. That workaround is no longer required, though
+    still harmless.)
+
+    **Still true:** always use the RETURN VALUE of a chain call — a bare
+    `qb.filter(x=1)` statement (return discarded, not reassigned) is now a
+    no-op on `qb` itself (the filter lives only on the discarded clone).
+    Reassign (`qb = qb.filter(x=1)`) or chain directly
+    (`Model.filter(x=1).exclude(y=2)`).
+
+    Terminal methods (`.all()`, `.first()`, `.get()`, `.count()`,
+    `.exists()`, `.values()`, `.update()`, `.delete()`, `.aggregate()`, ...)
+    execute the query and do NOT clone.
     """
 
+    def _clone(self) -> QueryBuilder[ModelT]:
+        """Return a new QueryBuilder sharing `self`'s scalar state but with
+        every mutable container (lists/dicts/sets this builder appends to)
+        copied — so mutating the clone's containers never touches `self`'s,
+        and vice versa. Elements inside those containers (filter dicts, Q
+        objects, join specs, ...) are treated as immutable value objects and
+        are NOT deep-copied — only the containers themselves are copied.
+        """
+        new = self.__class__.__new__(self.__class__)
+        new.__dict__.update(self.__dict__)
+        new.filters = list(self.filters)
+        new.excludes = list(self.excludes)
+        new.order_by_fields = list(self.order_by_fields)
+        new.select_fields = list(self.select_fields)
+        new.deferred_fields = set(self.deferred_fields)
+        new.only_fields = set(self.only_fields)
+        new.prefetch_fields = list(self.prefetch_fields)
+        new.joins = list(self.joins)
+        new.group_by_fields = list(self.group_by_fields)
+        new.having_filters = list(self.having_filters)
+        new.aggregations = list(self.aggregations)
+        new.distinct_fields = list(self.distinct_fields) if self.distinct_fields is not None else None
+        new.for_update_opts = dict(self.for_update_opts) if self.for_update_opts is not None else None
+        new.select_related_fields = list(self.select_related_fields)
+        new.ctes = list(self.ctes)
+        new.vector_order = dict(self.vector_order) if self.vector_order is not None else None
+        new.raw_filters = list(self.raw_filters)
+        return new
+
     model: type[ModelT]
     database: str
     filters: list[Any]  # dict[str,Any] or Q objects
@@ -235,18 +257,17 @@ class QueryBuilder(Generic[ModelT]):
             .filter(Q(status="active") | Q(role="admin"))
             .filter(Q(a=1), b=2)          # AND composition
 
-        ⚠️ Mutates `self` and returns it — does NOT clone (see the class
-        docstring). Reusing a saved builder across independent branches
-        accumulates filters onto every branch.
+        Clone-on-chain: returns a NEW builder; `self` is unchanged.
         """
         from ..core.expressions import Exists, Q, TsMatch
 
+        new = self._clone()
         for arg in args:
             # Positional predicate expressions the executor renders from the
             # filters list: Q, Exists(...) (correlated subquery), and
             # TsMatch(...) (full-text WHERE match).
             if isinstance(arg, (Q, Exists, TsMatch)):
-                self.filters.append(arg)
+                new.filters.append(arg)
             else:
                 raise TypeError(
                     "Positional filter argument must be a Q, Exists, or TsMatch object, "
@@ -254,8 +275,8 @@ class QueryBuilder(Generic[ModelT]):
                 )
         if kwargs:
             self._validate_filter_keys(kwargs)
-            self.filters.append(kwargs)
-        return self
+            new.filters.append(kwargs)
+        return new
 
     def _validate_filter_keys(self, kwargs: dict[str, Any]) -> None:
         """Reject filter kwargs whose field/operator don't exist on the model.
@@ -330,15 +351,15 @@ class QueryBuilder(Generic[ModelT]):
     def exclude(self, **kwargs: Any) -> QueryBuilder[ModelT]:
         """Apply SQL exclusion filters.
 
-        ⚠️ Mutates `self` and returns it — does NOT clone (see the class
-        docstring). Calling `.exclude()` twice off the SAME saved builder
-        variable ANDs both excludes together onto one query — it does not
-        give you two independent counts. Build a fresh queryset per
-        independent read instead.
+        Clone-on-chain: returns a NEW builder; `self` is unchanged. Calling
+        `.exclude()` twice off the SAME saved builder variable now gives two
+        INDEPENDENT branches (each excludes only its own kwargs) — it does
+        not AND both excludes together the way in-place mutation used to.
         """
+        new = self._clone()
         if kwargs:
-            self.excludes.append(kwargs)
-        return self
+            new.excludes.append(kwargs)
+        return new
 
     def filter_raw(self, sql: str, *params: Any) -> QueryBuilder[ModelT]:
         """Add a parametrized raw SQL fragment to the WHERE clause (AND-ed).
@@ -392,33 +413,40 @@ class QueryBuilder(Generic[ModelT]):
                 f"but found placeholders {sorted(found) or 'none'} for {len(params)} param(s).\n"
                 f"  SQL: {sql!r}"
             )
-        self.raw_filters.append((sql, list(params)))
-        return self
+        new = self._clone()
+        new.raw_filters.append((sql, list(params)))
+        return new
 
     def order_by(self, *fields: str | Any) -> QueryBuilder[ModelT]:
-        self.order_by_fields.extend(fields)
-        return self
+        new = self._clone()
+        new.order_by_fields.extend(fields)
+        return new
 
     def limit(self, value: int) -> QueryBuilder[ModelT]:
-        self.limit_val = value
-        return self
+        new = self._clone()
+        new.limit_val = value
+        return new
 
     def offset(self, value: int) -> QueryBuilder[ModelT]:
-        self.offset_val = value
-        return self
+        new = self._clone()
+        new.offset_val = value
+        return new
 
     def select(self, *fields: str) -> QueryBuilder[ModelT]:
-        self.select_fields.extend(fields)
-        return self
+        new = self._clone()
+        new.select_fields.extend(fields)
+        return new
 
     def prefetch_related(self, *fields: str) -> QueryBuilder[ModelT]:
-        self.prefetch_fields.extend(fields)
-        return self
+        new = self._clone()
+        new.prefetch_fields.extend(fields)
+        return new
 
     def select_related(self, *fields: str) -> QueryBuilder[ModelT]:
         """Eager-load FK targets via JOIN in the same query (no N+1)."""
-        self.select_related_fields.extend(fields)
-        return self
+        new = self._clone()
+        new.select_related_fields.extend(fields)
+        return new
 
     def join(
         self,
@@ -482,7 +510,8 @@ class QueryBuilder(Generic[ModelT]):
             on_sql, on_params = partner.render()
             qb.join(KgEntities, on=f"e2.id = {on_sql}", on_params=on_params, alias="e2")
         """
-        self.joins.append(
+        new = self._clone()
+        new.joins.append(
             {
                 "model": model_cls,
                 "on": on,
@@ -491,15 +520,17 @@ class QueryBuilder(Generic[ModelT]):
                 "on_params": list(on_params) if on_params else [],
             }
         )
-        return self
+        return new
 
     def group_by(self, *fields: str) -> QueryBuilder[ModelT]:
-        self.group_by_fields.extend(fields)
-        return self
+        new = self._clone()
+        new.group_by_fields.extend(fields)
+        return new
 
     def having(self, **kwargs: Any) -> QueryBuilder[ModelT]:
-        self.having_filters.append(kwargs)
-        return self
+        new = self._clone()
+        new.having_filters.append(kwargs)
+        return new
 
     def annotate(self, **kwargs: Any) -> QueryBuilder[ModelT]:
         """Add computed columns (aggregates or functions) to the SELECT.
@@ -508,9 +539,10 @@ class QueryBuilder(Generic[ModelT]):
 
             .annotate(total=Sum("amount"), name_lower=Lower("username"))
         """
+        new = self._clone()
         for key, value in kwargs.items():
-            self.aggregations.append({"name": key, "function": value})
-        return self
+            new.aggregations.append({"name": key, "function": value})
+        return new
 
     def distinct(self, *fields: str) -> QueryBuilder[ModelT]:
         """Add DISTINCT or DISTINCT ON to the query.
@@ -518,8 +550,9 @@ class QueryBuilder(Generic[ModelT]):
         No args  → ``SELECT DISTINCT ...``
         With args → ``SELECT DISTINCT ON (f1, f2) ...`` (PostgreSQL-specific)
         """
-        self.distinct_fields = list(fields)
-        return self
+        new = self._clone()
+        new.distinct_fields = list(fields)
+        return new
 
     def select_for_update(
         self,
@@ -531,8 +564,9 @@ class QueryBuilder(Generic[ModelT]):
 
         Must be used inside a transaction.
         """
-        self.for_update_opts = {"nowait": nowait, "skip_locked": skip_locked, "of": of or []}
-        return self
+        new = self._clone()
+        new.for_update_opts = {"nowait": nowait, "skip_locked": skip_locked, "of": of or []}
+        return new
 
     def using(self, database: str) -> QueryBuilder[ModelT]:
         """Override the database for this query.
@@ -541,8 +575,9 @@ class QueryBuilder(Generic[ModelT]):
 
             await User.filter(is_active=True).using("replica").all()
         """
-        self.database = database
-        return self
+        new = self._clone()
+        new.database = database
+        return new
 
     def timeout(self, seconds: float) -> QueryBuilder[ModelT]:
         """Override the STATEMENT timeout for this query only (seconds).
@@ -566,8 +601,9 @@ class QueryBuilder(Generic[ModelT]):
         """
         if seconds is not None and seconds <= 0:
             raise ValueError(f"timeout() requires a positive number of seconds, got {seconds!r}")
-        self.timeout_val = seconds
-        return self
+        new = self._clone()
+        new.timeout_val = seconds
+        return new
 
     def from_alias(self, alias: str) -> QueryBuilder[ModelT]:
         """Alias the base (FROM) table — renders ``FROM <table> AS <alias>``.
@@ -589,8 +625,9 @@ class QueryBuilder(Generic[ModelT]):
                 f"from_alias must be a plain ASCII identifier, got {alias!r} — it is "
                 "trusted, code-supplied text (a short alias like 'c'), never user input"
             )
-        self.from_alias_name = alias
-        return self
+        new = self._clone()
+        new.from_alias_name = alias
+        return new
 
     def only(self, *fields: str) -> QueryBuilder[ModelT]:
         """Load only these columns. Unlisted columns on the model instance will be None.
@@ -599,9 +636,10 @@ class QueryBuilder(Generic[ModelT]):
 
             await User.filter(is_active=True).only("id", "email").all()
         """
-        self.only_fields = set(fields)
-        self.select_fields = list(fields)
-        return self
+        new = self._clone()
+        new.only_fields = set(fields)
+        new.select_fields = list(fields)
+        return new
 
     def defer(self, *fields: str) -> QueryBuilder[ModelT]:
         """Exclude these columns from the SELECT. They will be None on the returned instances.
@@ -610,8 +648,9 @@ class QueryBuilder(Generic[ModelT]):
 
             await User.filter(is_active=True).defer("large_blob", "heavy_json").all()
         """
-        self.deferred_fields = set(fields)
-        return self
+        new = self._clone()
+        new.deferred_fields = set(fields)
+        return new
 
     def with_cte(self, *ctes: Any) -> QueryBuilder[ModelT]:
         """Prepend one or more CTEs (WITH clauses) to the query.
@@ -627,8 +666,9 @@ class QueryBuilder(Generic[ModelT]):
             tree = CTE("org_tree", raw_recursive_sql, recursive=True)
             rows = await Org.filter().with_cte(tree).raw_sql(\"SELECT * FROM org_tree\")
         """
-        self.ctes.extend(ctes)
-        return self
+        new = self._clone()
+        new.ctes.extend(ctes)
+        return new
 
     def nearest(
         self,
@@ -665,20 +705,22 @@ class QueryBuilder(Generic[ModelT]):
             for doc in results:
                 print(doc._vector_distance, doc.title)
         """
-        self.vector_order = {"column": column, "vector": vector, "metric": metric}
-        self.vector_null_guard = null_guard
-        return self
+        new = self._clone()
+        new.vector_order = {"column": column, "vector": vector, "metric": metric}
+        new.vector_null_guard = null_guard
+        return new
 
     def reverse(self) -> QueryBuilder[ModelT]:
         """Reverse each ordering term."""
+        new = self._clone()
         reversed_fields = []
-        for term in self.order_by_fields:
+        for term in new.order_by_fields:
             if isinstance(term, str):
                 reversed_fields.append(term[1:] if term.startswith("-") else f"-{term}")
             else:
                 reversed_fields.append(term)
-        self.order_by_fields = reversed_fields
-        return self
+        new.order_by_fields = reversed_fields
+        return new
 
     # ------------------------------------------------------------------
     # Internal query dict construction
@@ -814,8 +856,7 @@ class QueryBuilder(Generic[ModelT]):
         """Order by primary key (all columns, for composite PKs) descending
         and fetch the first record."""
         pk_names = self.model._meta.primary_keys or ["id"]
-        self.order_by(*(f"-{pk}" for pk in pk_names))
-        return await self.first()
+        return await self.order_by(*(f"-{pk}" for pk in pk_names)).first()
 
     async def get(self) -> ModelT:
         """Retrieve exactly one matching record; raises if 0 or >1 found.
@@ -917,11 +958,14 @@ class QueryBuilder(Generic[ModelT]):
                 total=Sum("amount"), avg=Avg("amount"), count=Count("id")
             )
         """
-        if kwargs:
-            for key, value in kwargs.items():
-                self.aggregations.append({"name": key, "function": value})
+        # Terminal, but takes query-shaping args — build on a clone so `self`
+        # is never mutated (clone-on-chain contract: a reused base builder must
+        # stay pristine after a derived .aggregate() call).
+        target = self._clone() if kwargs else self
+        for key, value in kwargs.items():
+            target.aggregations.append({"name": key, "function": value})
         try:
-            return await self._get_executor().aggregate()
+            return await target._get_executor().aggregate()
         except ORMException as e:
             e.enrich(
                 model=self.model, operation="aggregate", filters=self._merge_filters_excludes()
@@ -929,9 +973,10 @@ class QueryBuilder(Generic[ModelT]):
             raise
 
     async def values(self, *fields: str) -> list[dict[str, Any]]:
+        target = self._clone() if fields else self
         if fields:
-            self.select_fields = list(fields)
-        return await self._get_executor().values()
+            target.select_fields = list(fields)
+        return await target._get_executor().values()
 
     def compile(self, *fields: str) -> tuple[str, list[Any]]:
         """Build the SELECT SQL + bound-parameter list WITHOUT executing.
@@ -950,9 +995,10 @@ class QueryBuilder(Generic[ModelT]):
                 await conn.execute("SET LOCAL hnsw.iterative_scan = 'relaxed_order'")
                 rows = await conn.fetch(sql, *params)
         """
+        target = self._clone() if fields else self
         if fields:
-            self.select_fields = list(fields)
-        return self._get_executor()._build_query()
+            target.select_fields = list(fields)
+        return target._get_executor()._build_query()
 
     async def fetch_via(
         self,
@@ -1000,9 +1046,10 @@ class QueryBuilder(Generic[ModelT]):
     async def values_list(
         self, *fields: str, flat: bool = False
     ) -> list[tuple[Any, ...]] | list[Any]:
+        target = self._clone() if fields else self
         if fields:
-            self.select_fields = list(fields)
-        return await self._get_executor().values_list(flat=flat)
+            target.select_fields = list(fields)
+        return await target._get_executor().values_list(flat=flat)
 
     # ------------------------------------------------------------------
     # Synchronous wrappers
@@ -1047,8 +1094,9 @@ class QueryBuilder(Generic[ModelT]):
         if isinstance(k, slice):
             start = k.start or 0
             stop = k.stop if k.stop is not None else 0
+            new = self
             if stop > 0:
-                self.limit(stop - start)
-            self.offset(start)
-            return self
+                new = new.limit(stop - start)
+            new = new.offset(start)
+            return new
         raise TypeError("Index access not supported, use slicing")

{matrx_orm-3.1.6 → matrx_orm-3.1.7}/matrx_orm/schema_builder/code_handler.py

@@ -2,14 +2,14 @@ from __future__ import annotations
 
 import os
 
-from matrx_utils.file_handling.specific_handlers.code_handler import CodeHandler
+from matrx_orm.schema_builder.codegen_writer import CodegenWriter
 
 from matrx_orm.schema_builder.common import OutputConfig
 
 
-class SchemaCodeHandler(CodeHandler):
+class SchemaCodeHandler(CodegenWriter):
     """
-    Thin subclass of CodeHandler that gates file writes based on OutputConfig.
+    Thin subclass of CodegenWriter that gates file writes based on OutputConfig.
 
     - generate_and_save_code_from_object: skipped when the file extension is
       .py (python=False) or .ts (typescript=False).

matrx_orm-3.1.7/matrx_orm/schema_builder/codegen_writer.py

@@ -0,0 +1,114 @@
+"""ORM-internal codegen file writer.
+
+Replaces the former dependency on the platform file system's ``CodeHandler``
+(now in matrx-files) with the ~80 lines of behavior the schema builder
+actually uses: assemble code sections, write generated files under
+``settings.BASE_DIR/temp/code_generator/…`` (or directly to their final path
+when ``save_direct``), and dump JSON artifacts. Paths and semantics are
+byte-compatible with the old CodeHandler so `python db/generate.py` output
+lands exactly where it always has.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from matrx_utils import print_link, to_matrx_json, vcprint
+from matrx_utils.conf import settings
+
+_APP_NAME = "code_generator"
+_CODE_ROOT = "code"
+
+
+class CodegenWriter:
+    """Minimal file writer for schema-builder output. Not a FileManager."""
+
+    def __init__(self, save_direct: bool = False):
+        self.save_direct = save_direct
+        self.verbose = False
+        self._written: list[str] = []
+
+    @property
+    def temp_dir(self) -> Path:
+        return Path(settings.BASE_DIR) / "temp" / _APP_NAME
+
+    # -- primitives ---------------------------------------------------------
+
+    def _write(self, full_path: Path, content: str) -> None:
+        full_path = Path(os.path.normpath(str(full_path)))
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+        full_path.write_text(content, encoding="utf-8")
+        self._written.append(str(full_path))
+
+    def save_code_file(self, file_path: str, content: str) -> None:
+        self._write(self.temp_dir / _CODE_ROOT / file_path, content)
+
+    def save_code_anywhere(self, path: str, content: str) -> None:
+        self._write(Path(path), content)
+
+    def write_to_json(self, path: str, data: Any, root: str = "temp", clean: bool = True) -> bool:
+        payload = to_matrx_json(data) if clean else json.dumps(data, indent=2, ensure_ascii=False)
+        if not isinstance(payload, str):
+            payload = json.dumps(payload, indent=2, ensure_ascii=False, default=str)
+        self._write(self.temp_dir / path, payload)
+        return True
+
+    # -- section assembly (byte-compatible with the old CodeHandler) --------
+
+    def generate_and_save_code(
+        self,
+        temp_path: str,
+        main_code: str,
+        file_location: str | None = None,
+        import_lines: list[str] | str | None = None,
+        additional_top_lines: list[str] | str | None = None,
+        additional_bottom_lines: list[str] | str | None = None,
+        additional_code: list[str] | str | None = None,
+        path: str | None = None,
+    ) -> None:
+        sections: list[str] = []
+        if file_location:
+            sections.append(file_location)
+        for section in [import_lines, additional_top_lines, [main_code], additional_code, additional_bottom_lines]:
+            if section:
+                if isinstance(section, str):
+                    section = [section]
+                sections.extend(section)
+                sections.append("")
+        code_content = "\n".join(sections).strip()
+
+        if self.save_direct:
+            if path is None:
+                raise ValueError("CodegenWriter: save_direct=True requires an explicit path")
+            self.save_code_anywhere(path, code_content)
+        else:
+            self.save_code_file(temp_path, code_content)
+
+    def generate_and_save_code_from_object(
+        self, config_obj: dict, main_code: str, additional_code: list[str] | str | None = None
+    ) -> None:
+        temp_path = config_obj["temp_path"]
+        path = os.path.join(config_obj["root"], temp_path)
+        self.generate_and_save_code(
+            temp_path,
+            main_code,
+            config_obj.get("file_location"),
+            config_obj.get("import_lines"),
+            config_obj.get("additional_top_lines"),
+            config_obj.get("additional_bottom_lines"),
+            additional_code,
+            path,
+        )
+
+    # -- reporting -----------------------------------------------------------
+
+    def print_all_batched(self) -> None:
+        if not self._written:
+            return
+        vcprint(f"[schema builder] {len(self._written)} file(s) written:", color="green")
+        for p in self._written:
+            print_link(p)
+        self._written.clear()

{matrx_orm-3.1.6 → matrx_orm-3.1.7}/pyproject.toml

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

@@ -55,7 +55,10 @@ class TestFilterRawBuilderState:
     def test_is_chainable(self):
         C = _make_chunk_model()
         qb = QueryBuilder(C)
-        assert qb.filter_raw("x = $1", 1) is qb
+        derived = qb.filter_raw("x = $1", 1)
+        assert isinstance(derived, QueryBuilder)
+        assert derived is not qb, "filter_raw() clones on chain — it must not return `self`"
+        assert qb.raw_filters == [], "the original builder must be unchanged"
 
     def test_build_query_carries_raw_filters(self):
         C = _make_chunk_model()