django-nplus1 0.1.0a1__tar.gz

django_nplus1-0.1.0a1/.gitignore

@@ -0,0 +1,33 @@
+*.py[cod]
+__pycache__/
+.DS_Store
+*.sql
+*.bz2
+*~
+*.log
+*.json
+*.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

django_nplus1-0.1.0a1/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.0a1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: django-nplus1
+Version: 0.1.0a1
+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-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.
+
+Detects N+1 queries (lazy loading related objects in a loop) and unused eager loads (`select_related`/`prefetch_related` that are never accessed) in your Django application.
+
+Modernized fork of [nplusone](https://github.com/jmcarp/nplusone), stripped down to Django-only support with Python 3.12+ / Django 5.2+.
+
+## Features
+
+- **N+1 detection**: Warns when a related object is lazily loaded on an instance that was part of a bulk query
+- **Unused eager load detection**: Warns when `select_related` or `prefetch_related` results are never accessed
+- **Middleware**: Automatically monitors all requests
+- **pytest plugin**: `nplus1` fixture and `@pytest.mark.nplus1` marker for test-time detection
+- **Profiler**: Context manager for manual use in scripts or tests
+- **Whitelisting**: Ignore specific model/field combinations with wildcard support
+- **Zero dependencies**: Only requires Django (no blinker, no six)
+
+## Quick Start
+
+```bash
+pip install django-nplus1
+```
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...,
+    "django_nplus1",
+]
+
+MIDDLEWARE = [
+    ...,
+    "django_nplus1.NPlusOneMiddleware",
+]
+
+# Optional
+NPLUS1_RAISE = True  # Raise exceptions instead of logging (recommended for tests)
+```
+
+## Documentation
+
+Full documentation at [oliverhaas.github.io/django-nplus1](https://oliverhaas.github.io/django-nplus1/).
+
+## License
+
+MIT

django_nplus1-0.1.0a1/README.md

@@ -0,0 +1,47 @@
+# django-nplus1
+
+N+1 query detection for Django.
+
+Detects N+1 queries (lazy loading related objects in a loop) and unused eager loads (`select_related`/`prefetch_related` that are never accessed) in your Django application.
+
+Modernized fork of [nplusone](https://github.com/jmcarp/nplusone), stripped down to Django-only support with Python 3.12+ / Django 5.2+.
+
+## Features
+
+- **N+1 detection**: Warns when a related object is lazily loaded on an instance that was part of a bulk query
+- **Unused eager load detection**: Warns when `select_related` or `prefetch_related` results are never accessed
+- **Middleware**: Automatically monitors all requests
+- **pytest plugin**: `nplus1` fixture and `@pytest.mark.nplus1` marker for test-time detection
+- **Profiler**: Context manager for manual use in scripts or tests
+- **Whitelisting**: Ignore specific model/field combinations with wildcard support
+- **Zero dependencies**: Only requires Django (no blinker, no six)
+
+## Quick Start
+
+```bash
+pip install django-nplus1
+```
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...,
+    "django_nplus1",
+]
+
+MIDDLEWARE = [
+    ...,
+    "django_nplus1.NPlusOneMiddleware",
+]
+
+# Optional
+NPLUS1_RAISE = True  # Raise exceptions instead of logging (recommended for tests)
+```
+
+## Documentation
+
+Full documentation at [oliverhaas.github.io/django-nplus1](https://oliverhaas.github.io/django-nplus1/).
+
+## License
+
+MIT

django_nplus1-0.1.0a1/django_nplus1/__init__.py

@@ -0,0 +1,11 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from django_nplus1.middleware import NPlusOneMiddleware
+from django_nplus1.profiler import Profiler
+
+try:
+    __version__ = version("django-nplus1")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["NPlusOneMiddleware", "Profiler", "__version__"]

django_nplus1-0.1.0a1/django_nplus1/apps.py

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

django_nplus1-0.1.0a1/django_nplus1/detect.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import fnmatch
+from collections import defaultdict
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import 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.field == 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
+
+
+class Message:
+    label: str = ""
+    formatter: str = ""
+
+    def __init__(self, model: type, field: str) -> None:
+        self.model = model
+        self.field = field
+
+    @property
+    def message(self) -> str:
+        return self.formatter.format(
+            label=self.label,
+            model=self.model.__name__,
+            field=self.field,
+        )
+
+    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 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]
+
+    def setup(self) -> None:
+        from django_nplus1 import signals
+
+        self.loaded = set()
+        self.ignore = set()
+        signals.connect(signals.LOAD, self.handle_load, sender=signals.get_worker())
+        signals.connect(signals.IGNORE_LOAD, self.handle_ignore, sender=signals.get_worker())
+        signals.connect(signals.LAZY_LOAD, self.handle_lazy, sender=signals.get_worker())
+
+    def teardown(self) -> None:
+        from django_nplus1 import signals
+
+        signals.disconnect(signals.LOAD, self.handle_load, sender=signals.get_worker())
+        signals.disconnect(signals.IGNORE_LOAD, self.handle_ignore, sender=signals.get_worker())
+        signals.disconnect(signals.LAZY_LOAD, self.handle_lazy, sender=signals.get_worker())
+
+    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:
+            message = LazyLoadMessage(model, field)
+            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, sender=signals.get_worker())
+
+    def teardown(self) -> None:
+        from django_nplus1 import signals
+
+        self.log_eager()
+        signals.disconnect(signals.EAGER_LOAD, self.handle_eager, sender=signals.get_worker())
+        signals.disconnect(signals.TOUCH, self.handle_touch, sender=signals.get_worker())
+
+    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:
+        from django_nplus1 import signals
+
+        self.tracker.track(*parser(args, kwargs, context))
+        signals.connect(signals.TOUCH, self.handle_touch, sender=signals.get_worker())
+
+    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]
+
+
+LISTENERS: dict[str, type[Listener]] = {
+    "lazy_load": LazyListener,
+    "eager_load": EagerListener,
+}

django_nplus1-0.1.0a1/django_nplus1/exceptions.py

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

django_nplus1-0.1.0a1/django_nplus1/middleware.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import fnmatch
+import weakref
+from typing import TYPE_CHECKING, Any
+
+from django.conf import settings
+
+from django_nplus1 import notifiers
+from django_nplus1.detect import LISTENERS, Message, Rule
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest, HttpResponse
+
+    from django_nplus1.detect import Listener
+
+
+class DjangoRule(Rule):
+    def match_model(self, model: type) -> bool:
+        if self.model is model:
+            return True
+        if isinstance(self.model, str):
+            return fnmatch.fnmatch(
+                f"{model._meta.app_label}.{model.__name__}",  # type: ignore[attr-defined]
+                self.model,
+            )
+        return False
+
+
+class NPlusOneMiddleware:
+    def __init__(self, get_response: Any) -> None:
+        self.get_response = get_response
+        self._listeners: weakref.WeakKeyDictionary[HttpRequest, dict[str, Listener]] = weakref.WeakKeyDictionary()
+        self._notifiers: list[notifiers.Notifier] = []
+        self._whitelist: list[DjangoRule] = []
+
+    def _load_config(self) -> None:
+        config = dict(vars(settings._wrapped))  # type: ignore[misc]
+        self._notifiers = notifiers.init(config)
+        self._whitelist = [DjangoRule(**item) for item in getattr(settings, "NPLUS1_WHITELIST", [])]
+
+    def __call__(self, request: HttpRequest) -> HttpResponse:
+        self._load_config()
+        self._listeners[request] = {}
+        for name, listener_type in LISTENERS.items():
+            self._listeners[request][name] = listener_type(self)
+            self._listeners[request][name].setup()
+        try:
+            response = self.get_response(request)
+        finally:
+            for name in list(LISTENERS.keys()):
+                listener = self._listeners.get(request, {}).pop(name, None)
+                if listener:
+                    listener.teardown()
+        return response
+
+    def notify(self, message: Message) -> None:
+        if not message.match(self._whitelist):
+            for notifier in self._notifiers:
+                notifier.notify(message)

django_nplus1-0.1.0a1/django_nplus1/notifiers.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from django_nplus1.exceptions import NPlusOneError
+
+if TYPE_CHECKING:
+    from django_nplus1.detect import Message
+
+
+class Notifier:
+    CONFIG_KEY: str | None = None
+    ENABLED_DEFAULT: bool = False
+
+    @classmethod
+    def is_enabled(cls, config: dict[str, Any]) -> bool:
+        if cls.CONFIG_KEY is None:
+            return cls.ENABLED_DEFAULT
+        if cls.CONFIG_KEY in config:
+            return bool(config[cls.CONFIG_KEY])
+        return cls.ENABLED_DEFAULT
+
+    def notify(self, message: Message) -> None:
+        pass
+
+
+class LogNotifier(Notifier):
+    CONFIG_KEY = "NPLUS1_LOG"
+    ENABLED_DEFAULT = True
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.logger: logging.Logger = config.get("NPLUS1_LOGGER", logging.getLogger("django_nplus1"))
+        self.level: int = config.get("NPLUS1_LOG_LEVEL", logging.WARNING)
+
+    def notify(self, message: Message) -> None:
+        self.logger.log(self.level, message.message)
+
+
+class ErrorNotifier(Notifier):
+    CONFIG_KEY = "NPLUS1_RAISE"
+    ENABLED_DEFAULT = False
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.error: type[Exception] = config.get("NPLUS1_ERROR", NPlusOneError)
+
+    def notify(self, message: Message) -> None:
+        raise self.error(message.message)
+
+
+def init(config: dict[str, Any]) -> list[Notifier]:
+    return [notifier_cls(config) for notifier_cls in (LogNotifier, ErrorNotifier) if notifier_cls.is_enabled(config)]

django_nplus1-0.1.0a1/django_nplus1/patch.py

@@ -0,0 +1,386 @@
+from __future__ import annotations
+
+import copy
+import functools
+import importlib
+import threading
+from typing import Any
+
+from django.db.models import Model, query
+from django.db.models.fields.related_descriptors import (
+    ForwardManyToOneDescriptor,
+    ReverseOneToOneDescriptor,
+    create_forward_many_to_many_manager,
+    create_reverse_many_to_one_manager,
+)
+
+from django_nplus1 import signals
+
+
+def get_worker() -> str:
+    return str(threading.current_thread().ident)
+
+
+def to_key(instance: Model) -> str:
+    return f"{type(instance).__name__}:{instance.pk}"
+
+
+def _patch(original: Any, patched: Any) -> None:
+    module = importlib.import_module(original.__module__)
+    setattr(module, original.__name__, patched)
+
+
+def signalify_queryset(
+    func: Any,
+    parser: Any = None,
+    **context: Any,
+) -> Any:
+    @functools.wraps(func)
+    def wrapped(*args: Any, **kwargs: Any) -> Any:
+        queryset = func(*args, **kwargs)
+        ctx = copy.copy(context)
+        ctx["args"] = context.get("args", args)
+        ctx["kwargs"] = context.get("kwargs", kwargs)
+        queryset._clone = signalify_queryset(queryset._clone, parser=parser, **ctx)
+        queryset._fetch_all = signalify_fetch_all(queryset, parser=parser, **ctx)
+        queryset._context = ctx
+        return queryset
+
+    return wrapped
+
+
+def signalify_fetch_all(queryset: Any, parser: Any = None, **context: Any) -> Any:
+    func = queryset._fetch_all
+
+    @functools.wraps(func)
+    def wrapped(*args: Any, **kwargs: Any) -> Any:
+        if queryset._result_cache is None:
+            signals.send(
+                signals.LAZY_LOAD,
+                sender=get_worker(),
+                args=args,
+                kwargs=kwargs,
+                ret=None,
+                context=context,
+                parser=parser,
+            )
+        return func(*args, **kwargs)
+
+    return wrapped
+
+
+def get_related_name(model: type[Model]) -> str:
+    return f"{model._meta.model_name}_set"
+
+
+def parse_field(field: Any) -> tuple[type[Model], str]:
+    related_model = field.related_model
+    name = field.remote_field.name or get_related_name(field.related_model)
+    return related_model, name
+
+
+def parse_reverse_field(field: Any) -> tuple[type[Model], str]:
+    return field.model, field.name
+
+
+def parse_related(context: dict[str, Any]) -> tuple[type[Model], str]:
+    field = context["rel_field"]
+    model = field.related_model
+    related_name = field.remote_field.related_name
+    related_model = context["rel_model"]
+    return parse_related_parts(model, related_name, related_model)
+
+
+def parse_related_parts(
+    model: type[Model], related_name: str | None, related_model: type[Model]
+) -> tuple[type[Model], str]:
+    return (
+        model,
+        related_name or get_related_name(related_model),
+    )
+
+
+def parse_reverse_one_to_one_queryset(
+    args: Any,
+    kwargs: Any,
+    context: dict[str, Any],
+) -> tuple[type[Model], str, str]:
+    descriptor = context["args"][0]
+    field = descriptor.related.field
+    model, name = parse_field(field)
+    instance = context["kwargs"]["instance"]
+    return model, to_key(instance), name
+
+
+def parse_forward_many_to_one_queryset(
+    args: Any,
+    kwargs: Any,
+    context: dict[str, Any],
+) -> tuple[type[Model], str, str]:
+    descriptor = context["args"][0]
+    instance = context["kwargs"]["instance"]
+    return descriptor.field.model, to_key(instance), descriptor.field.name
+
+
+def parse_many_related_queryset(
+    args: Any,
+    kwargs: Any,
+    context: dict[str, Any],
+) -> tuple[type[Model], str, str]:
+    rel = context["rel"]
+    manager = context["args"][0]
+    model = manager.instance.__class__
+    related_model = manager.target_field.related_model
+    field = manager.prefetch_cache_name if rel.related_name else None
+    return (
+        model,
+        to_key(manager.instance),
+        field or get_related_name(related_model),
+    )
+
+
+def parse_foreign_related_queryset(
+    args: Any,
+    kwargs: Any,
+    context: dict[str, Any],
+) -> tuple[type[Model], str, str]:
+    model, name = parse_related(context)
+    descriptor = context["args"][0]
+    return model, to_key(descriptor.instance), name
+
+
+# Suppress lazy_load signals during prefetch_one_level
+query.prefetch_one_level = signals.designalify(  # type: ignore[attr-defined]
+    signals.LAZY_LOAD,
+    query.prefetch_one_level,  # type: ignore[attr-defined]
+)
+
+
+def parse_get(
+    args: Any,
+    kwargs: Any,
+    context: dict[str, Any],
+    ret: Any,
+) -> list[str]:
+    return [to_key(ret)] if isinstance(ret, Model) else []
+
+
+# Ignore records loaded during `get`
+query.QuerySet.get = signals.signalify(  # type: ignore[method-assign]
+    signals.IGNORE_LOAD,
+    query.QuerySet.get,
+    parser=parse_get,
+)
+
+# Patch descriptor get_queryset methods
+ReverseOneToOneDescriptor.get_queryset = signalify_queryset(  # type: ignore[method-assign]
+    ReverseOneToOneDescriptor.get_queryset,
+    parser=parse_reverse_one_to_one_queryset,
+)
+ForwardManyToOneDescriptor.get_queryset = signalify_queryset(  # type: ignore[method-assign]
+    ForwardManyToOneDescriptor.get_queryset,
+    parser=parse_forward_many_to_one_queryset,
+)
+
+
+def _create_forward_many_to_many_manager(superclass: Any, rel: Any, **kwargs: Any) -> Any:
+    manager = create_forward_many_to_many_manager(superclass, rel, **kwargs)
+    manager.get_queryset = signalify_queryset(  # type: ignore[method-assign]
+        manager.get_queryset,
+        parser=parse_many_related_queryset,
+        rel=rel,
+        rel_field=rel.field,
+        rel_model=rel.related_model,
+    )
+    return manager
+
+
+_patch(create_forward_many_to_many_manager, _create_forward_many_to_many_manager)
+
+
+def _create_reverse_many_to_one_manager(superclass: Any, rel: Any) -> Any:
+    manager = create_reverse_many_to_one_manager(superclass, rel)
+    manager.get_queryset = signalify_queryset(  # type: ignore[method-assign]
+        manager.get_queryset,
+        parser=parse_foreign_related_queryset,
+        rel_field=rel.field,
+        rel_model=rel.related_model,
+    )
+    return manager
+
+
+_patch(create_reverse_many_to_one_manager, _create_reverse_many_to_one_manager)
+
+
+def parse_forward_many_to_one_get(
+    args: Any,
+    kwargs: Any,
+    context: dict[str, Any],
+) -> tuple[type[Model], str, list[str]] | None:
+    descriptor, instance, *_ = args
+    if instance is None:
+        return None
+    field, model = parse_reverse_field(descriptor.field)
+    return field, model, [to_key(instance)]
+
+
+ForwardManyToOneDescriptor.__get__ = signals.signalify(  # type: ignore[method-assign]
+    signals.TOUCH,
+    ForwardManyToOneDescriptor.__get__,
+    parser=parse_forward_many_to_one_get,
+)
+
+
+def parse_reverse_one_to_one_get(
+    args: Any,
+    kwargs: Any,
+    context: dict[str, Any],
+) -> tuple[type[Model], str, list[str]] | None:
+    descriptor, instance = args[:2]
+    if instance is None:
+        return None
+    model, field = parse_field(descriptor.related.field)
+    return model, field, [to_key(instance)]
+
+
+ReverseOneToOneDescriptor.__get__ = signals.signalify(  # type: ignore[method-assign]
+    signals.TOUCH,
+    ReverseOneToOneDescriptor.__get__,
+    parser=parse_reverse_one_to_one_get,
+)
+
+
+def parse_fetch_all(
+    args: Any,
+    kwargs: Any,
+    context: dict[str, Any],
+) -> tuple[type[Model], str, list[str]] | None:
+    self = args[0]
+    if hasattr(self, "_context"):
+        manager = self._context["args"][0]
+        instance = manager.instance
+        if manager.__class__.__name__ == "ManyRelatedManager":
+            return (
+                instance.__class__,
+                parse_manager_field(manager, self._context["rel"]),
+                [to_key(instance)],
+            )
+        model, field = parse_related(self._context)
+        return model, field, [to_key(instance)]
+    return None
+
+
+def parse_manager_field(manager: Any, rel: Any) -> str:
+    if manager.reverse:
+        return rel.related_name or get_related_name(rel.related_model)
+    return rel.field.name or get_related_name(rel.model)
+
+
+def parse_load(
+    args: Any,
+    kwargs: Any,
+    context: dict[str, Any],
+    ret: Any,
+) -> list[str]:
+    return [to_key(row) for row in ret if isinstance(row, Model)]
+
+
+def is_single(low: int, high: int | None) -> bool:
+    return high is not None and high - low == 1
+
+
+# Patch _fetch_all to emit load/ignore_load and touch signals
+_original_fetch_all = query.QuerySet._fetch_all
+
+
+def _fetch_all(self: Any) -> None:
+    if self._prefetch_done:
+        signals.send(
+            signals.TOUCH,
+            sender=get_worker(),
+            args=(self,),
+            parser=parse_fetch_all,
+        )
+    _original_fetch_all(self)
+    signal = signals.IGNORE_LOAD if is_single(self.query.low_mark, self.query.high_mark) else signals.LOAD
+    signals.send(
+        signal,
+        sender=get_worker(),
+        args=(self,),
+        ret=self._result_cache,
+        parser=parse_load,
+    )
+
+
+query.QuerySet._fetch_all = _fetch_all  # type: ignore[method-assign]
+
+
+# Patch RelatedPopulator.__init__ to capture args for eager load parsing
+_original_related_populator_init = query.RelatedPopulator.__init__  # type: ignore[attr-defined]
+
+
+def _related_populator_init(self: Any, *args: Any, **kwargs: Any) -> None:
+    _original_related_populator_init(self, *args, **kwargs)
+    self.__nplus1__ = {"args": args, "kwargs": kwargs}
+
+
+query.RelatedPopulator.__init__ = _related_populator_init  # type: ignore[attr-defined]
+
+
+def parse_eager_select(
+    args: Any,
+    kwargs: Any,
+    context: dict[str, Any],
+) -> tuple[type[Model], str, list[str], int]:
+    populator = args[0]
+    instance = args[2]
+    meta = populator.__nplus1__
+    klass_info, select, *_ = meta["args"]
+    field = klass_info["field"]
+    model, name = parse_field(field) if instance._meta.model != field.model else parse_reverse_field(field)
+    return model, name, [to_key(instance)], id(select)
+
+
+# Emit eager_load on populating from select_related
+query.RelatedPopulator.populate = signals.signalify(  # type: ignore[attr-defined]
+    signals.EAGER_LOAD,
+    query.RelatedPopulator.populate,  # type: ignore[attr-defined]
+    parser=parse_eager_select,
+)
+
+
+def parse_eager_join(
+    args: Any,
+    kwargs: Any,
+    context: dict[str, Any],
+) -> tuple[type[Model], str, list[str], int]:
+    instances, _descriptor, fetcher, level = args
+    model = instances[0].__class__
+    field, _ = fetcher.get_current_to_attr(level)
+    keys = [to_key(instance) for instance in instances]
+    return model, field, keys, id(instances)
+
+
+# Emit eager_load on populating from prefetch_related
+query.prefetch_one_level = signals.signalify(  # type: ignore[attr-defined]
+    signals.EAGER_LOAD,
+    query.prefetch_one_level,  # type: ignore[attr-defined]
+    parser=parse_eager_join,
+)
+
+# Emit touch on indexing into prefetched QuerySet instances
+_original_getitem = query.QuerySet.__getitem__
+
+
+def _getitem_queryset(self: Any, index: Any) -> Any:
+    if self._prefetch_done:
+        signals.send(
+            signals.TOUCH,
+            sender=get_worker(),
+            args=(self,),
+            parser=parse_fetch_all,
+        )
+    return _original_getitem(self, index)
+
+
+query.QuerySet.__getitem__ = _getitem_queryset  # type: ignore[method-assign]

django_nplus1-0.1.0a1/django_nplus1/profiler.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from django_nplus1.detect import LISTENERS, Listener, Message, Rule
+from django_nplus1.exceptions import NPlusOneError
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+
+class Profiler:
+    def __init__(self, whitelist: list[dict[str, Any]] | None = None) -> None:
+        self.whitelist = [Rule(**item) for item in (whitelist or [])]
+        self._listeners: dict[str, Listener] = {}
+
+    def __enter__(self) -> Profiler:
+        for name, listener_type in LISTENERS.items():
+            self._listeners[name] = listener_type(self)
+            self._listeners[name].setup()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        for name in list(LISTENERS.keys()):
+            self._listeners.pop(name).teardown()
+
+    def notify(self, message: Message) -> None:
+        if not message.match(self.whitelist):
+            raise NPlusOneError(message.message)

django_nplus1-0.1.0a1/django_nplus1/pytest_plugin.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from django_nplus1.profiler import Profiler
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+
+def pytest_configure(config: Any) -> None:
+    config.addinivalue_line("markers", "nplus1: mark test to detect N+1 queries")
+
+
+@pytest.fixture
+def nplus1() -> Generator[Profiler]:
+    with Profiler() as p:
+        yield p
+
+
+@pytest.fixture(autouse=True)
+def auto_nplus1(request: pytest.FixtureRequest) -> Generator[None]:
+    marker = request.node.get_closest_marker("nplus1")
+    if marker:
+        with Profiler(whitelist=marker.kwargs.get("whitelist")):
+            yield
+    else:
+        yield

