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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-orm-boundaries
-Version: 0.6.0
+Version: 0.7.1
 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
@@ -50,24 +50,37 @@ and reports access that crosses a configured boundary - through `__` lookups,
 
 ## Install
 
-Install the plugin with Django support:
+Install the plugin in your Django project:
 
 ```bash
-pip install "pytest-orm-boundaries[django]"
+pip install pytest-orm-boundaries
 ```
 
 pytest discovers the plugin automatically.
 
+The plugin uses the Django version already installed by your project. If you are
+installing into an environment without Django and want pip to install it too,
+use the optional extra:
+
+```bash
+pip install "pytest-orm-boundaries[django]"
+```
+
 ## 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
@@ -146,18 +159,21 @@ Places are ordered by how many tests they affect. Pass `-v` to see every affecte
 
 ## 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:
+CQRS read models may cross aggregate boundaries by design, while 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.
+  span aggregates, such as CQRS read models. 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.
+  and the plugin reports the entry when its matching code runs without a
+  crossing.
 
 ```toml
 [allow]
 files = [
-    "app/reports/sales_summary.py",
+    "app/read_models/sales.py",
 ]
 
 [ignore]
@@ -173,13 +189,12 @@ resolved relative to pytest's root directory and matched against either:
 - the file that issues the query, or
 - the test file.
 
-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:
+An `[ignore]` whose matching code runs through the whole suite without crossing
+a boundary is stale, so the plugin lists it for removal:
 
 ```
 ======================= orm-boundaries: stale ignores ========================
-These [ignore] entries no longer suppress any boundary crossing - their files are clean now.
-Remove them from boundaries.toml:
+These [ignore] entries matched files that ran without crossing a boundary. Remove them from boundaries.toml:
   - app/billing.py
 ```
 

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

@@ -21,24 +21,37 @@ and reports access that crosses a configured boundary - through `__` lookups,
 
 ## Install
 
-Install the plugin with Django support:
+Install the plugin in your Django project:
 
 ```bash
-pip install "pytest-orm-boundaries[django]"
+pip install pytest-orm-boundaries
 ```
 
 pytest discovers the plugin automatically.
 
+The plugin uses the Django version already installed by your project. If you are
+installing into an environment without Django and want pip to install it too,
+use the optional extra:
+
+```bash
+pip install "pytest-orm-boundaries[django]"
+```
+
 ## 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
@@ -117,18 +130,21 @@ Places are ordered by how many tests they affect. Pass `-v` to see every affecte
 
 ## 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:
+CQRS read models may cross aggregate boundaries by design, while 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.
+  span aggregates, such as CQRS read models. 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.
+  and the plugin reports the entry when its matching code runs without a
+  crossing.
 
 ```toml
 [allow]
 files = [
-    "app/reports/sales_summary.py",
+    "app/read_models/sales.py",
 ]
 
 [ignore]
@@ -144,13 +160,12 @@ resolved relative to pytest's root directory and matched against either:
 - the file that issues the query, or
 - the test file.
 
-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:
+An `[ignore]` whose matching code runs through the whole suite without crossing
+a boundary is stale, so the plugin lists it for removal:
 
 ```
 ======================= orm-boundaries: stale ignores ========================
-These [ignore] entries no longer suppress any boundary crossing - their files are clean now.
-Remove them from boundaries.toml:
+These [ignore] entries matched files that ran without crossing a boundary. Remove them from boundaries.toml:
   - app/billing.py
 ```
 

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pytest-orm-boundaries"
-version = "0.6.0"
+version = "0.7.1"
 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 → pytest_orm_boundaries-0.7.1}/src/pytest_orm_boundaries/config.py

@@ -62,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):
@@ -90,7 +118,9 @@ def _parse_file_globs(
     """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")
+        raise BoundariesConfigError(
+            f"{path}: [{section_name}] must be a section with a 'files' list"
+        )
 
     files = section_data.get("files", [])
     if not isinstance(files, list):

{pytest_orm_boundaries-0.6.0 → pytest_orm_boundaries-0.7.1}/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: