django-nplus1 0.1.0__tar.gz

django_nplus1-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+*.py[cod]
+__pycache__/
+.DS_Store
+*.sql
+*.bz2
+*~
+*.log
+*.wsgi
+local_settings.py
+development_settings.py
+*.egg-info
+.project
+.pydevproject
+.settings
+versiontools*
+_build*
+doc/index.html
+/build/
+/dist/
+*.swp
+\#*
+.\#*
+.tox
+dump.rdb
+.idea
+.venv
+.coverage
+coverage.xml
+cobertura.xml
+CLAUDE.md
+site/
+*.sqlite3
+docs/superpowers/

django_nplus1-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oliver Haas
+
+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.

django_nplus1-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: django-nplus1
+Version: 0.1.0
+Summary: N+1 query detection for Django
+Project-URL: Homepage, https://github.com/oliverhaas/django-nplus1
+Project-URL: Documentation, https://oliverhaas.github.io/django-nplus1/
+Project-URL: Repository, https://github.com/oliverhaas/django-nplus1.git
+Project-URL: Changelog, https://oliverhaas.github.io/django-nplus1/reference/changelog/
+Author-email: Oliver Haas <ohaas@e1plus.de>
+License: MIT License
+        
+        Copyright (c) 2026 Oliver Haas
+        
+        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.
+License-File: LICENSE
+Keywords: detection,django,n+1,orm,performance,query
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: django<7,>=5.2
+Description-Content-Type: text/markdown
+
+# django-nplus1
+
+N+1 query detection for Django. Beta - API may still change before 1.0.
+
+## Quick Start
+
+```bash
+pip install django-nplus1
+```
+
+```python
+# settings.py
+INSTALLED_APPS = [..., "django_nplus1"]
+```
+
+```python
+# tests.py
+@pytest.mark.nplus1
+class TestMyView:
+    def test_list_books(self, books):
+        response = client.get("/books/")  # raises NPlus1Error if view has N+1
+```
+
+Tests marked with `@pytest.mark.nplus1` will fail if the code under test triggers an N+1 query. Fix the N+1, or use `nplus1_allow()` in helper functions that intentionally defer prefetching to their callers.
+
+See [examples/](examples/) for a working project and the [docs](https://oliverhaas.github.io/django-nplus1/) for full configuration.
+
+## Credits
+
+This project builds on the work of:
+
+- [nplusone](https://github.com/jmcarp/nplusone) by Joshua Carp - the original automatic N+1 detection library for Python ORMs. django-nplus1 started as a Django-specific fork of nplusone's architecture.
+- [django-zeal](https://github.com/taobojlen/django-zeal) by Tao Bojlen - inspired several features including deferred field detection, `.get()`-in-a-loop detection, `ContextVar`-based async safety, call-site tracking, and configurable thresholds.
+
+## License
+
+MIT

django_nplus1-0.1.0/README.md

@@ -0,0 +1,37 @@
+# django-nplus1
+
+N+1 query detection for Django. Beta - API may still change before 1.0.
+
+## Quick Start
+
+```bash
+pip install django-nplus1
+```
+
+```python
+# settings.py
+INSTALLED_APPS = [..., "django_nplus1"]
+```
+
+```python
+# tests.py
+@pytest.mark.nplus1
+class TestMyView:
+    def test_list_books(self, books):
+        response = client.get("/books/")  # raises NPlus1Error if view has N+1
+```
+
+Tests marked with `@pytest.mark.nplus1` will fail if the code under test triggers an N+1 query. Fix the N+1, or use `nplus1_allow()` in helper functions that intentionally defer prefetching to their callers.
+
+See [examples/](examples/) for a working project and the [docs](https://oliverhaas.github.io/django-nplus1/) for full configuration.
+
+## Credits
+
+This project builds on the work of:
+
+- [nplusone](https://github.com/jmcarp/nplusone) by Joshua Carp - the original automatic N+1 detection library for Python ORMs. django-nplus1 started as a Django-specific fork of nplusone's architecture.
+- [django-zeal](https://github.com/taobojlen/django-zeal) by Tao Bojlen - inspired several features including deferred field detection, `.get()`-in-a-loop detection, `ContextVar`-based async safety, call-site tracking, and configurable thresholds.
+
+## License
+
+MIT

django_nplus1-0.1.0/django_nplus1/__init__.py

@@ -0,0 +1,14 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from django_nplus1.detect import nplus1_allow
+from django_nplus1.exceptions import NPlus1Error
+from django_nplus1.middleware import NPlus1Middleware
+from django_nplus1.profiler import Profiler
+from django_nplus1.signals import nplus1_detected
+
+try:
+    __version__ = version("django-nplus1")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["NPlus1Error", "NPlus1Middleware", "Profiler", "__version__", "nplus1_allow", "nplus1_detected"]

django_nplus1-0.1.0/django_nplus1/apps.py

@@ -0,0 +1,9 @@
+from django.apps import AppConfig
+
+
+class DjangoNPlus1Config(AppConfig):
+    name = "django_nplus1"
+    verbose_name = "Django N+1"
+
+    def ready(self) -> None:
+        from django_nplus1 import patch  # noqa: F401

django_nplus1-0.1.0/django_nplus1/detect.py

@@ -0,0 +1,438 @@
+from __future__ import annotations
+
+import contextlib
+import fnmatch
+import re
+from collections import defaultdict
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Sequence
+
+
+class Rule:
+    def __init__(self, label: str | None = None, model: str | type | None = None, field: str | None = None) -> None:
+        self.label = label
+        self.model = model
+        self.field = field
+
+    def compare(self, label: str, model: type, field: str) -> bool:
+        return bool(
+            (self.label or self.model or self.field)
+            and (self.label is None or self.label == label)
+            and (self.model is None or self.match_model(model))
+            and (self.field is None or self.match_field(field)),
+        )
+
+    def match_field(self, field: str) -> bool:
+        if self.field is None:
+            return True
+        return fnmatch.fnmatch(field, self.field)
+
+    def match_model(self, model: type) -> bool:
+        if self.model is model:
+            return True
+        if isinstance(self.model, str):
+            return fnmatch.fnmatch(model.__name__, self.model)
+        return False
+
+
+_allow_rules: ContextVar[list[Rule]] = ContextVar("nplus1_allow_rules")
+
+
+def is_allowed(message: Message) -> bool:
+    """Check if a message is suppressed by nplus1_allow rules."""
+    try:
+        rules = _allow_rules.get()
+    except LookupError:
+        return False
+    return message.match(rules) if rules else False
+
+
+@contextlib.contextmanager
+def nplus1_allow(whitelist: list[dict[str, Any]] | None = None) -> Generator[None]:
+    """Context manager to suppress N+1 detection for specific model/field combinations.
+
+    With no arguments, suppresses all detections. With a whitelist, suppresses only
+    matching detections. Uses the same format as ``Profiler(whitelist=...)`` and
+    ``@pytest.mark.nplus1(whitelist=...)``.
+
+    Usage::
+
+        # Suppress all detections
+        with nplus1_allow():
+            ...
+
+        # Suppress specific model/field
+        with nplus1_allow([{"model": "User", "field": "hobbies"}]):
+            ...
+
+        # Suppress all fields on a model (supports fnmatch wildcards)
+        with nplus1_allow([{"model": "User"}]):
+            ...
+    """
+    rules = [Rule(**item) for item in whitelist] if whitelist else [Rule(model="*", field="*")]
+
+    try:
+        current = _allow_rules.get()
+    except LookupError:
+        current = []
+    token = _allow_rules.set([*current, *rules])
+    try:
+        yield
+    finally:
+        _allow_rules.reset(token)
+
+
+class Message:
+    label: str = ""
+    formatter: str = ""
+
+    def __init__(
+        self,
+        model: type,
+        field: str,
+        caller: tuple[str, int, str] | None = None,
+        callers: list[list[tuple[str, int, str]]] | None = None,
+    ) -> None:
+        self.model = model
+        self.field = field
+        self.caller = caller
+        self.callers = callers
+
+    @property
+    def message(self) -> str:
+        base = self.formatter.format(
+            label=self.label,
+            model=self.model.__name__,
+            field=self.field,
+        )
+        if self.callers:
+            parts = [base, " with calls:"]
+            for i, stack in enumerate(self.callers, 1):
+                parts.append(f"\nCALL {i}:")
+                for fn, lineno, funcname in stack:
+                    parts.append(f"\n  {fn}:{lineno} in {funcname}")
+            return "".join(parts)
+        if self.caller:
+            filename, lineno, funcname = self.caller
+            return f"{base} at {filename}:{lineno} in {funcname}"
+        return base
+
+    def match(self, rules: Sequence[Rule]) -> bool:
+        return any(rule.compare(self.label, self.model, self.field) for rule in rules)
+
+
+class LazyLoadMessage(Message):
+    label = "n_plus_one"
+    formatter = "Potential n+1 query detected on `{model}.{field}`"
+
+
+class EagerLoadMessage(Message):
+    label = "unused_eager_load"
+    formatter = "Potential unnecessary eager load detected on `{model}.{field}`"
+
+
+class GetLoopMessage(Message):
+    label = "get_in_loop"
+    formatter = "Potential n+1 query detected on `{model}.{field}`"
+
+
+class Listener:
+    def __init__(self, parent: Any) -> None:
+        self.parent = parent
+
+    def setup(self) -> None:
+        pass
+
+    def teardown(self) -> None:
+        pass
+
+
+class LazyListener(Listener):
+    loaded: set[str]
+    ignore: set[str]
+    counts: defaultdict[tuple[type, str], int]
+    show_all_callers: bool
+    call_stacks: defaultdict[tuple[type, str], list[list[tuple[str, int, str]]]]
+
+    def setup(self) -> None:
+        from django.conf import settings
+
+        from django_nplus1 import signals
+
+        self.loaded = set()
+        self.ignore = set()
+        self.counts = defaultdict(int)
+        self.threshold = getattr(settings, "NPLUS1_THRESHOLD", 2)
+        self.show_all_callers = getattr(settings, "NPLUS1_SHOW_ALL_CALLERS", False)
+        self.call_stacks = defaultdict(list)
+        signals.connect(signals.LOAD, self.handle_load)
+        signals.connect(signals.IGNORE_LOAD, self.handle_ignore)
+        signals.connect(signals.LAZY_LOAD, self.handle_lazy)
+        signals.connect(signals.EAGER_LOAD, self.handle_eager)
+
+    def teardown(self) -> None:
+        from django_nplus1 import signals
+
+        signals.disconnect(signals.LOAD, self.handle_load)
+        signals.disconnect(signals.IGNORE_LOAD, self.handle_ignore)
+        signals.disconnect(signals.LAZY_LOAD, self.handle_lazy)
+        signals.disconnect(signals.EAGER_LOAD, self.handle_eager)
+
+    def handle_load(
+        self,
+        args: tuple[Any, ...] | None = None,
+        kwargs: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+        ret: Any = None,
+        parser: Any = None,
+    ) -> None:
+        instances = parser(args, kwargs, context, ret)
+        self.loaded.update(instances)
+
+    def handle_ignore(
+        self,
+        args: tuple[Any, ...] | None = None,
+        kwargs: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+        ret: Any = None,
+        parser: Any = None,
+    ) -> None:
+        instances = parser(args, kwargs, context, ret)
+        self.ignore.update(instances)
+
+    def handle_lazy(
+        self,
+        args: tuple[Any, ...] | None = None,
+        kwargs: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+        ret: Any = None,
+        parser: Any = None,
+    ) -> None:
+        model, instance, field = parser(args, kwargs, context)
+        if instance in self.loaded and instance not in self.ignore:
+            key = (model, field)
+            self.counts[key] += 1
+            if self.show_all_callers:
+                from django_nplus1.util import get_stack
+
+                self.call_stacks[key].append(get_stack())
+            if self.counts[key] == self.threshold:
+                if self.show_all_callers:
+                    message = LazyLoadMessage(model, field, callers=self.call_stacks[key])
+                else:
+                    from django_nplus1.util import get_caller
+
+                    caller = get_caller()
+                    message = LazyLoadMessage(model, field, caller=caller)
+                self.parent.notify(message)
+
+    def handle_eager(
+        self,
+        args: tuple[Any, ...] | None = None,
+        kwargs: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+        ret: Any = None,
+        parser: Any = None,
+    ) -> None:
+        # When a single bulk-loaded instance triggers an eager load (e.g.
+        # select_related on one item from a queryset), this is semantically
+        # an N+1 pattern, not an unused eager load. We use LazyLoadMessage
+        # with label "n_plus_one" intentionally.
+        model, field, keys, _key = parser(args, kwargs, context)
+        if len(keys) == 1 and keys[0] in self.loaded and keys[0] not in self.ignore:
+            key = (model, field)
+            self.counts[key] += 1
+            if self.show_all_callers:
+                from django_nplus1.util import get_stack
+
+                self.call_stacks[key].append(get_stack())
+            if self.counts[key] == self.threshold:
+                if self.show_all_callers:
+                    message = LazyLoadMessage(model, field, callers=self.call_stacks[key])
+                else:
+                    from django_nplus1.util import get_caller
+
+                    caller = get_caller()
+                    message = LazyLoadMessage(model, field, caller=caller)
+                self.parent.notify(message)
+
+
+class EagerListener(Listener):
+    tracker: EagerTracker
+    touched: list[tuple[type, str, list[str]] | None]
+
+    def setup(self) -> None:
+        from django_nplus1 import signals
+
+        self.tracker = EagerTracker()
+        self.touched = []
+        signals.connect(signals.EAGER_LOAD, self.handle_eager)
+        signals.connect(signals.TOUCH, self.handle_touch)
+
+    def teardown(self) -> None:
+        from django_nplus1 import signals
+
+        signals.disconnect(signals.EAGER_LOAD, self.handle_eager)
+        signals.disconnect(signals.TOUCH, self.handle_touch)
+        self.log_eager()
+
+    def handle_eager(
+        self,
+        args: tuple[Any, ...] | None = None,
+        kwargs: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+        ret: Any = None,
+        parser: Any = None,
+    ) -> None:
+        self.tracker.track(*parser(args, kwargs, context))
+
+    def handle_touch(
+        self,
+        args: tuple[Any, ...] | None = None,
+        kwargs: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+        ret: Any = None,
+        parser: Any = None,
+    ) -> None:
+        self.touched.append(parser(args, kwargs, context))
+
+    def log_eager(self) -> None:
+        self.tracker.prune([each for each in self.touched if each])
+        for model, field in self.tracker.unused:
+            message = EagerLoadMessage(model, field)
+            self.parent.notify(message)
+
+
+class EagerTracker:
+    def __init__(self) -> None:
+        self.data: defaultdict[tuple[type, str], defaultdict[int, set[str]]] = defaultdict(
+            lambda: defaultdict(set),
+        )
+
+    def track(self, model: type, field: str, instances: list[str], key: int) -> None:
+        self.data[(model, field)][key].update(instances)
+
+    def prune(self, touched: list[tuple[type, str, list[str]]]) -> None:
+        for model, field, touch_instances in touched:
+            group = self.data[(model, field)]
+            for key, fetch_instances in list(group.items()):
+                if touch_instances and fetch_instances.intersection(touch_instances):
+                    group.pop(key, None)
+
+    @property
+    def unused(self) -> list[tuple[type, str]]:
+        return [(model, field) for (model, field), group in self.data.items() if group]
+
+
+class GetLoopListener(Listener):
+    """Detects Model.objects.get() called repeatedly from the same call-site."""
+
+    counts: defaultdict[tuple[Any, ...], int]
+
+    def setup(self) -> None:
+        from django.conf import settings
+
+        from django_nplus1 import signals
+
+        self.counts = defaultdict(int)
+        self.threshold = getattr(settings, "NPLUS1_GET_THRESHOLD", 2)
+        signals.connect(signals.GET_CALL, self.handle_get)
+
+    def teardown(self) -> None:
+        from django_nplus1 import signals
+
+        signals.disconnect(signals.GET_CALL, self.handle_get)
+
+    def handle_get(
+        self,
+        args: tuple[Any, ...] | None = None,
+        kwargs: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+        ret: Any = None,
+        parser: Any = None,
+    ) -> None:
+        model, caller = parser(args, kwargs, context, ret)
+        key = (model, *caller)
+        self.counts[key] += 1
+        if self.counts[key] == self.threshold:
+            message = GetLoopMessage(model, "get()", caller=caller)
+            self.parent.notify(message)
+
+
+class DuplicateQueryMessage(Message):
+    label = "duplicate_query"
+    formatter = "Potential n+1 query detected: duplicate query `{field}`"
+
+
+class _SQL:
+    pass
+
+
+_SQL_LITERAL_RE = re.compile(r"'(?:[^']|'')*'|\b\d+\b")
+
+
+def _fingerprint_sql(sql: str) -> str:
+    """Normalize a SQL query by replacing literals with ?, collapsing whitespace."""
+    return " ".join(_SQL_LITERAL_RE.sub("?", sql).split())
+
+
+class DuplicateQueryListener(Listener):
+    """Detects repeated identical SQL queries (N+1 fallback for raw SQL).
+
+    Uses Django's connection.execute_wrapper to intercept all queries,
+    fingerprints them by normalizing literals, and counts occurrences
+    from the same call-site. This catches N+1 patterns from raw SQL,
+    .raw(), and any ORM path not covered by the descriptor-level detection.
+    """
+
+    def __init__(self, parent: Any) -> None:
+        super().__init__(parent)
+        self.enabled = False
+        self.counts: defaultdict[tuple[str, str, int, str], int] = defaultdict(int)
+        self._connection: Any = None
+
+    def setup(self) -> None:
+        from django.conf import settings
+        from django.db import connection
+
+        self.enabled = getattr(settings, "NPLUS1_DETECT_DUPLICATE_QUERIES", False)
+        if not self.enabled:
+            return
+        self.counts = defaultdict(int)
+        self.threshold = getattr(settings, "NPLUS1_DUPLICATE_QUERY_THRESHOLD", 2)
+        self._connection = connection
+        self._connection.execute_wrappers.append(self._wrapper)
+
+    def teardown(self) -> None:
+        if not self.enabled:
+            return
+        try:
+            self._connection.execute_wrappers.remove(self._wrapper)
+        except ValueError:
+            pass
+
+    def _wrapper(self, execute: Any, sql: str, params: Any, many: bool, context: Any) -> Any:
+        result = execute(sql, params, many, context)
+        if not many:
+            from django_nplus1.util import get_caller
+
+            fingerprint = _fingerprint_sql(sql)
+            caller = get_caller()
+            key = (fingerprint, *caller)
+            self.counts[key] += 1
+            if self.counts[key] == self.threshold:
+                short_sql = fingerprint[:120] + ("..." if len(fingerprint) > 120 else "")
+                message = DuplicateQueryMessage(_SQL, short_sql, caller=caller)
+                self.parent.notify(message)
+        return result
+
+
+LISTENERS: dict[str, type[Listener]] = {
+    "lazy_load": LazyListener,
+    "eager_load": EagerListener,
+    "get_loop": GetLoopListener,
+    "duplicate_query": DuplicateQueryListener,
+}

django_nplus1-0.1.0/django_nplus1/exceptions.py

@@ -0,0 +1,2 @@
+class NPlus1Error(Exception):
+    pass