django-query-contract 0.1.0__py3-none-any.whl

django_query_contract/__init__.py

@@ -0,0 +1,23 @@
+"""A query-capture engine for Django, and a pytest plugin over it."""
+
+from django_query_contract.capture_stack import capture_stack
+from django_query_contract.format_capture_report import format_capture_report
+from django_query_contract.log_ceiling import LogCeiling
+from django_query_contract.normalise_sql import normalise_sql
+from django_query_contract.query_capture import QueryCapture
+from django_query_contract.query_log_ceiling_warning import QueryLogCeilingWarning
+from django_query_contract.query_record import QueryRecord
+from django_query_contract.stack_frame import StackFrame
+from django_query_contract.version import __version__
+
+__all__ = [
+    "LogCeiling",
+    "QueryCapture",
+    "QueryLogCeilingWarning",
+    "QueryRecord",
+    "StackFrame",
+    "__version__",
+    "capture_stack",
+    "format_capture_report",
+    "normalise_sql",
+]

django_query_contract/capture_stack.py

@@ -0,0 +1,64 @@
+"""Walk the live call stack into plain frame records."""
+
+from __future__ import annotations
+
+import inspect
+import os
+
+from django_query_contract.stack_frame import StackFrame
+
+# The directory this package occupies. Frames inside it are dropped, so a caller
+# never sees the capture machinery between itself and the query -- including the
+# frame of this function. Computed once at import: it cannot change, and doing it
+# per query would cost a path resolution on every execution.
+_PACKAGE_ROOT = os.path.dirname(os.path.abspath(__file__)) + os.sep
+
+
+def capture_stack(depth: int) -> tuple[tuple[StackFrame, ...], bool]:
+    """Return the innermost ``depth`` frames outside this package, and whether more existed.
+
+    Ordered outermost-first, the way a traceback reads. The *innermost* frames
+    are the ones kept when the stack is deeper than ``depth``, because those are
+    where the information is: between a cursor execution and the test function
+    sit twenty-odd Django frames, and the call site this package exists to name
+    is just outside them. Truncating from the other end would drop it.
+
+    The boolean is the second half of that bargain. A truncated stack can hide
+    the call site entirely, and this package's whole argument is that a
+    measurement which quietly stops being true is worse than one that refuses --
+    so truncation is reported rather than absorbed.
+
+    Returns:
+        The frames and a flag that is ``True`` when at least one more frame was
+        available beyond ``depth``.
+    """
+    frame = inspect.currentframe()
+    if frame is None:
+        # Python implementations are not required to support frame
+        # introspection, and an interpreter that declines returns None here
+        # rather than raising. Every other face of this capture still works with
+        # an empty stack, so this degrades to "no call site" instead of failing
+        # a suite that was only asking for a query count.
+        return (), False
+
+    collected: list[StackFrame] = []
+    truncated = False
+    current = frame.f_back
+    while current is not None:
+        code = current.f_code
+        filename = code.co_filename
+        if not filename.startswith(_PACKAGE_ROOT):
+            if len(collected) == depth:
+                truncated = True
+                break
+            collected.append(
+                StackFrame(
+                    filename=filename,
+                    lineno=current.f_lineno,
+                    function=code.co_name,
+                )
+            )
+        current = current.f_back
+
+    collected.reverse()
+    return tuple(collected), truncated

django_query_contract/format_capture_report.py

@@ -0,0 +1,128 @@
+"""Turn a capture into the paragraph a reader needs under a failed assertion."""
+
+from __future__ import annotations
+
+import os
+
+from django_query_contract.query_capture import QueryCapture
+from django_query_contract.query_record import QueryRecord
+
+
+def format_capture_report(
+    capture: QueryCapture,
+    *,
+    max_shapes: int = 5,
+    max_sql: int = 160,
+) -> str:
+    """Describe what a capture saw, ordered by what repeated most.
+
+    This is the diagnosis half of the bargain with ``django_assert_num_queries``:
+    that fixture builds its message inline and calls ``pytest.fail()``, so there
+    is no hook inside it and no reason to want one. The user keeps writing the
+    assertion they already write, and a failure gains this underneath it.
+
+    It reports repetition and does not name it. Deciding that a repeated
+    statement *is* an N+1 needs the call stack as well as the fingerprint, and
+    that judgement is a later milestone -- shipping it as a hint here would be
+    the heuristic four dead detectors died of.
+
+    Args:
+        capture: A closed capture.
+        max_shapes: How many repeated shapes to list before summarising the rest.
+        max_sql: Where to cut a long statement. The record keeps the whole thing.
+
+    Returns:
+        The report, without a trailing newline. Empty when there is nothing to
+        say -- no statements and no ceiling crossed. There is deliberately no
+        early return for that case: an explicit guard here was provably dead,
+        because both halves below already produce nothing from nothing.
+    """
+    lines = _ceiling_lines(capture)
+    if capture.records:
+        if lines:
+            lines.append("")
+        lines.extend(_shape_lines(capture, max_shapes=max_shapes, max_sql=max_sql))
+    return "\n".join(lines)
+
+
+def _ceiling_lines(capture: QueryCapture) -> list[str]:
+    """The honest half: say when a count taken from Django's log is wrong."""
+    lines: list[str] = []
+    for ceiling in capture.exceeded_ceilings:
+        lines.append(
+            f"Query log ceiling exceeded on '{ceiling.alias}': "
+            f"{ceiling.executions} statements executed, but connection.queries_log holds at "
+            f"most {ceiling.limit} and already held {ceiling.log_length_at_enter}, so a "
+            f"CaptureQueriesContext over this block reports {ceiling.visible}."
+        )
+        lines.append(
+            "  Above that ceiling assertNumQueries and django_assert_num_queries under-report, "
+            "and with a full log they report zero for a block that ran queries."
+        )
+    return lines
+
+
+def _shape_lines(capture: QueryCapture, *, max_shapes: int, max_sql: int) -> list[str]:
+    """The repetition half: which shapes ran more than once, and from where."""
+    by_alias: dict[str, int] = {}
+    for record in capture.records:
+        by_alias[record.alias] = by_alias.get(record.alias, 0) + 1
+    counted = ", ".join(f"{count} on '{alias}'" for alias, count in by_alias.items())
+    lines = [f"{len(capture.records)} statements captured: {counted}."]
+
+    groups = sorted(
+        capture.by_fingerprint().items(),
+        # Descending by repeat count, then by first appearance so the order is
+        # total and the report does not reshuffle between two identical runs.
+        key=lambda item: (-len(item[1]), item[1][0].index),
+    )
+    repeated = [group for group in groups if len(group[1]) > 1]
+    once = len(groups) - len(repeated)
+
+    if repeated:
+        lines.append("")
+        lines.append("Repeated statement shapes:")
+        for fingerprint, records in repeated[:max_shapes]:
+            lines.extend(_group_lines(fingerprint, records, max_sql=max_sql))
+        if len(repeated) > max_shapes:
+            lines.append(f"  and {len(repeated) - max_shapes} more repeated shapes.")
+    if once:
+        lines.append(f"  {once} shape(s) ran once.")
+    return lines
+
+
+def _group_lines(fingerprint: str, records: tuple[QueryRecord, ...], *, max_sql: int) -> list[str]:
+    """One repeated shape: how often, where from, and which queries."""
+    indices = ", ".join(f"#{record.index}" for record in records[:8])
+    if len(records) > 8:
+        indices += ", ..."
+    lines = [f"  {len(records)} x  {indices}", f"       {_shorten(fingerprint, max_sql)}"]
+    # One call site per distinct site rather than one per query: a genuine N+1
+    # has one, and a shape reached from several places is worth seeing as such.
+    sites = {str(record.call_site) for record in records if record.call_site is not None}
+    if sites:
+        for site in sorted(sites):
+            lines.append(f"       from {_relative(site)}")
+    else:
+        lines.append("       from no frame outside Django (stack empty or truncated)")
+    return lines
+
+
+def _shorten(text: str, limit: int) -> str:
+    """Cut a statement to ``limit`` characters, saying that it was cut."""
+    if len(text) <= limit:
+        return text
+    return text[:limit] + " ... (truncated)"
+
+
+def _relative(site: str) -> str:
+    """Shorten a call site to a path relative to the working directory when it is under it.
+
+    Only when it is under it: ``os.path.relpath`` will happily walk out of the
+    tree with a row of ``..`` segments, which is longer than the absolute path
+    and harder to read.
+    """
+    root = os.getcwd() + os.sep
+    if site.startswith(root):
+        return site[len(root) :]
+    return site

django_query_contract/log_ceiling.py

@@ -0,0 +1,73 @@
+"""How much of a block Django's own query log could still see."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class LogCeiling:
+    """The arithmetic behind a query count that stops being true.
+
+    ``django.test.utils.CaptureQueriesContext`` -- which is what
+    ``assertNumQueries`` and pytest-django's ``django_assert_num_queries`` both
+    count with -- records ``len(connection.queries_log)`` on entry and on exit
+    and returns the slice between them. But ``queries_log`` is a
+    ``deque(maxlen=connection.queries_limit)``, 9000 by default, and once it
+    rotates those two absolute indices no longer point at what they did.
+
+    Measured against Django 6.1, with the count that context manager reports:
+
+    | Already in the log | Queries in the block | Reported |
+    | --- | --- | --- |
+    | 0 | 8999 | 8999 |
+    | 0 | 9001 | 9000 |
+    | 8990 | 100 | 10 |
+    | 9000 | 5 | 0 |
+
+    The last row is the one that matters: five real queries, a reported count of
+    zero, and ``django_assert_max_num_queries(1)`` passing. Django does emit a
+    ``UserWarning`` when the log is full, so it is not perfectly silent -- but a
+    warning in the summary beside a green test is not what a reader takes from a
+    passing assertion, and the regime this happens in, thousands of queries in
+    one block, is precisely the N+1-at-scale case worth catching.
+
+    The capture in this package counts executions through
+    ``connection.execute_wrapper``, which has no bound at all. This class is how
+    it says so instead of quietly being right where the other is wrong.
+    """
+
+    alias: str
+    """The Django connection alias these numbers describe."""
+
+    limit: int | None
+    """``connection.queries_limit``. ``None`` means the log is unbounded and there is no ceiling."""
+
+    log_length_at_enter: int
+    """``len(connection.queries_log)`` when the capture opened, itself capped at ``limit``."""
+
+    executions: int
+    """Statements this capture counted. Unbounded, and therefore the true number."""
+
+    @property
+    def headroom(self) -> int | None:
+        """How many more entries the log could hold when the capture opened.
+
+        ``None`` when the log is unbounded.
+        """
+        if self.limit is None:
+            return None
+        return max(self.limit - self.log_length_at_enter, 0)
+
+    @property
+    def visible(self) -> int:
+        """What a ``CaptureQueriesContext`` opened at the same moment would report."""
+        headroom = self.headroom
+        if headroom is None:
+            return self.executions
+        return min(self.executions, headroom)
+
+    @property
+    def exceeded(self) -> bool:
+        """``True`` when a count taken from Django's query log would be too low."""
+        return self.visible != self.executions

django_query_contract/normalise_sql.py

@@ -0,0 +1,90 @@
+"""Reduce a statement to the shape it shares with its repeats."""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+
+# Every rule below is here because a real Django execution needs it. They were
+# read off the wire -- an ``execute_wrapper`` over an ORM session on SQLite --
+# rather than imagined, and each one is named by the statement that produced it.
+
+# ``SAVEPOINT "s8384995712_x1"`` / ``RELEASE SAVEPOINT ...`` / ``ROLLBACK TO
+# SAVEPOINT ...``. The identifier carries the thread id and a per-connection
+# counter, so it is different for every savepoint and different again on the
+# next run. It is not a bound parameter -- there are no parameters on these
+# statements at all -- so a normaliser that only strips placeholders leaves
+# every nested ``atomic()`` block looking like a unique query shape.
+_SAVEPOINT = re.compile(r"(?i)(\bSAVEPOINT\s+)(\"[^\"]*\"|`[^`]*`|\[[^\]]*\]|[^\s;]+)")
+
+# Single-quoted literals, with SQL's doubled-quote escape. Django's own SQL is
+# fully parameterised, so these come from the escape hatches: ``.raw()``,
+# ``RawSQL``, ``.extra()``, a hand-written ``cursor.execute``, and migrations.
+_STRING_LITERAL = re.compile(r"'(?:[^']|'')*'")
+
+# Numeric literals in value position. The lookarounds are what keep this from
+# mangling identifiers: a digit preceded or followed by a word character or a
+# quote belongs to a name (``app_address2``, ``"s123_x1"``, ``col1``), while a
+# free-standing number is a value. Django inlines ``LIMIT`` and ``OFFSET``
+# rather than binding them, which is how a paginating loop -- as real an N+1 as
+# any other -- would otherwise present as a different shape on every page.
+_NUMERIC_LITERAL = re.compile(r"(?<![\w\"'`\].])\d+(?:\.\d+)?(?![\w\"'`\[.])")
+
+# A parenthesised run of placeholders collapses to one. ``IN (%s, %s, %s)`` is
+# what ``prefetch_related`` and ``pk__in`` emit, and its width is the size of the
+# data, not the shape of the query. The same rule handles a multi-row
+# ``INSERT ... VALUES (%s, %s), (%s, %s)`` from ``bulk_create``, which would
+# otherwise fingerprint differently for every batch size.
+_PLACEHOLDER_RUN = re.compile(r"\(\s*%s(?:\s*,\s*%s)+\s*\)")
+_PLACEHOLDER_GROUPS = re.compile(r"\(%s\)(?:\s*,\s*\(%s\))+")
+
+_WHITESPACE = re.compile(r"\s+")
+
+_PLACEHOLDER = "%s"
+
+
+# Measured on an ORM query of average length: the five passes below cost about
+# 5.9 microseconds, which was more than the call-stack walk and the single
+# largest part of capture. A cache is the obvious answer precisely because of
+# what this package is for -- a suite that repeats a statement is the case it
+# exists to find, so the hit rate is highest exactly where the cost is. Bounded
+# rather than unbounded because a wide ``IN`` list produces one distinct
+# statement per width, and an unbounded cache would grow with the data.
+@lru_cache(maxsize=2048)
+def normalise_sql(sql: str) -> str:
+    """Return the fingerprint of ``sql``: the part that repeats across executions.
+
+    Two executions with the same fingerprint ran the same statement with
+    different data. Paired with the call stack, that is the definition of an
+    N+1 -- which is why this is a small list of named, reversible-in-the-head
+    rules rather than a hash. Every one of them can be pointed at, argued with
+    and tested, and the record keeps the original SQL beside the fingerprint so
+    a report never has to be believed on the strength of the normaliser alone.
+
+    A real SQL parser was considered and does not fit, for three independent
+    reasons. The SQL that reaches ``execute_wrapper`` carries Django's ``%s``
+    placeholders -- the backend's own paramstyle is applied below the wrapper --
+    and ``%s`` is a syntax error to a PostgreSQL grammar, so a parser cannot
+    read the input at all without the parameters being substituted back in,
+    which is the opposite of what a fingerprint is for. It would also be
+    PostgreSQL-only in a package whose count and growth assertions are meant to
+    work on any backend. And it costs roughly fifteen times a regex pass, per
+    query, in a suite that may run hundreds of thousands.
+
+    Args:
+        sql: The statement as handed to ``cursor.execute``.
+
+    Returns:
+        The normalised statement, with whitespace collapsed.
+    """
+    # String literals go first so that a statement which merely *mentions* a
+    # savepoint inside quotes is reduced to a placeholder before the savepoint
+    # rule can reach into it and leave an unbalanced quote behind.
+    normalised = _STRING_LITERAL.sub(_PLACEHOLDER, sql)
+    normalised = _SAVEPOINT.sub(r"\1<savepoint>", normalised)
+    normalised = _NUMERIC_LITERAL.sub(_PLACEHOLDER, normalised)
+    # Runs first, groups second: the group rule matches ``(%s)`` items, which is
+    # what a multi-column run becomes once the run rule has collapsed it.
+    normalised = _PLACEHOLDER_RUN.sub("(%s)", normalised)
+    normalised = _PLACEHOLDER_GROUPS.sub("(%s)", normalised)
+    return _WHITESPACE.sub(" ", normalised).strip()

django_query_contract/plugin.py

@@ -0,0 +1,129 @@
+"""The pytest face of the capture: a diagnosis, and never an assertion.
+
+This module is the one place in the package that is not a single exported
+symbol, because pytest finds hooks by name in a module and there is nowhere else
+to put them. It stays thin for that reason: every hook here decides *when* to
+capture and *when* to speak, and hands the actual work to a module that can be
+tested without a test runner in the loop.
+
+The design decision it implements is that this package ships **no count
+assertion**. ``django_assert_num_queries`` is the assertion -- it is typed, it
+already handles ``connection=`` and ``using=`` and a custom failure note, and it
+yields the captured queries. Wrapping it in a fixture of our own would
+re-implement all of that to add a paragraph. So the seam is: their assertion,
+our diagnosis, joined by a report section rather than by a wrapper.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Generator
+from typing import Any
+
+import pytest
+from django.conf import settings
+from pluggy import Result
+
+from django_query_contract.format_capture_report import format_capture_report
+from django_query_contract.query_capture import QueryCapture
+from django_query_contract.query_log_ceiling_warning import QueryLogCeilingWarning
+
+_CAPTURE_KEY = pytest.StashKey[QueryCapture]()
+
+# What pytest prints above the block, as ``---- django-query-contract ----``.
+_SECTION_NAME = "django-query-contract"
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Register the on/off switch and the stack-depth knob."""
+    parser.addini(
+        "query_contract",
+        "Capture queries around every test, so a failed query-count assertion "
+        "can be diagnosed and a block above Django's query-log ceiling can be reported.",
+        type="bool",
+        default=True,
+    )
+    # A string rather than pytest's ``int`` type, which only exists from 8.4.
+    parser.addini(
+        "query_contract_stack_depth",
+        "How many call-stack frames to keep per captured query.",
+        default="25",
+    )
+    parser.getgroup("django-query-contract").addoption(
+        "--no-query-contract",
+        action="store_true",
+        default=False,
+        help="Turn capture off for this run without editing the ini file.",
+    )
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_call(item: pytest.Item) -> Generator[None, Result[Any], None]:
+    """Capture around the test body, and say so when the block outran the log.
+
+    Around the *call* phase only. The assertion this diagnoses is written inside
+    the test, and widening capture to setup would fold every fixture's queries
+    into the diagnosis of a block that did not run them.
+
+    The ceiling is reported as a warning rather than a report section because
+    the case that matters is a test that **passed**: past the ceiling
+    ``django_assert_max_num_queries`` can be handed a zero for a block that ran
+    five queries, and a section on a passing test is only printed when somebody
+    already suspected something.
+    """
+    if not _enabled(item.config) or not settings.configured:
+        # Installed in a suite with no Django settings, or switched off. Both
+        # are ordinary, and neither is this plugin's business to complain about.
+        yield
+        return
+
+    capture = QueryCapture(stack_depth=_stack_depth(item.config))
+    item.stash[_CAPTURE_KEY] = capture
+    with capture:
+        yield
+    for ceiling in capture.exceeded_ceilings:
+        warnings.warn(
+            f"{item.nodeid}: {ceiling.executions} statements ran on connection "
+            f"'{ceiling.alias}', but connection.queries_log holds at most {ceiling.limit} "
+            f"and already held {ceiling.log_length_at_enter}. A query count taken from it "
+            f"-- which is what assertNumQueries and django_assert_num_queries both do -- "
+            f"reports {ceiling.visible} for this block.",
+            QueryLogCeilingWarning,
+            stacklevel=1,
+        )
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(
+    item: pytest.Item, call: pytest.CallInfo[None]
+) -> Generator[None, Result[Any], None]:
+    """Attach the diagnosis under a failed test.
+
+    ``_assert_num_queries`` builds its message inline and calls ``pytest.fail()``,
+    so there is no hook inside it to enrich. A report section reaches the same
+    place -- underneath the stock failure -- without owning the failure, which
+    means the user's assertion keeps working unchanged whether this package is
+    installed or not.
+    """
+    outcome = yield
+    report = outcome.get_result()
+    if report.when != "call" or not report.failed:
+        return
+    capture = item.stash.get(_CAPTURE_KEY, None)
+    if capture is None:
+        return
+    text = format_capture_report(capture)
+    if text:
+        report.sections.append((_SECTION_NAME, text))
+
+
+def _enabled(config: pytest.Config) -> bool:
+    """Whether to capture at all: the ini says normally, the flag says today."""
+    if config.getoption("--no-query-contract"):
+        return False
+    return bool(config.getini("query_contract"))
+
+
+def _stack_depth(config: pytest.Config) -> int:
+    """The configured frame budget per query."""
+    return int(config.getini("query_contract_stack_depth"))

django_query_contract/query_capture.py

@@ -0,0 +1,211 @@
+"""The capture engine: every execution, with its fingerprint and its call site."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from contextlib import ExitStack
+from typing import Any
+
+from django.db import connections
+
+from django_query_contract.capture_stack import capture_stack
+from django_query_contract.log_ceiling import LogCeiling
+from django_query_contract.normalise_sql import normalise_sql
+from django_query_contract.query_record import QueryRecord
+
+# Measured rather than guessed: six frames separate ``cursor.execute`` from the
+# line that iterated a queryset, so twenty-five leaves nineteen for whatever
+# application code sits above it -- a view, a service, a serializer -- and still
+# reaches the call site. The frames beyond that, under pytest, are the runner's
+# own and identical for every query in the suite. Depth is the one part of
+# capture whose cost scales, at roughly half a microsecond per frame, so the
+# default is the smallest number that keeps what a reader can act on.
+_DEFAULT_STACK_DEPTH = 25
+
+
+class QueryCapture:
+    """Record every statement executed inside a block, on one or more connections.
+
+    Capture rides on ``connection.execute_wrapper()``, which is Django's
+    documented hook and is what makes this compose rather than compete.
+    ``django_assert_num_queries`` counts through ``CaptureQueriesContext``, which
+    works by flipping ``force_debug_cursor`` and reading ``queries_log``; a
+    wrapper is a separate list on the connection and touches neither. So this
+    nests inside or around that assertion without changing what it sees --
+    a fact about the two mechanisms rather than a hope about them.
+
+    It also counts every execution, where ``queries_log`` is a bounded deque.
+    See ``LogCeiling`` for what that costs the other path and how this reports it.
+
+    ```python
+    with QueryCapture() as capture:
+        list(Author.objects.all())
+
+    for fingerprint, records in capture.by_fingerprint().items():
+        print(len(records), fingerprint, records[0].call_site)
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        using: str | Iterable[str] | None = None,
+        stack_depth: int = _DEFAULT_STACK_DEPTH,
+    ) -> None:
+        """
+        Args:
+            using: A connection alias, several aliases, or ``None`` for every
+                configured one. Every alias by default because the assertion
+                this diagnoses takes a ``using=`` of its own, and a diagnosis
+                that covered only ``default`` would go quiet on exactly the
+                multi-database test that most needs it.
+            stack_depth: How many frames to keep per query. Lower it if a suite
+                feels the cost; the walk is the only part of capture that is not
+                a handful of string operations.
+        """
+        if using is None:
+            self._using: tuple[str, ...] | None = None
+        elif isinstance(using, str):
+            self._using = (using,)
+        else:
+            self._using = tuple(using)
+        self._stack_depth = stack_depth
+        self._records: list[QueryRecord] = []
+        self._ceilings: tuple[LogCeiling, ...] = ()
+        self._entered: tuple[tuple[str, int, int | None], ...] = ()
+        self._wrappers = ExitStack()
+
+    def __enter__(self) -> QueryCapture:
+        # Reset rather than accumulate, so re-entering one instance measures one
+        # block. A capture that silently summed two blocks would be the same
+        # class of quiet wrongness this package exists to expose.
+        self._records = []
+        self._ceilings = ()
+        aliases = self._using if self._using is not None else tuple(connections)
+        entered: list[tuple[str, int, int | None]] = []
+        self._wrappers = ExitStack()
+        for alias in aliases:
+            connection = connections[alias]
+            entered.append((alias, len(connection.queries_log), connection.queries_limit))
+            self._wrappers.enter_context(connection.execute_wrapper(self._record))
+        self._entered = tuple(entered)
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        self._wrappers.close()
+        self._ceilings = tuple(
+            LogCeiling(
+                alias=alias,
+                limit=limit,
+                log_length_at_enter=log_length,
+                executions=sum(1 for record in self._records if record.alias == alias),
+            )
+            for alias, log_length, limit in self._entered
+        )
+
+    def _record(self, execute: Any, sql: Any, params: Any, many: bool, context: Any) -> Any:
+        """The ``execute_wrapper`` callable itself.
+
+        Recording happens before the statement runs and the result is returned
+        untouched, so a query that raises is still counted. A failing statement
+        is a statement that was executed, and a diagnosis that dropped it would
+        under-report the block that most needs explaining.
+        """
+        connection = context["connection"]
+        stack, truncated = capture_stack(self._stack_depth)
+        try:
+            param_count = None if params is None else len(params)
+        except TypeError:
+            # Django accepts an iterator of parameters and handles the same
+            # TypeError in its own debug logging. Sizing it here would consume
+            # it and the query would run with nothing bound.
+            param_count = None
+        self._records.append(
+            QueryRecord(
+                index=len(self._records),
+                sql=sql,
+                fingerprint=normalise_sql(sql),
+                alias=connection.alias,
+                vendor=connection.vendor,
+                many=many,
+                param_count=param_count,
+                stack=stack,
+                stack_truncated=truncated,
+            )
+        )
+        return execute(sql, params, many, context)
+
+    @property
+    def records(self) -> tuple[QueryRecord, ...]:
+        """Every execution, in order. A snapshot, so it is safe to read mid-block."""
+        return tuple(self._records)
+
+    @property
+    def ceilings(self) -> tuple[LogCeiling, ...]:
+        """One per captured connection, populated on exit."""
+        return self._ceilings
+
+    @property
+    def exceeded_ceilings(self) -> tuple[LogCeiling, ...]:
+        """The connections whose block ran past what Django's query log can hold."""
+        return tuple(ceiling for ceiling in self._ceilings if ceiling.exceeded)
+
+    def by_fingerprint(self) -> dict[str, tuple[QueryRecord, ...]]:
+        """Group the records by fingerprint, in the order each was first seen.
+
+        The grouping every face of this capture starts from. A group of more
+        than one is a repeated statement; whether it is an N+1 also depends on
+        the call stack, which the records carry.
+        """
+        grouped: dict[str, list[QueryRecord]] = {}
+        for record in self._records:
+            grouped.setdefault(record.fingerprint, []).append(record)
+        return {fingerprint: tuple(records) for fingerprint, records in grouped.items()}
+
+    def __len__(self) -> int:
+        return len(self._records)
+
+    def __iter__(self) -> Iterator[QueryRecord]:
+        return iter(tuple(self._records))
+
+    def __getitem__(self, index: int) -> QueryRecord:
+        return self._records[index]
+
+    @classmethod
+    def from_capture_context(cls, context: Any) -> QueryCapture:
+        """Build a capture from a ``django.test.utils.CaptureQueriesContext``.
+
+        This is the object ``django_assert_num_queries`` yields, so a caller
+        already holding one can be served without rewriting the test. What comes
+        back is honestly degraded, and the gaps are the argument for capturing
+        separately rather than a limitation to work around:
+
+        - **No call stacks.** That context records ``{"sql", "time"}`` per query
+          and nothing else, so there is no frame to recover. ``call_site`` is
+          ``None`` on every record.
+        - **No ceiling.** ``ceilings`` is empty, because a count taken from a
+          rotated deque cannot report how much it lost -- the dropped entries
+          are gone, and their number with them. This is the one thing that
+          cannot be reconstructed after the fact at any price.
+        - **No parameter counts**, and ``many`` is ``False`` throughout: the SQL
+          of an ``executemany`` arrives there already rewritten to
+          ``"N times: ..."``.
+
+        Args:
+            context: Anything with ``captured_queries`` and ``connection``.
+        """
+        capture = cls()
+        connection = context.connection
+        capture._records = [
+            QueryRecord(
+                index=index,
+                sql=query["sql"],
+                fingerprint=normalise_sql(query["sql"]),
+                alias=connection.alias,
+                vendor=connection.vendor,
+                many=False,
+                param_count=None,
+            )
+            for index, query in enumerate(context.captured_queries)
+        ]
+        return capture

django_query_contract/query_log_ceiling_warning.py

@@ -0,0 +1,19 @@
+"""The warning raised when a block outruns Django's query log."""
+
+from __future__ import annotations
+
+
+class QueryLogCeilingWarning(UserWarning):
+    """A block executed more statements than ``connection.queries_log`` can hold.
+
+    A warning rather than a failure, because this package asserts nothing: the
+    assertion belongs to ``django_assert_num_queries`` and this only says when
+    its arithmetic stopped being reliable. It is a warning rather than a report
+    section because the dangerous case is a test that **passed** -- five real
+    queries counted as zero -- and a section on a passing test is printed only
+    when someone asks for it.
+
+    Django emits a ``UserWarning`` of its own when the log is full, but it says
+    only that the log truncated; it does not say what the count should have been
+    or that an assertion just read a wrong number off it.
+    """

django_query_contract/query_record.py

@@ -0,0 +1,97 @@
+"""One database execution, as this package remembers it."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+import django
+
+from django_query_contract.stack_frame import StackFrame
+
+# Where Django itself lives. ``call_site`` walks outwards until it leaves this
+# directory, which is what turns twenty frames of queryset machinery into the
+# one line a reader can act on. Resolved once at import rather than per query.
+_DJANGO_ROOT = os.path.dirname(os.path.abspath(django.__file__)) + os.sep
+
+
+@dataclass(frozen=True, slots=True)
+class QueryRecord:
+    """A single statement, its fingerprint and the stack that emitted it.
+
+    This is the artifact the whole package is built around, and it is public and
+    documented from the first release on purpose: four separate faces read it --
+    the pytest plugin, a CI report, call-site attribution and a runtime budget
+    middleware -- and three of them are not written yet. A record kept private
+    until they are would grow a private accessor per face instead of a shape.
+
+    The contract in ``0.x`` is additive: fields may be added, never removed and
+    never given a new meaning. It is frozen at ``1.0``.
+
+    Two things are deliberately absent.
+
+    **No parameters.** Retaining them would pin every bound value for the length
+    of a capture -- a ``bulk_create`` of ten thousand rows arrives here as one
+    execution and ten thousand values -- and the runtime middleware face would
+    then be holding customer data in memory to answer a question about query
+    counts. ``param_count`` is what the diagnosis actually needs ("the ``IN``
+    list had five hundred entries"), and the plan face runs ``EXPLAIN`` at
+    execution time, where the parameters are still in hand.
+
+    **No duration.** This package's argument is that a performance assertion
+    mentioning a number of milliseconds is a flaky test with extra steps, and a
+    field invites the assertion. Timing a query is a profiler's job;
+    ``django-silk`` does it well and is deliberately out of scope.
+    """
+
+    index: int
+    """Position within the capture, counting from zero. Names a query in a report."""
+
+    sql: str
+    """The statement exactly as handed to the cursor, placeholders and all."""
+
+    fingerprint: str
+    """``sql`` reduced to the part that repeats. See ``normalise_sql``."""
+
+    alias: str
+    """The Django connection alias this ran on."""
+
+    vendor: str
+    """The backend's ``vendor`` string: ``sqlite``, ``postgresql``, ``mysql``, ``oracle``."""
+
+    many: bool
+    """``True`` when this arrived through ``executemany`` rather than ``execute``."""
+
+    param_count: int | None
+    """How many bindings were passed -- rows, for ``executemany``.
+
+    ``None`` when the parameters were not sized: ``None`` itself, as every
+    transaction control statement passes, or an iterator, which Django permits
+    and which cannot be measured without consuming it.
+    """
+
+    stack: tuple[StackFrame, ...] = field(default=())
+    """The call stack, outermost first. Empty when reconstructed from a source that had none."""
+
+    stack_truncated: bool = False
+    """``True`` when the stack was deeper than the capture's limit and outer frames were dropped."""
+
+    @property
+    def call_site(self) -> StackFrame | None:
+        """The innermost frame outside Django: the line that asked for this query.
+
+        ``None`` when the stack holds no such frame -- an empty stack, or one
+        truncated before it reached the caller. That is reported rather than
+        approximated with the innermost frame available, because "the query came
+        from ``django/db/models/query.py``" is true of every query and tells a
+        reader nothing.
+
+        Django is the only package skipped. Anything else in the stack -- a REST
+        framework, a factory library, a service layer -- did emit the query, and
+        deciding that some libraries are more interesting than others is the
+        kind of tuning this package exists without.
+        """
+        for frame in reversed(self.stack):
+            if not frame.filename.startswith(_DJANGO_ROOT):
+                return frame
+        return None

django_query_contract/stack_frame.py

@@ -0,0 +1,29 @@
+"""One frame of the call stack that emitted a query."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class StackFrame:
+    """Where a query came from, at one level of the call stack.
+
+    Deliberately three plain strings and an integer rather than a reference to a
+    live frame object: a captured stack outlives the call it describes, and
+    holding frames would keep every local variable of every ORM call alive for
+    the length of a test. It would also make the record unpickleable, which the
+    CI-report face needs it not to be.
+
+    The source line is not read either. ``traceback.extract_stack`` opens and
+    caches the file for every frame it formats, and this runs once per query in
+    a suite that may execute hundreds of thousands of them.
+    """
+
+    filename: str
+    lineno: int
+    function: str
+
+    def __str__(self) -> str:
+        """``path/to/file.py:31 in test_books`` -- one frame, one line."""
+        return f"{self.filename}:{self.lineno} in {self.function}"

django_query_contract/version.py

@@ -0,0 +1,7 @@
+"""The single source of truth for this package's version."""
+
+from __future__ import annotations
+
+__version__: str = "0.1.0"
+
+__all__ = ["__version__"]

django_query_contract-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: django-query-contract
+Version: 0.1.0
+Summary: A query-capture engine for Django, and a pytest plugin over it: normalised SQL fingerprints, call sites, and an honest report above Django's query-log ceiling.
+Project-URL: Homepage, https://github.com/Artui/django-query-contract
+Project-URL: Repository, https://github.com/Artui/django-query-contract
+Project-URL: Issues, https://github.com/Artui/django-query-contract/issues
+Author-email: Artur Veres <artur8118@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: django,n-plus-one,performance,pytest,query-count,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Description-Content-Type: text/markdown
+
+# django-query-contract
+
+[![CI](https://github.com/Artui/django-query-contract/workflows/tests/badge.svg)](https://github.com/Artui/django-query-contract/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/django-query-contract.svg)](https://pypi.org/project/django-query-contract/)
+[![Python versions](https://img.shields.io/pypi/pyversions/django-query-contract.svg)](https://pypi.org/project/django-query-contract/)
+[![Django versions](https://img.shields.io/pypi/djversions/django-query-contract.svg)](https://pypi.org/project/django-query-contract/)
+[![Docs](https://img.shields.io/badge/docs-artui.github.io-blue.svg)](https://artui.github.io/django-query-contract/)
+[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Artui/django-query-contract/gh-pages/coverage.json)](https://github.com/Artui/django-query-contract/actions/workflows/tests.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![License](https://img.shields.io/pypi/l/django-query-contract.svg)](LICENSE)
+
+A query-capture engine for Django, and a pytest plugin over it.
+
+Every statement is recorded with a normalised SQL fingerprint and the call stack
+that emitted it, through `connection.execute_wrapper()`. When a query-count
+assertion fails, the failure gains a paragraph saying which shape repeated and
+where it came from. When a block runs past the ceiling on Django's own query
+log, that is reported instead of papered over.
+
+## Install
+
+```bash
+pip install django-query-contract
+```
+
+The pytest plugin loads itself. There is nothing to add to `INSTALLED_APPS`, and
+no fixture to request.
+
+## It ships no count assertion, on purpose
+
+`django_assert_num_queries` is the assertion. It is typed, it handles
+`connection=` / `using=` and a custom failure note, and it yields the captured
+queries. Keep writing it:
+
+```python
+def test_listing_is_flat(django_assert_num_queries, authors):
+    with django_assert_num_queries(2):
+        render_author_list()
+```
+
+When it fails, the failure now carries a diagnosis underneath it:
+
+```
+------------------------------ django-query-contract ------------------------------
+13 statements captured: 13 on 'default'.
+
+Repeated statement shapes:
+  11 x  #1, #2, #3, #4, #5, #6, #7, #8, ...
+       SELECT "shop_book"."id", "shop_book"."author_id", "shop_book"."title" FROM "shop_book" WHERE "shop_book"."author_id" = %s
+       from shop/views.py:16 in render_author_list
+  2 shape(s) ran once.
+```
+
+## The ceiling nobody mentions
+
+`assertNumQueries` and `django_assert_num_queries` both count through
+`CaptureQueriesContext`, which slices `connection.queries` between two absolute
+indices. That log is a `deque(maxlen=connection.queries_limit)` -- 9000 by
+default -- so once it rotates the indices no longer point at what they did.
+Measured against Django 6.1:
+
+| Already in the log | Queries in the block | Reported |
+| --- | --- | --- |
+| 0 | 8999 | 8999 |
+| 0 | 9001 | 9000 |
+| 8990 | 100 | 10 |
+| 9000 | 5 | **0** |
+
+The last row is a passing `django_assert_max_num_queries(1)` around five real
+queries, and the regime it happens in -- thousands of statements in one block --
+is exactly the N+1-at-scale case worth catching.
+
+Capture here rides on `execute_wrapper`, which has no bound, so this package
+raises a `QueryLogCeilingWarning` naming the test, the real count and the number
+the assertion was handed.
+
+## Reading the capture directly
+
+```python
+from django_query_contract import QueryCapture
+
+with QueryCapture() as capture:
+    render_author_list()
+
+for fingerprint, records in capture.by_fingerprint().items():
+    if len(records) > 1:
+        print(len(records), records[0].call_site, fingerprint)
+```
+
+A `QueryRecord` carries the statement, its fingerprint, the connection alias and
+vendor, the parameter count and the call stack. It carries **no parameters** --
+a `bulk_create` is one execution and ten thousand values, and a runtime reader
+of this capture has no business holding them -- and **no duration**, because a
+performance assertion that mentions milliseconds is a flaky test with extra
+steps.
+
+`QueryCapture.from_capture_context(...)` builds one from the
+`CaptureQueriesContext` that `django_assert_num_queries` yields. It is honestly
+degraded: no call stacks, no parameter counts, and no ceiling, because a count
+taken from a rotated deque cannot report what it lost.
+
+## Where the capture stops
+
+`execute_wrapper` wraps Django's cursor wrapper, so it sees `execute` and
+`executemany` and nothing else. A statement issued on the raw driver connection
+is invisible, and so is a driver API that is neither -- psycopg 3's
+`cursor.copy()`, for instance. Django's own query log has the same blind spot,
+so the two agree, and there is a test that pins it rather than a note that
+assumes it.
+
+## Turning it off
+
+```ini
+[pytest]
+query_contract = false
+query_contract_stack_depth = 25
+```
+
+or `--no-query-contract` for one run.
+
+## Status
+
+Early. The capture engine and the pytest diagnosis. N+1 by
+(call stack, fingerprint), the growth assertion, call-site attribution and plan
+capture come next.
+
+Full documentation: <https://artui.github.io/django-query-contract/>
+
+## License
+
+MIT

django_query_contract-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+django_query_contract/__init__.py,sha256=SYSRrQ-Vc1LfVCzhHgnzXixxWiWpls0gT5Gk74rgw4s,854
+django_query_contract/capture_stack.py,sha256=K4Nz23Z_WOsfmcs1_shfvXs54KO08eKLxDLFz49SEh4,2618
+django_query_contract/format_capture_report.py,sha256=BrzP2mdlg6MBpQjNd6MJj9DeSWuvp-7XnORe10Ops6c,5381
+django_query_contract/log_ceiling.py,sha256=vUhVKdiQwzCYob7K00CoQePjrsRScPzdFfC8OO0Swcs,2834
+django_query_contract/normalise_sql.py,sha256=8QRxdrphLqu6IjpYSNQ3aoNipzd_C4guoga9vVP28Hs,5009
+django_query_contract/plugin.py,sha256=yWrgxX45hL_cS5LO9tt8JNdJYxXTF5cg4cu2o46L5NQ,5281
+django_query_contract/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_query_contract/query_capture.py,sha256=4KZ2IzquCyKHg4RWNMW0oRDynGEi2PTw7WJkw59CmR8,9107
+django_query_contract/query_log_ceiling_warning.py,sha256=Mqfp0OqbsrgyHoR66ans-B2JU5kg3UEiZbGcuNjPAP4,883
+django_query_contract/query_record.py,sha256=m-XYekmuZawk0pegH7URRQ_xnFGwKv99cjSDC2ud_N4,4186
+django_query_contract/stack_frame.py,sha256=BOvktfJlvzY9Lg2u8rpg2Pe_PHn8ji889NfXwQs_LMU,1056
+django_query_contract/version.py,sha256=IGt2-6r71nTeUfPEK_x1lNeMEBrz0uYGAfUvfX0lTVs,152
+django_query_contract-0.1.0.dist-info/METADATA,sha256=zKn_v9y5tqEX8tH0HS_-rqbV7RteIpuDvCkbTn8ptow,6997
+django_query_contract-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+django_query_contract-0.1.0.dist-info/entry_points.txt,sha256=HNBzVPUMK5O_qcJ8aJVke5EaP8EzozGXTFlLuluP3vA,64
+django_query_contract-0.1.0.dist-info/licenses/LICENSE,sha256=0rCDnUPa87Fm67SxYMrdqEdLV6UiMENH6NCPLZ_KT5M,1068
+django_query_contract-0.1.0.dist-info/RECORD,,

django_query_contract-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

django_query_contract-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+django_query_contract = django_query_contract.plugin

django_query_contract-0.1.0.dist-info/licenses/LICENSE

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