pytest-orm-boundaries 0.3.1__tar.gz → 0.4.0__tar.gz

{pytest_orm_boundaries-0.3.1 → pytest_orm_boundaries-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-orm-boundaries
-Version: 0.3.1
+Version: 0.4.0
 Summary: Pytest plugin that fails tests when ORM queries cross DDD aggregate boundaries (Django supported today).
 Keywords: django,pytest,plugin,orm,ddd,aggregate,boundaries,architecture
 Author: Evgeniia Chibisova
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Testing
 Requires-Dist: pytest>=8
+Requires-Dist: sqlglot>=30,<31
 Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/evchibisova/pytest-orm-boundaries
 Project-URL: Repository, https://github.com/evchibisova/pytest-orm-boundaries
@@ -41,9 +42,9 @@ lookups make it easy to cross those boundaries silently:
 Purchase.objects.get(client__name="John")
 ```
 
-`pytest-orm-boundaries` watches the queries your test suite executes and
-reports the ones that step outside their aggregate, whether through `__`
-lookups, subqueries, or other joins.
+`pytest-orm-boundaries` watches the SQL your test suite executes and reports the
+queries that step outside their aggregate — whether through `__` lookups,
+`select_related`, subqueries, or hand-written `.raw()` SQL.
 
 ## Install
 
@@ -68,6 +69,50 @@ purchase = ["bookshop.Purchase", "bookshop.PurchaseLine"]
 Models are written as `app_label.Model`. Models not listed in any aggregate are
 not checked. Without a config file the plugin emits a warning and runs no checks.
 
+## What it catches
+
+The plugin works from the SQL your suite actually executes, so it flags any
+single statement that reads tables from two different aggregates - however the
+query was written. Each example below joins the `purchase` and `client` aggregates:
+
+- `__` relation lookups:
+
+  ```python
+  Purchase.objects.get(client__name="John")
+  ```
+
+- `select_related`
+
+  ```python
+  Purchase.objects.select_related("client")
+  ```
+
+- Subqueries - a table reached through a subquery still counts:
+
+  ```python
+  berlin_clients = Client.objects.filter(city="Berlin").values("id")
+  Purchase.objects.filter(client_id__in=berlin_clients)
+  ```
+
+- Hand-written `.raw()` SQL:
+
+  ```python
+  Purchase.objects.raw(
+      "SELECT p.id FROM bookshop_purchase p "
+      "JOIN bookshop_client c ON p.client_id = c.id"
+  )
+  ```
+
+- Bare `cursor.execute()` - the same join reached through a raw cursor.
+
+Queries that don't actually join across the boundary are **not** flagged — for
+example a foreign-key lookup by id, which Django resolves without a join:
+
+```python
+Purchase.objects.filter(client_id=42)     # reads one table
+Purchase.objects.filter(client__pk=42)    # Django trims the join
+```
+
 ## The report
 
 At the end of the run, the plugin prints one grouped entry per offending place:
@@ -76,17 +121,18 @@ At the end of the run, the plugin prints one grouped entry per offending place:
 ===================== orm-boundaries: boundary violations ======================
 1 place(s) in your code crossed aggregate boundaries, affecting 1 test(s):
 
-bookshop/purchases.py:29
-    code: return list(Purchase.objects.filter(client__name=name))
-    crosses: client, purchase
-    affected tests (1):
-      test_purchases.py::test_get_purchases_by_client_name
+bookshop/reports.py:13
+    crossed aggregates: client ↔ purchase
+    models: bookshop.Client, bookshop.Purchase
+    1 test(s) affected:
+      test_purchases.py::test_list_purchases_with_client
 
 orm-boundaries: FAILED - 1 boundary violation(s), run exits non-zero.
 ```
 
-The run exits non-zero when there are violations, so CI catches them.
-Pass `-v` to list all affected tests.
+Each entry names the aggregates the query crossed and the models it joined.
+Places are ordered by how many tests they affect. Pass `-v` to see every affected test
+(otherwise the list is capped at 5 per place).
 
 ## Ignoring files
 
@@ -116,6 +162,10 @@ Remove them from boundaries.toml:
   - app/billing.py
 ```
 
+## Known gaps
+
+- `prefetch_related` loads doesn't detected in current version.
+
 ## Status
 
 Alpha - testing basic version.

{pytest_orm_boundaries-0.3.1 → pytest_orm_boundaries-0.4.0}/README.md

@@ -15,9 +15,9 @@ lookups make it easy to cross those boundaries silently:
 Purchase.objects.get(client__name="John")
 ```
 
-`pytest-orm-boundaries` watches the queries your test suite executes and
-reports the ones that step outside their aggregate, whether through `__`
-lookups, subqueries, or other joins.
+`pytest-orm-boundaries` watches the SQL your test suite executes and reports the
+queries that step outside their aggregate — whether through `__` lookups,
+`select_related`, subqueries, or hand-written `.raw()` SQL.
 
 ## Install
 
@@ -42,6 +42,50 @@ purchase = ["bookshop.Purchase", "bookshop.PurchaseLine"]
 Models are written as `app_label.Model`. Models not listed in any aggregate are
 not checked. Without a config file the plugin emits a warning and runs no checks.
 
+## What it catches
+
+The plugin works from the SQL your suite actually executes, so it flags any
+single statement that reads tables from two different aggregates - however the
+query was written. Each example below joins the `purchase` and `client` aggregates:
+
+- `__` relation lookups:
+
+  ```python
+  Purchase.objects.get(client__name="John")
+  ```
+
+- `select_related`
+
+  ```python
+  Purchase.objects.select_related("client")
+  ```
+
+- Subqueries - a table reached through a subquery still counts:
+
+  ```python
+  berlin_clients = Client.objects.filter(city="Berlin").values("id")
+  Purchase.objects.filter(client_id__in=berlin_clients)
+  ```
+
+- Hand-written `.raw()` SQL:
+
+  ```python
+  Purchase.objects.raw(
+      "SELECT p.id FROM bookshop_purchase p "
+      "JOIN bookshop_client c ON p.client_id = c.id"
+  )
+  ```
+
+- Bare `cursor.execute()` - the same join reached through a raw cursor.
+
+Queries that don't actually join across the boundary are **not** flagged — for
+example a foreign-key lookup by id, which Django resolves without a join:
+
+```python
+Purchase.objects.filter(client_id=42)     # reads one table
+Purchase.objects.filter(client__pk=42)    # Django trims the join
+```
+
 ## The report
 
 At the end of the run, the plugin prints one grouped entry per offending place:
@@ -50,17 +94,18 @@ At the end of the run, the plugin prints one grouped entry per offending place:
 ===================== orm-boundaries: boundary violations ======================
 1 place(s) in your code crossed aggregate boundaries, affecting 1 test(s):
 
-bookshop/purchases.py:29
-    code: return list(Purchase.objects.filter(client__name=name))
-    crosses: client, purchase
-    affected tests (1):
-      test_purchases.py::test_get_purchases_by_client_name
+bookshop/reports.py:13
+    crossed aggregates: client ↔ purchase
+    models: bookshop.Client, bookshop.Purchase
+    1 test(s) affected:
+      test_purchases.py::test_list_purchases_with_client
 
 orm-boundaries: FAILED - 1 boundary violation(s), run exits non-zero.
 ```
 
-The run exits non-zero when there are violations, so CI catches them.
-Pass `-v` to list all affected tests.
+Each entry names the aggregates the query crossed and the models it joined.
+Places are ordered by how many tests they affect. Pass `-v` to see every affected test
+(otherwise the list is capped at 5 per place).
 
 ## Ignoring files
 
@@ -90,6 +135,10 @@ Remove them from boundaries.toml:
   - app/billing.py
 ```
 
+## Known gaps
+
+- `prefetch_related` loads doesn't detected in current version.
+
 ## Status
 
 Alpha - testing basic version.

{pytest_orm_boundaries-0.3.1 → pytest_orm_boundaries-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pytest-orm-boundaries"
-version = "0.3.1"
+version = "0.4.0"
 description = "Pytest plugin that fails tests when ORM queries cross DDD aggregate boundaries (Django supported today)."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -33,7 +33,7 @@ classifiers = [
     "Topic :: Software Development :: Quality Assurance",
     "Topic :: Software Development :: Testing",
 ]
-dependencies = ["pytest>=8"]
+dependencies = ["pytest>=8", "sqlglot>=30,<31"]
 
 [project.urls]
 Homepage = "https://github.com/evchibisova/pytest-orm-boundaries"
@@ -44,6 +44,9 @@ Changelog = "https://github.com/evchibisova/pytest-orm-boundaries/blob/main/CHAN
 [project.entry-points.pytest11]
 boundaries = "pytest_orm_boundaries.plugin"
 
+[tool.uv]
+exclude-newer = "2 weeks"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 

pytest_orm_boundaries-0.3.1/src/pytest_orm_boundaries/call_stack.py → pytest_orm_boundaries-0.4.0/src/pytest_orm_boundaries/callstack.py

@@ -15,7 +15,7 @@ def _is_third_party(*, relative: Path) -> bool:
     return not _THIRD_PARTY_SEGMENTS.isdisjoint(relative.parts)
 
 
-def find_in_project_frames(*, root: Path) -> list[tuple[str, int]]:
+def find_frames_inside_project(*, root: Path) -> list[tuple[str, int]]:
     """(root-relative path, line) for each in-project frame, innermost first.
 
     Skips stdlib (outside root) and installed packages; frames[0] is the line

{pytest_orm_boundaries-0.3.1 → pytest_orm_boundaries-0.4.0}/src/pytest_orm_boundaries/guard.py

@@ -1,27 +1,26 @@
-"""Django boundary guard: the aggregate-crossing rule and the query
-interception that records crossings.
+"""Django boundary guard: applies the aggregate-crossing rule to the queries a
+test suite executes and records the crossings.
 """
 
 from __future__ import annotations
 
-import functools
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from pytest_orm_boundaries.call_stack import find_in_project_frames
-from pytest_orm_boundaries.ignores import IgnoreTracker
-from pytest_orm_boundaries.read_config import (
+from pytest_orm_boundaries.callstack import find_frames_inside_project
+from pytest_orm_boundaries.config import (
     load_aggregates_from_config,
     load_ignored_files_from_config,
 )
+from pytest_orm_boundaries.ignores import IgnoreTracker
+from pytest_orm_boundaries.model_resolution import resolve_labels
+from pytest_orm_boundaries.sql_parsing import extract_table_names, looks_like_data_query
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable
-    from typing import Any
+    from collections.abc import Iterable
 
-    from django.db.models import Model
-    from django.db.models.sql.query import Query
+    from django.db.backends.base.base import BaseDatabaseWrapper
 
 
 @dataclass
@@ -40,7 +39,7 @@ class ViolationRecord:
 
 
 class BoundaryGuard:
-    """Intercepts Django's executed queries and records aggregate crossings."""
+    """Records aggregate crossings in the queries a test suite executes."""
 
     def __init__(
         self,
@@ -51,27 +50,47 @@ class BoundaryGuard:
     ) -> None:
         self._aggregates_config = aggregates_config
         self._ignore_tracker = ignore_tracker
-        self._root = Path(root)
-        self._original_execute_sql: Callable[..., Any] | None = None
+        self._root_path = Path(root)
         self._current_test: str | None = None
         self._violations: dict[tuple[str, int, tuple[str, ...]], ViolationRecord] = {}
+        self._attached_connections: list[BaseDatabaseWrapper] = []
 
     def install(self) -> None:
-        from django.db.models.sql.compiler import SQLCompiler
-
-        original_execute_sql = SQLCompiler.execute_sql
-        self._original_execute_sql = original_execute_sql
-
-        def patched_execute_sql(compiler, *args, **kwargs):
-            self._handle_query(query=compiler.query)
-            return original_execute_sql(compiler, *args, **kwargs)
+        """Attach to every DB connection: those open now and any opened later
+        (each new connection fires ``connection_created``).
+        """
+        from django.db import connections
+        from django.db.backends.signals import connection_created
 
-        SQLCompiler.execute_sql = patched_execute_sql
+        connection_created.connect(self._handle_connection_created, weak=False)
+        for connection in connections.all(initialized_only=True):
+            self._attach_wrapper(connection)
 
     def uninstall(self) -> None:
-        from django.db.models.sql.compiler import SQLCompiler
+        from django.db.backends.signals import connection_created
+
+        connection_created.disconnect(self._handle_connection_created)
+        for connection in self._attached_connections:
+            try:
+                connection.execute_wrappers.remove(self._execute_wrapper)
+            except ValueError:
+                pass
+        self._attached_connections.clear()
+
+    def _handle_connection_created(
+        self, *, connection: BaseDatabaseWrapper, **_
+    ) -> None:
+        self._attach_wrapper(connection)
 
-        SQLCompiler.execute_sql = self._original_execute_sql
+    def _attach_wrapper(self, connection: BaseDatabaseWrapper) -> None:
+        if self._execute_wrapper not in connection.execute_wrappers:
+            connection.execute_wrappers.append(self._execute_wrapper)
+            self._attached_connections.append(connection)
+
+    def _execute_wrapper(self, execute, sql, params, many, context):
+        if looks_like_data_query(sql):
+            self._check_violations_in_query(sql, context["connection"].vendor)
+        return execute(sql, params, many, context)
 
     def set_current_test(self, nodeid: str | None) -> None:
         """Remember which test is running so a recorded crossing can name it."""
@@ -88,20 +107,23 @@ class BoundaryGuard:
     def find_stale_patterns(self) -> list[str]:
         return self._ignore_tracker.find_stale_patterns()
 
-    def _handle_query(self, *, query: Query) -> None:
-        """Handle one executed query: gather stack context, apply the aggregate
-        rule, and record a crossing (unless it's clean or its place is ignored).
+    def _check_violations_in_query(self, sql: str, vendor: str) -> None:
+        """Handle one executed data query: gather stack context, apply the
+        aggregate rule, and record a crossing (unless it's clean or ignored).
         """
         # ``frames`` is the in-project part of this query's call stack,
         # used by the ignore/stale check and the report.
         frames: list[tuple[str, int]] | None = None
-        file_paths: list[str] | None = None
+        file_paths: set[str] | None = None
         if self._ignore_tracker.is_active:
-            frames = find_in_project_frames(root=self._root)
-            file_paths = self._extract_file_paths(frames)
+            frames = find_frames_inside_project(root=self._root_path)
+            file_paths = {path for path, _ in frames}
             self._ignore_tracker.mark_seen(file_paths=file_paths)
 
-        labels = self._read_labels(query=query)
+        table_names = extract_table_names(sql, vendor)
+        if table_names is None:  # unparseable data query -- skip it (see ROADMAP)
+            return
+        labels = resolve_labels(table_names)
         crossing = self._find_crossing(labels=labels)
         if crossing is None:
             return
@@ -113,25 +135,11 @@ class BoundaryGuard:
             return
 
         if frames is None:
-            frames = find_in_project_frames(root=self._root)
+            frames = find_frames_inside_project(root=self._root_path)
         self._record_violation(
             call_place=frames[0] if frames else None, crossing=crossing
         )
 
-    def _read_labels(self, *, query: Query) -> list[str]:
-        """Model labels of the tables the query actually reads.
-
-        A filter on a foreign-key id reads a column already on the current
-        table, so the table it points to isn't read -- and isn't counted.
-        """
-        table_to_model = _map_tables_to_models()
-        return [
-            table_to_model[table.table_name]._meta.label
-            for alias, table in query.alias_map.items()
-            if table.table_name in table_to_model
-            and query.alias_refcount.get(alias, 0) > 0
-        ]
-
     def _find_crossing(
         self, *, labels: Iterable[str]
     ) -> tuple[tuple[str, ...], tuple[str, ...]] | None:
@@ -171,10 +179,6 @@ class BoundaryGuard:
         if self._current_test is not None:
             record.tests.add(self._current_test)
 
-    @staticmethod
-    def _extract_file_paths(frames: Iterable[tuple[str, int]]) -> set[str]:
-        return {path for path, _ in frames}
-
 
 def build_guard(*, rootpath: Path, config_path: Path) -> BoundaryGuard | None:
     aggregates_by_model = load_aggregates_from_config(path=config_path)
@@ -187,11 +191,3 @@ def build_guard(*, rootpath: Path, config_path: Path) -> BoundaryGuard | None:
     return BoundaryGuard(
         aggregates_config=aggregates_by_model, ignore_tracker=tracker, root=rootpath
     )
-
-
-@functools.cache
-def _map_tables_to_models() -> dict[str, type[Model]]:
-    """Map db_table -> model class for every installed model."""
-    from django.apps import apps
-
-    return {model._meta.db_table: model for model in apps.get_models()}

pytest_orm_boundaries-0.4.0/src/pytest_orm_boundaries/model_resolution.py

@@ -0,0 +1,29 @@
+"""Resolve Django model labels for the table names a query reads."""
+
+from __future__ import annotations
+
+import functools
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from django.db.models import Model
+
+
+def resolve_labels(table_names: Iterable[str]) -> list[str]:
+    """Resolve model labels for the given table names, dropping unmapped names."""
+    table_to_model = map_tables_to_models()
+    return [
+        table_to_model[table]._meta.label
+        for table in table_names
+        if table in table_to_model
+    ]
+
+
+@functools.cache
+def map_tables_to_models() -> dict[str, type[Model]]:
+    """Map db_table -> model class for every installed model."""
+    from django.apps import apps
+
+    return {model._meta.db_table: model for model in apps.get_models()}

{pytest_orm_boundaries-0.3.1 → pytest_orm_boundaries-0.4.0}/src/pytest_orm_boundaries/plugin.py

@@ -7,13 +7,13 @@ from typing import TYPE_CHECKING
 
 import pytest
 
-from pytest_orm_boundaries import build_report
-from pytest_orm_boundaries.guard import build_guard
-from pytest_orm_boundaries.read_config import (
+from pytest_orm_boundaries import report
+from pytest_orm_boundaries.config import (
     CONFIG_FILE_NAME,
     BoundariesConfigError,
     discover_config_path,
 )
+from pytest_orm_boundaries.guard import build_guard
 
 if TYPE_CHECKING:
     from pytest_orm_boundaries.guard import BoundaryGuard
@@ -108,15 +108,15 @@ def pytest_terminal_summary(
     guard = _installed_guard(config)
     if guard is None:
         return
-    build_report.report_violations(
+    report.report_violations(
         terminalreporter=terminalreporter,
         violations=guard.violations,
         verbose=config.getoption("verbose", 0) > 0,
     )
     stale = guard.find_stale_patterns()
-    build_report.report_stale_ignores(terminalreporter=terminalreporter, stale=stale)
+    report.report_stale_ignores(terminalreporter=terminalreporter, stale=stale)
 
 
 def pytest_report_header(config: pytest.Config) -> str:
     config_path = config.stash.get(config_path_key, None)
-    return build_report.render_header(config_path=config_path)
+    return report.render_header(config_path=config_path)

pytest_orm_boundaries-0.3.1/src/pytest_orm_boundaries/build_report.py → pytest_orm_boundaries-0.4.0/src/pytest_orm_boundaries/report.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from pytest_orm_boundaries.read_config import CONFIG_FILE_NAME
+from pytest_orm_boundaries.config import CONFIG_FILE_NAME
 
 if TYPE_CHECKING:
     from pathlib import Path

pytest_orm_boundaries-0.4.0/src/pytest_orm_boundaries/sql_parsing.py

@@ -0,0 +1,58 @@
+"""Read the tables a SQL statement touches by parsing the SQL text."""
+
+from __future__ import annotations
+
+import functools
+import re
+
+import sqlglot
+from sqlglot import expressions as exp
+from sqlglot.errors import SqlglotError
+
+# Decreasing amount of work - only these statements read tables,
+# transaction control, PRAGMA and DDL are ignored before we bother parsing.
+_DATA_QUERY = re.compile(
+    r"\s*(?:WITH|SELECT|INSERT|UPDATE|DELETE|REPLACE|MERGE)\b", re.IGNORECASE
+)
+
+# Django backend vendor -> sqlglot dialect; unmapped vendors parse dialect-free.
+_DIALECT_BY_VENDOR = {
+    "sqlite": "sqlite",
+    "postgresql": "postgres",
+    "mysql": "mysql",
+    "oracle": "oracle",
+}
+
+
+def looks_like_data_query(sql: str) -> bool:
+    """Whether the statement is one that can read tables (worth parsing)."""
+    return _DATA_QUERY.match(sql) is not None
+
+
+def _blank_placeholders(sql: str) -> str:
+    """Replace ``%s`` / ``%(name)s`` placeholders with a literal so the SQL parses,
+    leaving any placeholder-looking text inside quoted strings untouched.
+    """
+    placeholder = re.compile(r"""('(?:[^']|'')*')|("(?:[^"]|"")*")|(%\(\w+\)s|%s)""")
+
+    return placeholder.sub(
+        lambda match: "NULL" if match.group(3) else match.group(0), sql
+    )
+
+
+@functools.lru_cache(maxsize=4096)
+def extract_table_names(sql: str, vendor: str) -> frozenset[str] | None:
+    """Names of the tables the statement reads, or None if it could not be parsed."""
+    dialect = _DIALECT_BY_VENDOR.get(vendor)
+    blanked_sql = _blank_placeholders(sql)
+    try:
+        tree = sqlglot.parse_one(blanked_sql, dialect=dialect)
+    except (SqlglotError, RecursionError):
+        return None
+    if tree is None:
+        return frozenset()
+    # common table expression - can be named as an existed table, but it is not a table
+    # e.g. `report` in ` WITH report AS (SELECT id FROM orders WHERE created > '2026-01-01')
+    cte_names = {cte.alias_or_name for cte in tree.find_all(exp.CTE)}
+    tables = {table.name for table in tree.find_all(exp.Table)}
+    return frozenset(tables - cte_names)