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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-orm-boundaries
-Version: 0.5.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
@@ -29,11 +29,11 @@ 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
@@ -44,8 +44,8 @@ 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 — through `__` lookups,
+`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
@@ -75,8 +75,9 @@ 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:
+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:
 
@@ -114,7 +115,7 @@ the `purchase` and `client` aggregates:
   Purchase.objects.prefetch_related("client")
   ```
 
-Queries that don't actually join across the boundary are **not** flagged — for
+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
@@ -143,11 +144,22 @@ 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
 
-Add exceptions so that known offenders keep passing while you fix them one file at a time:
+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:
+
+- `[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",
@@ -155,14 +167,14 @@ 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 ========================
@@ -171,6 +183,9 @@ Remove them from boundaries.toml:
   - app/billing.py
 ```
 
+`[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

{pytest_orm_boundaries-0.5.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,8 +15,8 @@ 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 — through `__` lookups,
+`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
@@ -46,8 +46,9 @@ 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:
+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:
 
@@ -85,7 +86,7 @@ the `purchase` and `client` aggregates:
   Purchase.objects.prefetch_related("client")
   ```
 
-Queries that don't actually join across the boundary are **not** flagged — for
+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
@@ -114,11 +115,22 @@ 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
 
-Add exceptions so that known offenders keep passing while you fix them one file at a time:
+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:
+
+- `[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",
@@ -126,14 +138,14 @@ 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 ========================
@@ -142,6 +154,9 @@ Remove them from boundaries.toml:
   - app/billing.py
 ```
 
+`[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

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pytest-orm-boundaries"
-version = "0.5.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"

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.5.0 → pytest_orm_boundaries-0.6.0}/src/pytest_orm_boundaries/config.py

@@ -19,7 +19,8 @@ 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
+    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:
@@ -42,7 +43,8 @@ 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),
+        ignored_files=_parse_file_globs(data=data, path=path, section_name="ignore"),
+        allowed_files=_parse_file_globs(data=data, path=path, section_name="allow"),
     )
 
 
@@ -82,23 +84,25 @@ def _parse_aggregates(*, data: dict[str, Any], path: Path) -> dict[str, str]:
     return aggregates_by_model
 
 
-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")
+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.5.0 → pytest_orm_boundaries-0.6.0}/src/pytest_orm_boundaries/crossings.py

@@ -11,6 +11,7 @@ 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
 
 
@@ -27,16 +28,19 @@ class CrossingRecord:
 
 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."""
+    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
@@ -48,13 +52,16 @@ class CrossingTracker:
 
     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.
+        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, gathered lazily:
-        # for the ignore/stale bookkeeping and to name each crossing's place.
+        # ``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._ignore_tracker.is_active:
+        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)
@@ -63,11 +70,12 @@ class CrossingTracker:
             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 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

{pytest_orm_boundaries-0.5.0 → pytest_orm_boundaries-0.6.0}/src/pytest_orm_boundaries/guard.py

@@ -20,6 +20,7 @@ from pytest_orm_boundaries.sql_parsing import extract_table_names, looks_like_da
 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
 
@@ -45,11 +46,13 @@ class BoundaryGuard:
         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,
         )

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

@@ -14,6 +14,7 @@ from pytest_orm_boundaries.config import (
     discover_config_path,
     load_config,
 )
+from pytest_orm_boundaries.allows import AllowList
 from pytest_orm_boundaries.guard import BoundaryGuard
 from pytest_orm_boundaries.ignores import IgnoreTracker
 
@@ -56,10 +57,12 @@ def _build_guard(*, rootpath: Path, config_path: Path) -> BoundaryGuard | None:
     if not config.aggregates_by_model:
         return None
 
-    tracker = IgnoreTracker(patterns=config.ignored_files)
+    allow_list = AllowList(patterns=config.allowed_files)
+    ignore_tracker = IgnoreTracker(patterns=config.ignored_files)
     return BoundaryGuard(
         aggregates_config=config.aggregates_by_model,
-        ignore_tracker=tracker,
+        allow_list=allow_list,
+        ignore_tracker=ignore_tracker,
         root=rootpath,
     )