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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-orm-boundaries
-Version: 0.5.0
+Version: 0.7.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
@@ -60,14 +60,19 @@ 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):
+Declare your aggregates and their Django models 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"]
+[aggregates.client]
+models = ["bookshop.Client"]
+
+[aggregates.book]
+models = ["bookshop.Book"]
+
+[aggregates.purchase]
+models = ["bookshop.Purchase", "bookshop.PurchaseLine"]
 ```
 
 Models are written as `app_label.Model`. Models not listed in any aggregate are
@@ -75,8 +80,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 +120,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 +149,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 +172,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 +188,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.7.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
@@ -31,14 +31,19 @@ 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):
+Declare your aggregates and their Django models 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"]
+[aggregates.client]
+models = ["bookshop.Client"]
+
+[aggregates.book]
+models = ["bookshop.Book"]
+
+[aggregates.purchase]
+models = ["bookshop.Purchase", "bookshop.PurchaseLine"]
 ```
 
 Models are written as `app_label.Model`. Models not listed in any aggregate are
@@ -46,8 +51,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 +91,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 +120,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 +143,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 +159,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.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pytest-orm-boundaries"
-version = "0.5.0"
+version = "0.7.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.7.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.7.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"),
     )
 
 
@@ -60,13 +62,41 @@ def _parse_aggregates(*, data: dict[str, Any], path: Path) -> dict[str, str]:
     Model labels are lower-cased ("app_label.modelname") for case-insensitive
     matching.
     """
+    aggregate_definitions = data.get("aggregates", {})
+    if not isinstance(aggregate_definitions, dict):
+        raise BoundariesConfigError(
+            f"{path}: define aggregates as named sections, for example "
+            "[aggregates.order] with models = [...]"
+        )
+
     aggregates_by_model: dict[str, str] = {}
-    for aggregate, members in data.get("aggregates", {}).items():
-        if isinstance(members, dict):
-            members = members.get("models", [])
+    for aggregate, definition in aggregate_definitions.items():
+        if not isinstance(definition, dict):
+            raise BoundariesConfigError(
+                f"{path}: aggregate '{aggregate}' must define models in its own "
+                "section: "
+                f"[aggregates.{aggregate}] with models = [...]"
+            )
+
+        unknown_fields = set(definition) - {"models"}
+        if unknown_fields:
+            fields = ", ".join(sorted(unknown_fields))
+            raise BoundariesConfigError(
+                f"{path}: aggregate '{aggregate}' has unknown field(s): {fields}"
+            )
+
+        if "models" not in definition:
+            raise BoundariesConfigError(
+                f"{path}: aggregate '{aggregate}' is missing required 'models'"
+            )
+        members = definition["models"]
         if not isinstance(members, list):
             raise BoundariesConfigError(
-                f"{path}: aggregate '{aggregate}' must be a list of model labels"
+                f"{path}: aggregate '{aggregate}' models must be a list"
+            )
+        if not members:
+            raise BoundariesConfigError(
+                f"{path}: aggregate '{aggregate}' models must not be empty"
             )
         for label in members:
             if not isinstance(label, str):
@@ -82,23 +112,27 @@ 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 section with a 'files' list"
+        )
 
-    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.7.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.7.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.7.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,
     )
 

{pytest_orm_boundaries-0.5.0 → pytest_orm_boundaries-0.7.0}/src/pytest_orm_boundaries/report.py

@@ -88,8 +88,8 @@ 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 crossing - "
-        f"their files are clean now. Remove them from {CONFIG_FILE_NAME}:",
+        "These [ignore] entries matched files that ran without crossing a "
+        f"boundary. Remove them from {CONFIG_FILE_NAME}:",
         yellow=True,
     )
     for pattern in stale: