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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-orm-boundaries
-Version: 0.4.0
+Version: 0.6.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
@@ -18,20 +18,22 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Testing
 Requires-Dist: pytest>=8
 Requires-Dist: sqlglot>=30,<31
+Requires-Dist: django>=4.2 ; extra == 'django'
 Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/evchibisova/pytest-orm-boundaries
 Project-URL: Repository, https://github.com/evchibisova/pytest-orm-boundaries
 Project-URL: Issues, https://github.com/evchibisova/pytest-orm-boundaries/issues
 Project-URL: Changelog, https://github.com/evchibisova/pytest-orm-boundaries/blob/main/CHANGELOG.md
+Provides-Extra: django
 Description-Content-Type: text/markdown
 
 # pytest-orm-boundaries
 
-> 💡 **Even if you control your imports — boundaries still can leak through the ORM**
+💡 **Even if you control your imports, boundaries can still leak through the ORM.**
 
-A `pytest-orm-boundaries` is a pytest plugin that reports ORM queries crossing your DDD aggregate boundaries.
+`pytest-orm-boundaries` is a pytest plugin that reports ORM queries crossing your DDD aggregate boundaries.
 
-Currently works with Django ORM.
+Currently works with Django ORM, SQLAlchemy is in roadmap.
 
 In domain-driven design, an aggregate is a consistency boundary: code in one
 aggregate should not reach into the internals of another. Django's `__` relation
@@ -42,17 +44,19 @@ lookups make it easy to cross those boundaries silently:
 Purchase.objects.get(client__name="John")
 ```
 
-`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.
+`pytest-orm-boundaries` watches the ORM activity exercised by your test suite
+and reports access that crosses a configured boundary - through `__` lookups,
+`select_related`, `prefetch_related`, subqueries, or hand-written `.raw()` SQL.
 
 ## Install
 
+Install the plugin with Django support:
+
 ```bash
-pip install pytest-orm-boundaries
+pip install "pytest-orm-boundaries[django]"
 ```
 
-pytest picks the plugin up automatically.
+pytest discovers the plugin automatically.
 
 ## Configure
 
@@ -71,9 +75,9 @@ 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:
+The plugin flags executed ORM access that spans more than one configured group.
+In the DDD example below, each crossing couples the `purchase` and `client`
+aggregates:
 
 - `__` relation lookups:
 
@@ -81,7 +85,7 @@ query was written. Each example below joins the `purchase` and `client` aggregat
   Purchase.objects.get(client__name="John")
   ```
 
-- `select_related`
+- `select_related`:
 
   ```python
   Purchase.objects.select_related("client")
@@ -105,7 +109,13 @@ query was written. Each example below joins the `purchase` and `client` aggregat
 
 - Bare `cursor.execute()` - the same join reached through a raw cursor.
 
-Queries that don't actually join across the boundary are **not** flagged — for
+- `prefetch_related`:
+
+  ```python
+  Purchase.objects.prefetch_related("client")
+  ```
+
+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
@@ -118,7 +128,7 @@ Purchase.objects.filter(client__pk=42)    # Django trims the join
 At the end of the run, the plugin prints one grouped entry per offending place:
 
 ```
-===================== orm-boundaries: boundary violations ======================
+====================== orm-boundaries: boundary crossings ======================
 1 place(s) in your code crossed aggregate boundaries, affecting 1 test(s):
 
 bookshop/reports.py:13
@@ -127,18 +137,29 @@ bookshop/reports.py:13
     1 test(s) affected:
       test_purchases.py::test_list_purchases_with_client
 
-orm-boundaries: FAILED - 1 boundary violation(s), run exits non-zero.
+orm-boundaries: FAILED - 1 boundary crossing(s), run exits non-zero.
 ```
 
 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
+## Allow and ignore
+
+CQRS read models may cross boundaries intentionally, also existing application code may contain crossings you want to fix over time. [allow] and [ignore] let you tell the plugin which is which:
 
-Add exceptions so that known offenders keep passing while you fix them one file at a time:
+- `[allow]` - the crossing is **intentional**. Use it for code that is meant to
+  span aggregates, such as CQRS read models or cross-aggregate reports. An
+  allowed crossing is suppressed and never reported.
+- `[ignore]` - the crossing is **known debt** you plan to fix. It is suppressed
+  for now, and the plugin reminds you when an entry is no longer needed.
 
 ```toml
+[allow]
+files = [
+    "app/reports/sales_summary.py",
+]
+
 [ignore]
 files = [
     "app/billing.py",
@@ -146,25 +167,35 @@ files = [
 ]
 ```
 