django_nplus1-0.1.0a1/django_nplus1/signals.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import contextlib
+import functools
+import threading
+from collections import defaultdict
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+_listeners: defaultdict[str, list[Callable[..., Any]]] = defaultdict(list)
+
+
+def get_worker() -> str:
+    return str(threading.current_thread().ident)
+
+
+def connect(signal_name: str, callback: Callable[..., Any], *, sender: str | None = None) -> None:
+    _listeners[_key(signal_name, sender)].append(callback)
+
+
+def disconnect(signal_name: str, callback: Callable[..., Any], *, sender: str | None = None) -> None:
+    key = _key(signal_name, sender)
+    try:
+        _listeners[key].remove(callback)
+    except ValueError:
+        pass
+
+
+def send(signal_name: str, *, sender: str | None = None, **kwargs: Any) -> None:
+    for callback in _listeners[_key(signal_name, sender)]:
+        callback(**kwargs)
+
+
+def _key(signal_name: str, sender: str | None) -> str:
+    if sender is None:
+        return signal_name
+    return f"{signal_name}:{sender}"
+
+
+def signalify(
+    signal_name: str, func: Callable[..., Any], *, parser: Callable[..., Any] | None = None
+) -> Callable[..., Any]:
+    @functools.wraps(func)
+    def wrapped(*args: Any, **kwargs: Any) -> Any:
+        ret = func(*args, **kwargs)
+        send(
+            signal_name,
+            sender=get_worker(),
+            args=args,
+            kwargs=kwargs,
+            ret=ret,
+            context={},
+            parser=parser,
+        )
+        return ret
+
+    return wrapped
+
+
+def designalify(signal_name: str, func: Callable[..., Any]) -> Callable[..., Any]:
+    @functools.wraps(func)
+    def wrapped(*args: Any, **kwargs: Any) -> Any:
+        with suppress(signal_name):
+            return func(*args, **kwargs)
+
+    return wrapped
+
+
+@contextlib.contextmanager
+def suppress(signal_name: str, sender: str | None = None) -> Generator[None]:
+    sender = sender or get_worker()
+    key = _key(signal_name, sender)
+    saved = _listeners[key][:]
+    _listeners[key].clear()
+    try:
+        yield
+    finally:
+        _listeners[key] = saved
+
+
+# Signal names as constants
+LOAD = "load"
+IGNORE_LOAD = "ignore_load"
+LAZY_LOAD = "lazy_load"
+EAGER_LOAD = "eager_load"
+TOUCH = "touch"

