pytest-orm-boundaries 0.1.0__tar.gz

pytest_orm_boundaries-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evgeniia Chibisova
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytest_orm_boundaries-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: pytest-orm-boundaries
+Version: 0.1.0
+Summary: Pytest plugin that fails your tests when ORM queries cross DDD aggregate boundaries (Django supported today).
+Keywords: django,pytest,plugin,orm,ddd,aggregate,boundaries,architecture
+Author: Evgeniia Chibisova
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Dist: pytest>=8
+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
+Description-Content-Type: text/markdown
+
+# pytest-orm-boundaries
+
+A pytest plugin that fails your tests when ORM queries cross 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
+# Payment and Order 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, including `__`, subqueries and other.
+
+## Install
+
+```bash
+pip install pytest-orm-boundaries
+```
+
+pytest picks the plugin up 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.
+
+## Status
+
+Alpha - testing basic version.

pytest_orm_boundaries-0.1.0/README.md

@@ -0,0 +1,44 @@
+# pytest-orm-boundaries
+
+A pytest plugin that fails your tests when ORM queries cross 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
+# Payment and Order 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, including `__`, subqueries and other.
+
+## Install
+
+```bash
+pip install pytest-orm-boundaries
+```
+
+pytest picks the plugin up 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.
+
+## Status
+
+Alpha - testing basic version.

