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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-orm-boundaries
-Version: 0.3.1
+Version: 0.5.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,11 +17,14 @@ 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-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
@@ -41,17 +44,19 @@ 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 queries your test suite executes and reports
+the ones that step outside their aggregate — 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
 
@@ -68,25 +73,75 @@ 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 flags queries that read across an aggregate boundary. Each example below couples
+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.
+
+- `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
+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:
 
 ```
-===================== orm-boundaries: boundary violations ======================
+====================== orm-boundaries: boundary crossings ======================
 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.
+orm-boundaries: FAILED - 1 boundary crossing(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
 
@@ -111,11 +166,22 @@ boundary, the plugin says so at the end:
 
 ```
 ======================= 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
 ```
 
+## 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)
+
+- 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
 
 Alpha - testing basic version.

pytest_orm_boundaries-0.5.0/README.md

@@ -0,0 +1,158 @@
+# pytest-orm-boundaries
+
+> 💡 **Even if you control your imports — boundaries still can leak through the ORM**
+
+A `pytest-orm-boundaries` is a pytest plugin that reports ORM queries crossing your DDD aggregate boundaries.
+
+Currently works with Django ORM.
+
+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
+lookups make it easy to cross those boundaries silently:
+
+```python
+# Purchase and Client belong to different aggregates — this query couples them.
+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 — 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[django]"
+```
+
+pytest discovers the plugin automatically.
+
+## Configure
+
+Declare your aggregates in `boundaries.toml` at the project root (or point at
+the file with `--boundaries-config` / the `boundaries_config` ini option):
+
+```toml
+[aggregates]
+client   = ["bookshop.Client"]
+book     = ["bookshop.Book"]
+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 flags queries that read across an aggregate boundary. Each example below couples
+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.
+
+- `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
+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:
+
+```
+====================== orm-boundaries: boundary crossings ======================
+1 place(s) in your code crossed aggregate boundaries, affecting 1 test(s):
+
+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 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
+
+Add exceptions so that known offenders keep passing while you fix them one file at a time:
+
+```toml
+[ignore]
+files = [
+    "app/billing.py",
+    "app/legacy/*",
+]
+```
+
+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:
+
+```
+======================= orm-boundaries: stale ignores ========================
+These [ignore] entries no longer suppress any boundary crossing - their files are clean now.
+Remove them from boundaries.toml:
+  - app/billing.py
+```
+
+## 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)
+
+- 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
+
+Alpha - testing basic version.

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pytest-orm-boundaries"
-version = "0.3.1"
+version = "0.5.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,10 @@ classifiers = [
     "Topic :: Software Development :: Quality Assurance",
     "Topic :: Software Development :: Testing",
 ]
-dependencies = ["pytest>=8"]
+dependencies = ["pytest>=8", "sqlglot>=30,<31"]
+
+[project.optional-dependencies]
+django = ["django>=4.2"]
 
 [project.urls]
 Homepage = "https://github.com/evchibisova/pytest-orm-boundaries"
@@ -44,6 +47,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.5.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/src/pytest_orm_boundaries/read_config.py → pytest_orm_boundaries-0.5.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,14 @@ 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]  # glob patterns
+
+
 def discover_config_path(*, explicit: str | None, rootpath: Path) -> Path | None:
     """Resolve the config path.
 
@@ -29,6 +38,14 @@ 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_ignored_files(data=data, path=path),
+    )
+
+
 def _read_config(*, path: Path) -> dict[str, Any]:
     try:
         with path.open("rb") as fh:
@@ -37,16 +54,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,10 +82,8 @@ 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)
-
+def _parse_ignored_files(*, data: dict[str, Any], path: Path) -> list[str]:
+    """Read ``[ignore] files`` into a list of glob patterns."""
     ignore = data.get("ignore", {})
     if not isinstance(ignore, dict):
         raise BoundariesConfigError(f"{path}: [ignore] must be a table")

pytest_orm_boundaries-0.5.0/src/pytest_orm_boundaries/crossings.py

@@ -0,0 +1,131 @@
+"""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.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 ignored files and naming each crossing's call place and test."""
+
+    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._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
+        active ignore covers the call place.
+        """
+        # ``frames`` is the in-project part of the call stack, gathered lazily:
+        # for the ignore/stale bookkeeping and to name each crossing's place.
+        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)
+
+        for labels in label_sets:
+            crossing = self.find_crossing(labels=labels)
+            if crossing is None:
+                continue
+            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)
+                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()