-Each entry is a glob ([`fnmatch`](https://docs.python.org/3/library/fnmatch.html),
+Each entry is a glob ([`fnmatch`](https://docs.python.org/3/library/fnmatch.html)),
 resolved relative to pytest's root directory and matched against either:
 
 - the file that issues the query, or
 - the test file.
 
-If an ignored file runs queries through the whole suite without ever crossing a
-boundary, the plugin says so at the end:
+An `[ignore]` whose file runs through the whole suite without ever crossing a
+boundary is stale — it is clean now, so the plugin lists it for removal:
 
 ```
 ======================= orm-boundaries: stale ignores ========================
-These [ignore] entries no longer suppress any boundary violation - their files are clean now.
+These [ignore] entries no longer suppress any boundary crossing - their files are clean now.
 Remove them from boundaries.toml:
   - app/billing.py
 ```
 
-## Known gaps
+`[allow]` entries are never reported this way. If a file sits in both sections,
+the allow wins and its `[ignore]` entry shows up as stale to remove.
+
+## A note on Django internals
+
+Catching `prefetch_related` relies on Django internals that come with no stability
+promise, so new Django releases may require compatibility updates.
+
+## Known gaps (on the project roadmap)
 
-- `prefetch_related` loads doesn't detected in current version.
+- lazy attribute access (e.g. `purchase.client`);
+- related-manager reads/writes (`client.purchases.all()`, `client.purchases.create(...)`);
+- a direct query on another aggregate's model, e.g. `Client.objects.get(...)` written inside purchase code.
 
 ## Status
 

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

@@ -1,10 +1,10 @@
 # pytest-orm-boundaries
 
-> 💡 **Even if you control your imports — boundaries still can leak through the ORM**
+💡 **Even if you control your imports, boundaries can still leak through the ORM.**
 
-A `pytest-orm-boundaries` is a pytest plugin that reports ORM queries crossing your DDD aggregate boundaries.
+`pytest-orm-boundaries` is a pytest plugin that reports ORM queries crossing your DDD aggregate boundaries.
 
-Currently works with Django ORM.
+Currently works with Django ORM, SQLAlchemy is in roadmap.
 
 In domain-driven design, an aggregate is a consistency boundary: code in one
 aggregate should not reach into the internals of another. Django's `__` relation
@@ -15,17 +15,19 @@ lookups make it easy to cross those boundaries silently:
 Purchase.objects.get(client__name="John")
 ```
 
-`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.
+`pytest-orm-boundaries` watches the ORM activity exercised by your test suite
+and reports access that crosses a configured boundary - through `__` lookups,
+`select_related`, `prefetch_related`, subqueries, or hand-written `.raw()` SQL.
 
 ## Install
 
+Install the plugin with Django support:
+
 ```bash
-pip install pytest-orm-boundaries
+pip install "pytest-orm-boundaries[django]"
 ```
 
-pytest picks the plugin up automatically.
+pytest discovers the plugin automatically.
 
 ## Configure
 
@@ -44,9 +46,9 @@ 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:
+The plugin flags executed ORM access that spans more than one configured group.
+In the DDD example below, each crossing couples the `purchase` and `client`
+aggregates:
 
 - `__` relation lookups:
 
@@ -54,7 +56,7 @@ query was written. Each example below joins the `purchase` and `client` aggregat
   Purchase.objects.get(client__name="John")
   ```
 
-- `select_related`
+- `select_related`:
 
   ```python
   Purchase.objects.select_related("client")
@@ -78,7 +80,13 @@ query was written. Each example below joins the `purchase` and `client` aggregat
 
 - Bare `cursor.execute()` - the same join reached through a raw cursor.
 
-Queries that don't actually join across the boundary are **not** flagged — for
+- `prefetch_related`:
+
+  ```python
+  Purchase.objects.prefetch_related("client")
+  ```
+
+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
@@ -91,7 +99,7 @@ Purchase.objects.filter(client__pk=42)    # Django trims the join
 At the end of the run, the plugin prints one grouped entry per offending place:
 
 ```
-===================== orm-boundaries: boundary violations ======================
+====================== orm-boundaries: boundary crossings ======================
 1 place(s) in your code crossed aggregate boundaries, affecting 1 test(s):
 
 bookshop/reports.py:13
@@ -100,18 +108,29 @@ bookshop/reports.py:13
     1 test(s) affected:
       test_purchases.py::test_list_purchases_with_client
 
-orm-boundaries: FAILED - 1 boundary violation(s), run exits non-zero.
+orm-boundaries: FAILED - 1 boundary crossing(s), run exits non-zero.
 ```
 
 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
+## Allow and ignore
+
+CQRS read models may cross boundaries intentionally, also existing application code may contain crossings you want to fix over time. [allow] and [ignore] let you tell the plugin which is which:
 
-Add exceptions so that known offenders keep passing while you fix them one file at a time:
+- `[allow]` - the crossing is **intentional**. Use it for code that is meant to
+  span aggregates, such as CQRS read models or cross-aggregate reports. An
+  allowed crossing is suppressed and never reported.
+- `[ignore]` - the crossing is **known debt** you plan to fix. It is suppressed
+  for now, and the plugin reminds you when an entry is no longer needed.
 
 ```toml
+[allow]
+files = [
+    "app/reports/sales_summary.py",
+]
+
 [ignore]
 files = [
     "app/billing.py",
@@ -119,25 +138,35 @@ files = [
 ]
 ```
 
-Each entry is a glob ([`fnmatch`](https://docs.python.org/3/library/fnmatch.html),
+Each entry is a glob ([`fnmatch`](https://docs.python.org/3/library/fnmatch.html)),
 resolved relative to pytest's root directory and matched against either:
 
 - the file that issues the query, or
 - the test file.
 
-If an ignored file runs queries through the whole suite without ever crossing a
-boundary, the plugin says so at the end:
+An `[ignore]` whose file runs through the whole suite without ever crossing a
+boundary is stale — it is clean now, so the plugin lists it for removal:
 
 ```
 ======================= orm-boundaries: stale ignores ========================
-These [ignore] entries no longer suppress any boundary violation - their files are clean now.
+These [ignore] entries no longer suppress any boundary crossing - their files are clean now.
 Remove them from boundaries.toml:
   - app/billing.py
 ```
 
-## Known gaps
+`[allow]` entries are never reported this way. If a file sits in both sections,
+the allow wins and its `[ignore]` entry shows up as stale to remove.
+
+## A note on Django internals
+
+Catching `prefetch_related` relies on Django internals that come with no stability
+promise, so new Django releases may require compatibility updates.
+
+## Known gaps (on the project roadmap)
 
-- `prefetch_related` loads doesn't detected in current version.
+- lazy attribute access (e.g. `purchase.client`);
+- related-manager reads/writes (`client.purchases.all()`, `client.purchases.create(...)`);
+- a direct query on another aggregate's model, e.g. `Client.objects.get(...)` written inside purchase code.
 
 ## Status
 

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pytest-orm-boundaries"
-version = "0.4.0"
+version = "0.6.0"
 description = "Pytest plugin that fails tests when ORM queries cross DDD aggregate boundaries (Django supported today)."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -35,6 +35,9 @@ classifiers = [
 ]
 dependencies = ["pytest>=8", "sqlglot>=30,<31"]
 
+[project.optional-dependencies]
+django = ["django>=4.2"]
+
 [project.urls]
 Homepage = "https://github.com/evchibisova/pytest-orm-boundaries"
 Repository = "https://github.com/evchibisova/pytest-orm-boundaries"

pytest_orm_boundaries-0.6.0/src/pytest_orm_boundaries/allows.py

@@ -0,0 +1,26 @@
+"""Per-file allows: files whose boundary crossings are intentional.
+
+Unlike ``[ignore]`` (known debt, tracked for staleness), an ``[allow]`` marks
+architecture that is meant to span aggregates - CQRS read models, cross-aggregate
+reports - so a matching crossing is suppressed and never surfaces as stale.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from fnmatch import fnmatch
+
+
+class AllowList:
+    """Decides whether a crossing's call place is intentional and so allowed.
+    """
+
+    def __init__(self, *, patterns: Iterable[str]) -> None:
+        self._patterns = list(dict.fromkeys(patterns))  # ordered, de-duped
+
+    @property
+    def is_active(self) -> bool:
+        return bool(self._patterns)
+
+    def has_allow_for(self, *, file_paths: Iterable[str]) -> bool:
+        return any(fnmatch(f, p) for f in file_paths for p in self._patterns)

{pytest_orm_boundaries-0.4.0 → pytest_orm_boundaries-0.6.0}/src/pytest_orm_boundaries/config.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import tomllib
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
@@ -13,6 +14,15 @@ class BoundariesConfigError(Exception):
     """Raised when the config file is malformed or semantically invalid."""
 
 
+@dataclass(frozen=True)
+class BoundariesConfig:
+    """Parsed and validated content of a ``boundaries.toml``."""
+
+    aggregates_by_model: dict[str, str]  # {"app.model" lower-cased: aggregate_name}
+    ignored_files: list[str]  # globs for known debt, tracked for staleness
+    allowed_files: list[str]  # globs for intentional crossings, never stale
+
+
 def discover_config_path(*, explicit: str | None, rootpath: Path) -> Path | None:
     """Resolve the config path.
 
@@ -29,6 +39,15 @@ def discover_config_path(*, explicit: str | None, rootpath: Path) -> Path | None
     return default if default.is_file() else None
 
 
+def load_config(*, path: Path) -> BoundariesConfig:
+    data = _read_config(path=path)
+    return BoundariesConfig(
+        aggregates_by_model=_parse_aggregates(data=data, path=path),
+        ignored_files=_parse_file_globs(data=data, path=path, section_name="ignore"),
+        allowed_files=_parse_file_globs(data=data, path=path, section_name="allow"),
+    )
+
+
 def _read_config(*, path: Path) -> dict[str, Any]:
     try:
         with path.open("rb") as fh:
@@ -37,16 +56,14 @@ def _read_config(*, path: Path) -> dict[str, Any]:
         raise BoundariesConfigError(f"{path}: invalid TOML ({exc})") from exc
 
 
-def load_aggregates_from_config(*, path: Path) -> dict[str, str]:
-    """Parse the config into a {model_label: aggregate_name} map.
+def _parse_aggregates(*, data: dict[str, Any], path: Path) -> dict[str, str]:
+    """Build a {model_label: aggregate_name} map from the ``[aggregates]`` table.
 
     Model labels are lower-cased ("app_label.modelname") for case-insensitive
     matching.
     """
-    config = _read_config(path=path)
-
     aggregates_by_model: dict[str, str] = {}
-    for aggregate, members in config.get("aggregates", {}).items():
+    for aggregate, members in data.get("aggregates", {}).items():
         if isinstance(members, dict):
             members = members.get("models", [])
         if not isinstance(members, list):
@@ -67,25 +84,25 @@ def load_aggregates_from_config(*, path: Path) -> dict[str, str]:
     return aggregates_by_model
 
 
-def load_ignored_files_from_config(*, path: Path) -> list[str]:
-    """Parse ``[ignore] files`` into a list of glob patterns."""
-    data = _read_config(path=path)
-
-    ignore = data.get("ignore", {})
-    if not isinstance(ignore, dict):
-        raise BoundariesConfigError(f"{path}: [ignore] must be a table")
+def _parse_file_globs(
+    *, data: dict[str, Any], path: Path, section_name: str
+) -> list[str]:
+    """Read ``[allow]`` and ``[ignore] files`` into a list of glob patterns."""
+    section_data = data.get(section_name, {})
+    if not isinstance(section_data, dict):
+        raise BoundariesConfigError(f"{path}: [{section_name}] must be a table")
 
-    files = ignore.get("files", [])
+    files = section_data.get("files", [])
     if not isinstance(files, list):
         raise BoundariesConfigError(
-            f"{path}: [ignore] files must be a list of glob patterns"
+            f"{path}: [{section_name}] files must be a list of glob patterns"
         )
 
     patterns: list[str] = []
     for entry in files:
         if not isinstance(entry, str):
             raise BoundariesConfigError(
-                f"{path}: [ignore] files has a non-string entry: {entry!r}"
+                f"{path}: [{section_name}] files has a non-string entry: {entry!r}"
             )
         patterns.append(entry)
     return patterns

pytest_orm_boundaries-0.6.0/src/pytest_orm_boundaries/crossings.py

@@ -0,0 +1,139 @@
+"""Track aggregate crossings: apply the rule to models and accumulate the crossings found."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pytest_orm_boundaries.callstack import find_frames_inside_project
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from pytest_orm_boundaries.allows import AllowList
+    from pytest_orm_boundaries.ignores import IgnoreTracker
+
+
+@dataclass
+class CrossingRecord:
+    """One offending call place and the tests that reached it."""
+
+    file: str
+    line_number: int
+    crossed_aggregates: tuple[str, ...]  # ("order", "payment")
+    involved_models: tuple[str, ...]  # ("order.Invoice", "payrolls.IncomePayment")
+    tests: set[str] = field(default_factory=set)
+
+
+class CrossingTracker:
+    """Checks label sets against the aggregate rule and records the crossings,
+    skipping allowed and ignored files and naming each crossing's call place and
+    test."""
+
+    def __init__(
+        self,
+        *,
+        aggregates_config: dict[str, str],
+        allow_list: AllowList,
+        ignore_tracker: IgnoreTracker,
+        root: Path,
+    ) -> None:
+        self._aggregates_config = aggregates_config
+        self._allow_list = allow_list
+        self._ignore_tracker = ignore_tracker
+        self._root_path = Path(root)
+        self._current_test: str | None = None
+        self._crossings: dict[tuple[str, int, tuple[str, ...]], CrossingRecord] = {}
+
+    def set_current_test(self, nodeid: str | None) -> None:
+        """Remember which test is running so a recorded crossing can name it."""
+        self._current_test = nodeid
+
+    def check(self, *, label_sets: Iterable[Iterable[str]]) -> None:
+        """Record a crossing for each label set that spans aggregates, unless an
+        allow or an ignore covers the call place.
+
+        Allow wins over ignore: an allowed crossing is suppressed without marking
+        the ignore used, so an ignore that only overlaps an allow surfaces as
+        stale and can be removed as redundant.
+        """
+        # ``frames`` is the in-project part of the call stack
+        frames: list[tuple[str, int]] | None = None
+        file_paths: set[str] | None = None
+        if self._allow_list.is_active or self._ignore_tracker.is_active:
+            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)
+
+        for labels in label_sets:
+            crossing = self.find_crossing(labels=labels)
+            if crossing is None:
+                continue
+            if file_paths is not None:
+                if self._allow_list.has_allow_for(file_paths=file_paths):
+                    continue
+                if self._ignore_tracker.has_ignore_for(file_paths=file_paths):
+                    self._ignore_tracker.mark_used(file_paths=file_paths)
+                    continue
+            if frames is None:
+                frames = find_frames_inside_project(root=self._root_path)
+            call_place = frames[0] if frames else None
+            self.add_record(
+                call_place=call_place, crossing=crossing, test=self._current_test
+            )
+
+    def find_crossing(
+        self, *, labels: Iterable[str]
+    ) -> tuple[tuple[str, ...], tuple[str, ...]] | None:
+        """Return ``(crossed aggregate names, involved model labels)`` if the
+        labels span more than one aggregate, else None.
+
+        e.g. ``(("order", "payment"), ("order.Invoice", "payrolls.IncomePayment"))``.
+
+        ``labels`` are model labels.
+        """
+        aggregate_by_label = {
+            label: aggregate
+            for label in labels
+            if (aggregate := self._aggregates_config.get(label.lower())) is not None
+        }
+        aggregates = set(aggregate_by_label.values())
+        if len(aggregates) <= 1:
+            return None
+        return tuple(sorted(aggregates)), tuple(sorted(aggregate_by_label.keys()))
+
+    def add_record(
+        self,
+        *,
+        call_place: tuple[str, int] | None,
+        crossing: tuple[tuple[str, ...], tuple[str, ...]],
+        test: str | None,
+    ) -> None:
+        """Add one crossing, merging into the record for its call place."""
+        crossed_aggregates, involved_models = crossing
+        file, line = call_place if call_place is not None else ("<unknown>", 0)
+        key = (file, line, crossed_aggregates)
+        record = self._crossings.get(key)
+        if record is None:
+            record = CrossingRecord(
+                file=file,
+                line_number=line,
+                crossed_aggregates=crossed_aggregates,
+                involved_models=involved_models,
+            )
+            self._crossings[key] = record
+        if test is not None:
+            record.tests.add(test)
+
+    @property
+    def crossings(self) -> list[CrossingRecord]:
+        """Recorded crossings, most-affecting first."""
+        return sorted(
+            self._crossings.values(),
+            key=lambda v: (-len(v.tests), v.file, v.line_number),
+        )
+
+    def find_stale_patterns(self) -> list[str]:
+        """Ignore globs whose file ran but never crossed -- safe to delete."""
+        return self._ignore_tracker.find_stale_patterns()

pytest_orm_boundaries-0.6.0/src/pytest_orm_boundaries/guard.py

@@ -0,0 +1,179 @@
+"""Django boundary guard: watches the queries a test suite executes and checks crossing.
+
+Two sources of crossings: the SQL of each executed query, and the relation path
+of each ``prefetch_related``.
+"""
+
+from __future__ import annotations
+
+import weakref
+from dataclasses import dataclass
+from functools import wraps
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pytest_orm_boundaries.crossings import CrossingTracker
+from pytest_orm_boundaries.model_resolution import resolve_labels
+from pytest_orm_boundaries.prefetch_resolution import resolve_prefetch_step_models
+from pytest_orm_boundaries.sql_parsing import extract_table_names, looks_like_data_query
+
+if TYPE_CHECKING:
+    from django.db.backends.base.base import BaseDatabaseWrapper
+
+    from pytest_orm_boundaries.allows import AllowList
+    from pytest_orm_boundaries.crossings import CrossingRecord
+    from pytest_orm_boundaries.ignores import IgnoreTracker
+
+
+@dataclass
+class _HookState:
+    """On/off switch for one installed prefetch wrapper.
+
+    We monkey-patch Django's ``prefetch_related_objects``. On uninstall we
+    restore the original when our wrapper is still on top - but if another tool
+    wrapped it above ours, that tool holds a reference to our wrapper and we
+    can't take it out of the chain. So instead of removing it we set ``active``
+    to False: the wrapper keeps being called but does nothing.
+    """
+
+    active: bool
+
+
+class BoundaryGuard:
+    """Records aggregate crossings in the queries a test suite executes."""
+
+    def __init__(
+        self,
+        *,
+        aggregates_config: dict[str, str],
+        allow_list: AllowList,
+        ignore_tracker: IgnoreTracker,
+        root: Path,
+    ) -> None:
+        self._tracker = CrossingTracker(
+            aggregates_config=aggregates_config,
+            allow_list=allow_list,
+            ignore_tracker=ignore_tracker,
+            root=root,
+        )
+        self._attached_connections: list[BaseDatabaseWrapper] = []
+        self._original_prefetch = None
+        self._prefetch_wrapper = None
+        self._prefetch_hook_state: _HookState | None = None
+
+    def install(self) -> None:
+        """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
+
+        connection_created.connect(self._handle_connection_created, weak=False)
+        for connection in connections.all(initialized_only=True):
+            self._attach_wrapper(connection)
+        self._install_prefetch_hook()
+
+    def uninstall(self) -> None:
+        from django.db.backends.signals import connection_created
+
+        self._remove_prefetch_hook()
+        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)
+
+    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 _install_prefetch_hook(self) -> None:
+        """Wrap django ``prefetch_related_objects`` so each prefetch reports the
+        models it walks between.
+        """
+        import django.db.models.query as query_module
+
+        if self._prefetch_wrapper is not None:
+            # Already installed. A second install would capture our own wrapper
+            # as ``original`` and orphan the first _HookState
+            return
+
+        original = query_module.prefetch_related_objects
+        # hook can be switched off even when it can't be removed from the chain.
+        state = _HookState(active=True)
+        # strong ref is config.stash[guard_key]
+        guard_ref = weakref.ref(self)
+
+        @wraps(original)
+        def prefetch_with_check(model_instances, *lookups):
+            result = original(model_instances, *lookups)
+            guard = guard_ref()
+            if state.active and guard is not None:
+                guard._handle_prefetch(
+                    model_instances=model_instances, lookups=lookups
+                )
+            return result
+
+        self._prefetch_hook_state = state
+        self._original_prefetch = original
+        self._prefetch_wrapper = prefetch_with_check
+        query_module.prefetch_related_objects = prefetch_with_check
+
+    def _remove_prefetch_hook(self) -> None:
+        import django.db.models.query as query_module
+
+        if self._prefetch_wrapper is None:
+            return
+        # Disable our hook unconditionally. Restore the previous callable only
+        # when ours is still topmost; otherwise another wrapper may still
+        # reference it, and ours stays in the chain as an inert no-op.
+        self._prefetch_hook_state.active = False
+        if query_module.prefetch_related_objects is self._prefetch_wrapper:
+            query_module.prefetch_related_objects = self._original_prefetch
+        self._prefetch_hook_state = None
+        self._prefetch_wrapper = None
+        self._original_prefetch = None
+
+    def _execute_wrapper(self, execute, sql, params, many, context):
+        if looks_like_data_query(sql):
+            self._handle_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."""
+        self._tracker.set_current_test(nodeid)
+
+    @property
+    def crossings(self) -> list[CrossingRecord]:
+        return self._tracker.crossings
+
+    def find_stale_patterns(self) -> list[str]:
+        return self._tracker.find_stale_patterns()
+
+    def _handle_query(self, sql: str, vendor: str) -> None:
+        """Map one executed data query to its table labels and check them."""
+        table_names = extract_table_names(sql, vendor)
+        if table_names is None:
+            return
+        labels = resolve_labels(table_names)
+        self._tracker.check(label_sets=[labels])
+
+    def _handle_prefetch(self, *, model_instances, lookups) -> None:
+        """Map one prefetch to the model pair per relation step and check them."""
+        if not model_instances:
+            return
+        source_model = type(model_instances[0])
+        step_model_pairs = resolve_prefetch_step_models(
+            source_model=source_model, lookups=lookups
+        )
+        if not step_model_pairs:
+            return
+        self._tracker.check(label_sets=step_model_pairs)

{pytest_orm_boundaries-0.4.0 → pytest_orm_boundaries-0.6.0}/src/pytest_orm_boundaries/ignores.py

@@ -7,7 +7,7 @@ from fnmatch import fnmatch
 
 
 class IgnoreTracker:
-    """Decides whether a violation is ignored, and reports ignore globs that went
+    """Decides whether a crossing is ignored, and reports ignore globs that went
     stale - their file ran but never crossed a boundary."""
 
     def __init__(self, *, patterns: Iterable[str]) -> None:

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

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
+import importlib.util
 from pathlib import Path
-from typing import TYPE_CHECKING
 
 import pytest
 
@@ -12,18 +12,18 @@ from pytest_orm_boundaries.config import (
     CONFIG_FILE_NAME,
     BoundariesConfigError,
     discover_config_path,
+    load_config,
 )
-from pytest_orm_boundaries.guard import build_guard
-
-if TYPE_CHECKING:
-    from pytest_orm_boundaries.guard import BoundaryGuard
+from pytest_orm_boundaries.allows import AllowList
+from pytest_orm_boundaries.guard import BoundaryGuard
+from pytest_orm_boundaries.ignores import IgnoreTracker
 
 config_path_key = pytest.StashKey[Path | None]()
 guard_key = pytest.StashKey["BoundaryGuard"]()
 
 
 class BoundariesConfigWarning(UserWarning):
-    """Plugin is installed but no config file was found."""
+    """Plugin is installed but won't run: no config file, or Django is absent."""
 
 
 def _installed_guard(config: pytest.Config) -> BoundaryGuard | None:
@@ -51,6 +51,22 @@ def pytest_addoption(parser: pytest.Parser) -> None:
     )
 
 
+def _build_guard(*, rootpath: Path, config_path: Path) -> BoundaryGuard | None:
+    """Build the guard from config, or None if no aggregates are declared."""
+    config = load_config(path=config_path)
+    if not config.aggregates_by_model:
+        return None
+
+    allow_list = AllowList(patterns=config.allowed_files)
+    ignore_tracker = IgnoreTracker(patterns=config.ignored_files)
+    return BoundaryGuard(
+        aggregates_config=config.aggregates_by_model,
+        allow_list=allow_list,
+        ignore_tracker=ignore_tracker,
+        root=rootpath,
+    )
+
+
 def pytest_configure(config: pytest.Config) -> None:
     """Resolve config and install the guard, stashing both for later hooks:
     the config path for the report header, the guard for teardown and reporting.
@@ -66,7 +82,15 @@ def pytest_configure(config: pytest.Config) -> None:
             config.issue_config_time_warning(warning, stacklevel=2)
             return
 
-        guard = build_guard(rootpath=config.rootpath, config_path=config_path)
+        if importlib.util.find_spec("django") is None:
+            warning = BoundariesConfigWarning(
+                f"{CONFIG_FILE_NAME} found but Django is not installed, no checks "
+                "will run (install pytest-orm-boundaries[django])"
+            )
+            config.issue_config_time_warning(warning, stacklevel=2)
+            return
+
+        guard = _build_guard(rootpath=config.rootpath, config_path=config_path)
         if guard is not None:
             guard.install()
             config.stash[guard_key] = guard
@@ -82,7 +106,7 @@ def pytest_unconfigure(config: pytest.Config) -> None:
 
 @pytest.hookimpl(wrapper=True)
 def pytest_runtest_protocol(item: pytest.Item, nextitem: pytest.Item | None):
-    """Tell the guard which test is running so a violation can name it."""
+    """Tell the guard which test is running so a crossing can name it."""
     guard = _installed_guard(item.config)
     if guard is not None:
         guard.set_current_test(item.nodeid)
@@ -96,7 +120,7 @@ def pytest_runtest_protocol(item: pytest.Item, nextitem: pytest.Item | None):
 def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:
     """A clean-but-violating run must still fail the run (via the exit code)."""
     guard = _installed_guard(session.config)
-    if guard is not None and guard.violations and exitstatus == pytest.ExitCode.OK:
+    if guard is not None and guard.crossings and exitstatus == pytest.ExitCode.OK:
         session.exitstatus = pytest.ExitCode.TESTS_FAILED
 
 
@@ -108,9 +132,9 @@ def pytest_terminal_summary(
     guard = _installed_guard(config)
     if guard is None:
         return
-    report.report_violations(
+    report.report_crossings(
         terminalreporter=terminalreporter,
-        violations=guard.violations,
+        crossings=guard.crossings,
         verbose=config.getoption("verbose", 0) > 0,
     )
     stale = guard.find_stale_patterns()

pytest_orm_boundaries-0.6.0/src/pytest_orm_boundaries/prefetch_resolution.py

@@ -0,0 +1,72 @@
+"""Turn a ``prefetch_related`` lookup into the model pairs it steps between.
+
+A prefetch loads the other aggregate with a separate single-table query, so the
+SQL alone never looks like a boundary crossing. Django's prefetch,
+though, is handed the exact relation path it walks; so the guard can apply the aggregate rule to
+each step without inspecting any SQL.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from django.db.models import Model
+
+
+def resolve_prefetch_step_models(
+    *, source_model: type[Model],
+    lookups: Iterable[object],
+) -> list[tuple[str, str]]:
+    """Return one ``(owner_model_label, target_model_label)`` pair per relation step.
+
+    A nested lookup such as ``lines__product`` yields a pair for each step.
+    """
+    from django.db.models.constants import LOOKUP_SEP
+
+    step_model_pairs: list[tuple[str, str]] = []
+    for lookup in lookups:
+        path = _extract_lookup_path(lookup=lookup)
+        if path is None:
+            continue
+        owner = source_model
+        for lookup_step in path.split(LOOKUP_SEP):
+            target = _resolve_target_lookup_step_model(model=owner, lookup_step=lookup_step)
+            if target is None:
+                break
+            step_models = (owner._meta.label, target._meta.label)
+            step_model_pairs.append(step_models)
+            owner = target
+    return step_model_pairs
+
+
+def _extract_lookup_path(*, lookup: object) -> str | None:
+    if isinstance(lookup, str):
+        return lookup
+    return getattr(lookup, "prefetch_through", None)
+
+
+def _resolve_target_lookup_step_model(
+    *,
+    model: type[Model],
+    lookup_step: str,
+) -> type[Model] | None:
+    from django.core.exceptions import FieldDoesNotExist
+
+    try:
+        field = model._meta.get_field(lookup_step)
+    except FieldDoesNotExist:
+        field = None
+    if field is not None and field.is_relation:
+        return field.related_model
+    # A reverse relation without ``related_name`` is reached by its accessor
+    # (``order_set``), a name get_field doesn't know; match it by accessor.
+    for candidate in model._meta.get_fields():
+        if not candidate.is_relation:
+            continue
+        read_accessor_name = getattr(candidate, "get_accessor_name", None)
+        if read_accessor_name is not None and read_accessor_name() == lookup_step:
+            return candidate.related_model
+    return None

{pytest_orm_boundaries-0.4.0 → pytest_orm_boundaries-0.6.0}/src/pytest_orm_boundaries/report.py

@@ -11,61 +11,61 @@ if TYPE_CHECKING:
 
     import pytest
 
-    from pytest_orm_boundaries.guard import ViolationRecord
+    from pytest_orm_boundaries.crossings import CrossingRecord
 
 MAX_TESTS_SHOWN = 5
 
 
-def report_violations(
+def report_crossings(
     *,
     terminalreporter: pytest.TerminalReporter,
-    violations: list[ViolationRecord],
+    crossings: list[CrossingRecord],
     verbose: bool = False,
 ) -> None:
     """Print one grouped entry per offending call place: which aggregates the
-    query crossed, the models it joined, and which tests reached it.
+    query crossed, the models involved, and which tests reached it.
     """
-    if not violations:
+    if not crossings:
         return
 
-    affected = len({test for violation in violations for test in violation.tests})
+    affected = len({test for crossing in crossings for test in crossing.tests})
     terminalreporter.section(
-        "orm-boundaries: boundary violations", red=True, bold=True
+        "orm-boundaries: boundary crossings", red=True, bold=True
     )
     terminalreporter.write_line(
-        f"{len(violations)} place(s) in your code crossed aggregate boundaries, "
+        f"{len(crossings)} place(s) in your code crossed aggregate boundaries, "
         f"affecting {affected} test(s):",
         red=True,
     )
-    for violation in violations:
-        _write_violation(
-            terminalreporter=terminalreporter, violation=violation, verbose=verbose
+    for crossing in crossings:
+        _write_crossing(
+            terminalreporter=terminalreporter, crossing=crossing, verbose=verbose
         )
     terminalreporter.write_line("")
     terminalreporter.write_line(
-        f"orm-boundaries: FAILED - {len(violations)} boundary violation(s), "
+        f"orm-boundaries: FAILED - {len(crossings)} boundary crossing(s), "
         "run exits non-zero.",
         red=True,
         bold=True,
     )
 
 
-def _write_violation(
+def _write_crossing(
     *,
     terminalreporter: pytest.TerminalReporter,
-    violation: ViolationRecord,
+    crossing: CrossingRecord,
     verbose: bool,
 ) -> None:
     terminalreporter.write_line("")
-    terminalreporter.write_line(f"{violation.file}:{violation.line_number}", bold=True)
-    aggregates = " ↔ ".join(violation.crossed_aggregates)
+    terminalreporter.write_line(f"{crossing.file}:{crossing.line_number}", bold=True)
+    aggregates = " ↔ ".join(crossing.crossed_aggregates)
     terminalreporter.write_line(
         f"    crossed aggregates: {aggregates}", yellow=True, bold=True
     )
-    models = ", ".join(violation.joined_models)
+    models = ", ".join(crossing.involved_models)
     terminalreporter.write_line(f"    models: {models}")
 
-    tests = sorted(violation.tests)
+    tests = sorted(crossing.tests)
     if not tests:
         terminalreporter.write_line("    tests affected: (none captured)", light=True)
         return
@@ -88,7 +88,7 @@ def report_stale_ignores(
         return
     terminalreporter.section("orm-boundaries: stale ignores", yellow=True, bold=True)
     terminalreporter.write_line(
-        "These [ignore] entries no longer suppress any boundary violation - "
+        "These [ignore] entries no longer suppress any boundary crossing - "
         f"their files are clean now. Remove them from {CONFIG_FILE_NAME}:",
         yellow=True,
     )

pytest_orm_boundaries-0.4.0/src/pytest_orm_boundaries/guard.py

@@ -1,193 +0,0 @@
-"""Django boundary guard: applies the aggregate-crossing rule to the queries a
-test suite executes and records the crossings.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-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 Iterable
-
-    from django.db.backends.base.base import BaseDatabaseWrapper
-
-
-@dataclass
-class ViolationRecord:
-    """One offending call place and the tests that reached it.
-
-    Grouped by call place so a crossing shared by many tests is one entry,
-    not one line per test.
-    """
-
-    file: str
-    line_number: int
-    crossed_aggregates: tuple[str, ...]  # ("order", "payment")
-    joined_models: tuple[str, ...]  # ("order.Invoice", "payrolls.IncomePayment")
-    tests: set[str] = field(default_factory=set)
-
-
-class BoundaryGuard:
-    """Records aggregate crossings in the queries a test suite executes."""
-
-    def __init__(
-        self,
-        *,
-        aggregates_config: dict[str, str],
-        ignore_tracker: IgnoreTracker,
-        root: Path,
-    ) -> None:
-        self._aggregates_config = aggregates_config
-        self._ignore_tracker = ignore_tracker
-        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:
-        """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
-
-        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.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)
-
-    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."""
-        self._current_test = nodeid
-
-    @property
-    def violations(self) -> list[ViolationRecord]:
-        """Recorded crossings, most-affecting first (then by call place)."""
-        return sorted(
-            self._violations.values(),
-            key=lambda v: (-len(v.tests), v.file, v.line_number),
-        )
-
-    def find_stale_patterns(self) -> list[str]:
-        return self._ignore_tracker.find_stale_patterns()
-
-    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: set[str] | None = None
-        if self._ignore_tracker.is_active:
-            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)
-
-        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
-
-        if file_paths is not None and self._ignore_tracker.has_ignore_for(
-            file_paths=file_paths
-        ):
-            self._ignore_tracker.mark_used(file_paths=file_paths)
-            return
-
-        if frames is None:
-            frames = find_frames_inside_project(root=self._root_path)
-        self._record_violation(
-            call_place=frames[0] if frames else None, crossing=crossing
-        )
-
-    def _find_crossing(
-        self, *, labels: Iterable[str]
-    ) -> tuple[tuple[str, ...], tuple[str, ...]] | None:
-        """Return ``(crossed aggregate names, joined model labels)`` if the query
-        crosses a boundary, else None.
-
-        e.g. ``(("order", "payment"), ("order.Invoice", "payrolls.IncomePayment"))``.
-        """
-        aggregate_by_label = {
-            label: aggregate
-            for label in labels
-            if (aggregate := self._aggregates_config.get(label.lower())) is not None
-        }
-        aggregates = set(aggregate_by_label.values())
-        if len(aggregates) <= 1:
-            return None
-        return tuple(sorted(aggregates)), tuple(sorted(aggregate_by_label.keys()))
-
-    def _record_violation(
-        self,
-        *,
-        call_place: tuple[str, int] | None,
-        crossing: tuple[tuple[str, ...], tuple[str, ...]],
-    ) -> None:
-        crossed_aggregates, joined_models = crossing
-        file, line = call_place if call_place is not None else ("<unknown>", 0)
-        key = (file, line, crossed_aggregates)
-        record = self._violations.get(key)
-        if record is None:
-            record = ViolationRecord(
-                file=file,
-                line_number=line,
-                crossed_aggregates=crossed_aggregates,
-                joined_models=joined_models,
-            )
-            self._violations[key] = record
-        if self._current_test is not None:
-            record.tests.add(self._current_test)
-
-
-def build_guard(*, rootpath: Path, config_path: Path) -> BoundaryGuard | None:
-    aggregates_by_model = load_aggregates_from_config(path=config_path)
-    if not aggregates_by_model:
-        return None
-
-    ignore_patterns = load_ignored_files_from_config(path=config_path)
-    tracker = IgnoreTracker(patterns=ignore_patterns)
-
-    return BoundaryGuard(
-        aggregates_config=aggregates_by_model, ignore_tracker=tracker, root=rootpath
-    )