pytest_orm_boundaries-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "pytest-orm-boundaries"
+version = "0.1.0"
+description = "Pytest plugin that fails your tests when ORM queries cross DDD aggregate boundaries (Django supported today)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Evgeniia Chibisova" }]
+keywords = [
+    "django",
+    "pytest",
+    "plugin",
+    "orm",
+    "ddd",
+    "aggregate",
+    "boundaries",
+    "architecture",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Django",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/evchibisova/pytest-orm-boundaries"
+Repository = "https://github.com/evchibisova/pytest-orm-boundaries"
+Issues = "https://github.com/evchibisova/pytest-orm-boundaries/issues"
+Changelog = "https://github.com/evchibisova/pytest-orm-boundaries/blob/main/CHANGELOG.md"
+
+[project.entry-points.pytest11]
+boundaries = "pytest_orm_boundaries.plugin"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pytest_orm_boundaries-0.1.0/src/pytest_orm_boundaries/check_boundaries.py

@@ -0,0 +1,128 @@
+"""Aggregate-boundary checking: parse the config, watch queries, fail on crossings.
+
+Django is imported lazily, inside the functions that need it (and under
+TYPE_CHECKING for annotations), so importing this module never requires Django
+to be installed.
+"""
+
+from __future__ import annotations
+
+import functools
+import tomllib
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from django.db.models import Model
+    from django.db.models.sql.query import Query
+
+
+class BoundaryViolation(Exception):
+    """Raised when a query joins models from more than one aggregate."""
+
+
+class BoundariesConfigError(Exception):
+    """Raised when the config file is malformed or semantically invalid."""
+
+
+def load_aggregates_from_config(*, path: Path) -> dict[str, str]:
+    """Parse the config into a {model_label: aggregate_name} map.
+
+    Model labels are lower-cased ("app_label.modelname") for case-insensitive
+    matching.
+    """
+    try:
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
+        raise BoundariesConfigError(f"{path}: invalid TOML ({exc})") from exc
+
+    aggregates_by_model: dict[str, str] = {}
+    for aggregate, members in data.get("aggregates", {}).items():
+        if isinstance(members, dict):
+            members = members.get("models", [])
+        if not isinstance(members, list):
+            raise BoundariesConfigError(
+                f"{path}: aggregate '{aggregate}' must be a list of model labels"
+            )
+        for label in members:
+            if not isinstance(label, str):
+                raise BoundariesConfigError(
+                    f"{path}: aggregate '{aggregate}' has a non-string member: {label!r}"
+                )
+            owner = aggregates_by_model.setdefault(label.lower(), aggregate)
+            if owner != aggregate:
+                raise BoundariesConfigError(
+                    f"{path}: model '{label}' claimed by two aggregates: "
+                    f"'{owner}' and '{aggregate}'"
+                )
+    return aggregates_by_model
+
+
+def _check_models(
+    *,
+    models: Iterable[type[Model]],
+    aggregates_config: dict[str, str],
+) -> None:
+    
+    aggregate_by_model_label = {
+        model._meta.label: aggregate
+        for model in models
+        if (aggregate := aggregates_config.get(model._meta.label_lower)) is not None
+    }
+    aggregates = set(aggregate_by_model_label.values())
+    if len(aggregates) <= 1:
+        return
+
+    crossed = ", ".join(sorted(aggregates))
+    joined = ", ".join(sorted(aggregate_by_model_label.keys()))
+    raise BoundaryViolation(
+        f"orm-boundaries: query crosses aggregate boundaries "
+        f"({crossed}); joined models: {joined}"
+    )
+
+
+@functools.cache
+def _table_to_model() -> dict[str, type[Model]]:
+    """Map db_table -> model class for every installed model."""
+    from django.apps import apps
+
+    return {model._meta.db_table: model for model in apps.get_models()}
+
+
+def _get_models_from_query(*, query: Query) -> list[type[Model]]:
+    table_to_model = _table_to_model()
+    return [
+        table_to_model[table.table_name]
+        for table in query.alias_map.values()
+        if table.table_name in table_to_model
+    ]
+
+
+def install_guard(*, aggregates_config: dict[str, str]) -> Callable[..., Any]:
+    """Wrap SQLCompiler.execute_sql to check every executed query.
+
+    Returns the original method so the caller can restore it later.
+    """
+    from django.db.models.sql.compiler import SQLCompiler
+
+    original = SQLCompiler.execute_sql
+
+    def patched_execute_sql(self, *args, **kwargs):
+        query_models = _get_models_from_query(query=self.query)
+        _check_models(
+            models=query_models,
+            aggregates_config=aggregates_config,
+        )
+        return original(self, *args, **kwargs)
+
+    SQLCompiler.execute_sql = patched_execute_sql
+    return original
+
+
+def uninstall_guard(*, original: Callable[..., Any]) -> None:
+    """Restore the original SQLCompiler.execute_sql."""
+    from django.db.models.sql.compiler import SQLCompiler
+
+    SQLCompiler.execute_sql = original

pytest_orm_boundaries-0.1.0/src/pytest_orm_boundaries/plugin.py

@@ -0,0 +1,97 @@
+"""Pytest plugin wiring: options, config discovery, activation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from .check_boundaries import (
+    BoundariesConfigError,
+    install_guard,
+    load_aggregates_from_config,
+    uninstall_guard,
+)
+
+CONFIG_FILE_NAME = "boundaries.toml"
+
+config_path_key = pytest.StashKey[Path | None]()
+original_execute_sql_key = pytest.StashKey[object]()
+
+
+class BoundariesConfigWarning(UserWarning):
+    """Plugin is installed but no config file was found."""
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("orm-boundaries")
+    group.addoption(
+        "--boundaries-config",
+        dest="boundaries_config",
+        metavar="PATH",
+        default=None,
+        help=(
+            "Path to the boundaries TOML config. Defaults to "
+            f"{CONFIG_FILE_NAME} in the pytest root directory; if no config "
+            "file is found, boundary checks are disabled."
+        ),
+    )
+    parser.addini(
+        "boundaries_config",
+        help="Same as --boundaries-config.",
+        default="",
+    )
+
+
+def _discover_config_path(*, config: pytest.Config) -> Path | None:
+    explicit = config.getoption("boundaries_config") or config.getini(
+        "boundaries_config"
+    )
+    if explicit:
+        path = Path(explicit)
+        if not path.is_absolute():
+            path = config.rootpath / path
+        if not path.is_file():
+            raise pytest.UsageError(
+                f"orm-boundaries: config file not found: {path}"
+            )
+        return path
+    default = config.rootpath / CONFIG_FILE_NAME
+    return default if default.is_file() else None
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    path = _discover_config_path(config=config)
+    config.stash[config_path_key] = path
+    if path is None:
+        config.issue_config_time_warning(
+            BoundariesConfigWarning(
+                f"no {CONFIG_FILE_NAME} found in the pytest root directory; "
+                "orm-boundaries is inactive, so no boundary checks will run."
+            ),
+            stacklevel=2,
+        )
+        return
+    try:
+        aggregates_by_model = load_aggregates_from_config(path=path)
+    except BoundariesConfigError as exc:
+        raise pytest.UsageError(f"orm-boundaries: {exc}") from exc
+    if not aggregates_by_model:
+        # Config present but defines no aggregates, so skip patching entirely.
+        return
+    config.stash[original_execute_sql_key] = install_guard(
+        aggregates_config=aggregates_by_model
+    )
+
+
+def pytest_unconfigure(config: pytest.Config) -> None:
+    original = config.stash.get(original_execute_sql_key, None)
+    if original is not None:
+        uninstall_guard(original=original)
+
+
+def pytest_report_header(config: pytest.Config) -> str:
+    path = config.stash.get(config_path_key, None)
+    if path is None:
+        return "orm-boundaries: no config file, checks disabled"
+    return f"orm-boundaries: config {path}"