django_nplus1-0.1.0a1/pyproject.toml

@@ -0,0 +1,169 @@
+[project]
+name = "django-nplus1"
+version = "0.1.0a1"
+description = "N+1 query detection for Django"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+keywords = ["django", "n+1", "query", "detection", "performance", "orm"]
+authors = [{ name = "Oliver Haas", email = "ohaas@e1plus.de" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Web Environment",
+  "Framework :: Django",
+  "Framework :: Django :: 5.2",
+  "Framework :: Django :: 6.0",
+  "Framework :: Pytest",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Software Development :: Testing",
+  "Typing :: Typed",
+]
+dependencies = ["Django>=5.2,<7"]
+
+[project.entry-points.pytest11]
+nplus1 = "django_nplus1.pytest_plugin"
+
+[project.urls]
+Homepage = "https://github.com/oliverhaas/django-nplus1"
+Documentation = "https://oliverhaas.github.io/django-nplus1/"
+Repository = "https://github.com/oliverhaas/django-nplus1.git"
+Changelog = "https://oliverhaas.github.io/django-nplus1/reference/changelog/"
+
+[dependency-groups]
+dev = [
+  "django-stubs==5.2.9",
+  "mypy==1.19.1",
+  "pre-commit==4.5.1",
+  "pytest-cov==7.0.0",
+  "pytest-django==4.12.0",
+  "pytest-mock==3.15.1",
+  "pytest==9.0.2",
+  "ruff==0.15.5",
+  "ty==0.0.21",
+]
+docs = ["mkdocs==1.6.1", "mkdocs-material==9.7.3", "mike==2.1.3"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["django_nplus1"]
+
+[tool.hatch.build.targets.sdist]
+include = ["django_nplus1", "LICENSE", "README.md"]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 120
+fix = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  "ANN401",  # Any type is acceptable for generic ORM internals
+  "ARG001",  # Unused function args required by parser callback interface (args, kwargs, context, ret)
+  "ARG002",  # Unused method args required by signal callback interface
+  "COM812",  # Conflicts with ruff-format
+  "D",       # Docstrings - will add incrementally
+  "E501",    # Line length handled by config
+  "EM",      # Exception strings inline are fine
+  "FBT",     # Boolean params acceptable for config flags
+  "PERF203", # try/except in loop is fine for signal dispatch
+  "PLC0415", # Dynamic imports needed to avoid circular imports (detect.py -> signals.py)
+  "PLR0913", # Many args needed for signal parsers
+  "PLR2004", # Magic values like slice indices are acceptable
+  "PYI034",  # __enter__ returning Self vs concrete type is preference
+  "SIM105",  # try/except/pass is clearer than contextlib.suppress for single-line
+  "SLF001",  # Private member access needed for ORM monkeypatching
+  "TRY003",  # Long exception messages are helpful for debugging
+]
+
+[tool.ruff.lint.flake8-annotations]
+allow-star-arg-any = true
+suppress-none-returning = true
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+  "ANN",    # Type annotations not required in tests
+  "ARG",    # Unused arguments common in fixtures
+  "B018",   # Useless expressions are how we trigger lazy loads in tests
+  "DJ008",  # Test models don't need __str__
+  "E402",   # Import order in settings files
+  "F841",   # Unused variables okay in tests
+  "PT006",  # Parametrize tuple style is preference
+  "PT011",  # Broad pytest.raises okay in some tests
+  "PT012",  # Multi-statement pytest.raises needed for N+1 trigger patterns
+  "PT013",  # pytest import style is preference
+  "PT018",  # Compound assertions okay in tests
+  "RUF043", # Regex metacharacters in match= are intentional (dot in model.field)
+  "S101",   # assert in tests
+  "S105",   # Hardcoded passwords in test settings
+  "T201",   # print in test views is intentional
+]
+
+[tool.mypy]
+python_version = "3.12"
+plugins = ["mypy_django_plugin.main"]
+pretty = true
+show_error_codes = true
+show_error_context = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_unreachable = false
+
+[tool.django-stubs]
+django_settings_module = "tests.settings.base"
+
+[[tool.mypy.overrides]]
+module = "testapp.*"
+ignore_missing_imports = true
+
+[tool.ty.rules]
+invalid-method-override = "ignore"
+
+[tool.ty.environment]
+python-version = "3.13"
+
+[tool.ty.analysis]
+respect-type-ignore-comments = false
+
+[[tool.ty.overrides]]
+include = ["django_nplus1/patch.py", "django_nplus1/middleware.py"]
+
+[tool.ty.overrides.rules]
+# patch.py monkeypatches Django internals; middleware.py accesses _meta on type
+unresolved-attribute = "ignore"
+invalid-assignment = "ignore"
+
+[[tool.ty.overrides]]
+include = ["tests/**"]
+
+[tool.ty.overrides.rules]
+unresolved-attribute = "ignore"
+invalid-argument-type = "ignore"
+invalid-assignment = "ignore"
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "settings.base"
+addopts = "--cov=django_nplus1 --cov-report=term-missing --cov-report=xml --no-cov-on-fail"
+pythonpath = ["tests"]
+testpaths = ["tests"]
+xfail_strict = true
+
+[tool.coverage.run]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+precision = 2
+skip_covered = true