pytest-querycount 0.3.0__py3-none-any.whl

pytest_querycount/report.py

@@ -0,0 +1,64 @@
+"""The end-of-session table.
+
+This is the part people leave switched on. A budget tells you when you crossed a
+line you drew; the report tells you where the lines should go.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class TestStats:
+    nodeid: str
+    count: int
+    duration: float
+    worst_duplicate: int
+    worst_sql: str | None = None
+
+
+def build(stats: dict[str, TestStats], top: int = 10) -> list[str]:
+    """Render the summary as terminal lines. Empty when nothing was recorded."""
+    recorded = [entry for entry in stats.values() if entry.count]
+    if not recorded:
+        return []
+
+    recorded.sort(key=lambda entry: (entry.count, entry.duration), reverse=True)
+    shown = recorded[:top]
+
+    id_width = max(len(entry.nodeid) for entry in shown)
+    id_width = min(max(id_width, 4), 70)
+
+    lines = [
+        f"{'queries':>7}  {'time':>9}  {'dupes':>5}  test",
+        f"{'-' * 7}  {'-' * 9}  {'-' * 5}  {'-' * id_width}",
+    ]
+    for entry in shown:
+        dupes = str(entry.worst_duplicate) if entry.worst_duplicate > 1 else "-"
+        flag = "!" if entry.worst_duplicate > 1 else " "
+        lines.append(
+            f"{entry.count:>7}  {entry.duration * 1000:>7.1f}ms  "
+            f"{dupes:>4}{flag}  {_trim(entry.nodeid, id_width)}"
+        )
+
+    total_queries = sum(entry.count for entry in recorded)
+    total_time = sum(entry.duration for entry in recorded)
+    hidden = len(recorded) - len(shown)
+    footer = f"{total_queries} queries in {total_time * 1000:.1f}ms across {len(recorded)} tests"
+    if hidden:
+        footer += f" ({hidden} more not shown, raise --querycount-top)"
+    lines += ["", footer]
+
+    flagged = [entry for entry in shown if entry.worst_duplicate > 1]
+    if flagged:
+        lines.append(
+            "! marks a repeated query shape -- add @pytest.mark.no_n_plus_one to see the detail."
+        )
+    return lines
+
+
+def _trim(text: str, width: int) -> str:
+    if len(text) <= width:
+        return text
+    return "…" + text[-(width - 1) :]

pytest_querycount-0.3.0.dist-info/METADATA

@@ -0,0 +1,336 @@
+Metadata-Version: 2.5
+Name: pytest-querycount
+Version: 0.3.0
+Summary: Fail your tests when they run too many SQL queries. Catch N+1 problems in CI, not in production.
+Project-URL: Homepage, https://github.com/ldavidsm/pytest-querycount
+Project-URL: Issues, https://github.com/ldavidsm/pytest-querycount/issues
+Project-URL: Changelog, https://github.com/ldavidsm/pytest-querycount/blob/main/CHANGELOG.md
+Author: Luis David Senra
+License: MIT License
+        
+        Copyright (c) 2026 Luis David Senra
+        
+        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: database,n+1,orm,performance,pytest,query-count,sql,sqlalchemy,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Topic :: Database
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pytest>=8.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: sqlalchemy>=2.0; extra == 'dev'
+Provides-Extra: postgresql
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgresql'
+Requires-Dist: sqlalchemy>=2.0; extra == 'postgresql'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# pytest-querycount
+
+[![CI](https://github.com/ldavidsm/pytest-querycount/actions/workflows/ci.yml/badge.svg)](https://github.com/ldavidsm/pytest-querycount/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pytest-querycount.svg)](https://pypi.org/project/pytest-querycount/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pytest-querycount.svg)](https://pypi.org/project/pytest-querycount/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Fail your tests when they run too many SQL queries.
+
+An endpoint that quietly grows from 2 queries to 200 does not break any test. It
+just gets slower, until one day it is slow enough to notice. This plugin turns
+that drift into a red test.
+
+```python
+@pytest.mark.max_queries(2)
+def test_billing_summary(db):
+    assert len(serialise(db)) == 12
+```
+
+Add a lazy-loaded relationship to that serialiser and the test fails on the next
+CI run, naming the repeated query and the line of your code that caused it.
+
+## Install
+
+```bash
+pip install "pytest-querycount[sqlalchemy]"
+```
+
+Requires Python 3.10+, pytest 8+, and SQLAlchemy 2.x. There is nothing to
+configure: the plugin instruments every engine your suite creates, sync or async.
+
+## What it gives you
+
+### A query budget
+
+```python
+@pytest.mark.max_queries(2)
+def test_billing_summary(db):
+    assert len(serialise(db)) == 12
+```
+
+When the serialiser loops, you get this -- real output, not an illustration:
+
+```
+_____________________________ test_billing_summary _____________________________
+
+E   TooManyQueriesError: test_billing_summary ran 13 queries, budget is 2 (11 over).
+
+    Repeated query shapes -- most likely where the extra queries come from:
+      12x  SELECT invoices.id, invoices.customer_id, invoices.cents FROM invoices WHERE ? = invoices.custome…
+          from test_billing.py:10 (12x)
+
+    13 queries in 0.1ms
+            1. [   0.02ms] SELECT customers.id, customers.email FROM customers
+                            from test_billing.py:11
+         2-13. [   0.06ms] 12x SELECT invoices.id, invoices.customer_id, invoices.cents FROM invoices WHERE …
+                            from test_billing.py:10
+```
+
+Three things to notice, because they are the reason this is a package and not a
+snippet:
+
+- **The diagnosis comes first.** `12x` on one query shape, before any listing.
+  In a CI log you get the culprit in the first three lines.
+- **`test_billing.py:10` is your code**, not a line inside SQLAlchemy. The
+  plugin walks up the stack past the ORM to find the line that actually caused
+  the query.
+- **The twelve identical queries print as one line.** Twelve copies of the same
+  SELECT tell you nothing that `12x` does not, and they would push the useful
+  lines off the screen.
+
+### N+1 detection without picking a number
+
+Sometimes you do not want to choose a budget, you just want to assert that
+nothing is looping.
+
+```python
+@pytest.mark.no_n_plus_one
+def test_billing_summary(db):
+    assert len(serialise(db)) == 12
+```
+
+This groups queries by *shape* -- `WHERE id = 42` and `WHERE id = 43` are the
+same shape -- and fails when one shape repeats. By default it looks only at
+SELECTs, since repeated `SAVEPOINT`s are just how transactions work.
+
+```python
+@pytest.mark.no_n_plus_one(threshold=5)             # tolerate up to 4 repeats
+@pytest.mark.no_n_plus_one(kinds=("select", "insert"))
+@pytest.mark.no_n_plus_one(kinds=None)              # consider every statement
+```
+
+### Missing indexes (PostgreSQL)
+
+```python
+@pytest.mark.no_seq_scan
+def test_customer_search(db):
+    assert len(find_by_city(db, "city3")) == 1
+```
+
+```
+_____________________________ test_customer_search _____________________________
+
+E   SeqScanError: test_customer_search ran 1 query that no index could serve.
+
+    PostgreSQL still chose a sequential scan with enable_seqscan disabled, which
+    means no index covers the filtered columns.
+
+      Seq Scan on "demo_customers"  Filter: ((city)::text = 'city3'::text)
+          try:  CREATE INDEX ON demo_customers (city);
+          from test_search.py:7
+          SELECT demo_customers.id, ... FROM demo_customers WHERE demo_customers.…
+```
+
+That table holds **eight rows**, and that matters more than it looks.
+
+The obvious way to write this check does not work. Failing on the presence of a
+`Seq Scan` is useless, because on a test database of twenty rows PostgreSQL picks
+a sequential scan *even when a perfect index exists* -- reading twenty rows is
+cheaper than descending a B-tree. So the plan alone cannot distinguish a missing
+index from a small table. And thresholding on table size, the usual next idea,
+means the check never fires on test data at all. Either way you get a check that
+lies to you.
+
+So this asks a different question: not "did it scan?" but "**could** it have used
+an index?". The plan is taken with `enable_seqscan` disabled, which makes the
+planner treat sequential scans as enormously expensive. If it still picks one, no
+index can serve that filter -- and that answer does not depend on data volume.
+The test suite for this feature runs against eight rows on purpose, to keep that
+claim honest.
+
+Excluding a table you read whole deliberately:
+
+```python
+@pytest.mark.no_seq_scan(ignore=("countries", "settings"))
+```
+
+Three things this is careful about:
+
+- The `EXPLAIN` runs on a raw DBAPI cursor, invisible to SQLAlchemy's events, so
+  it is never counted among your test's queries and cannot recurse.
+- It is wrapped in a savepoint, which both scopes the `enable_seqscan` change and
+  absorbs a failed `EXPLAIN` that would otherwise abort your test's transaction.
+- An unfiltered `Seq Scan` is never reported. Reading a whole table is sometimes
+  exactly what you meant.
+
+Needs `pip install "pytest-querycount[postgresql]"`. On SQLite or MySQL the check
+raises rather than passing, because a check that cannot fail is not a check.
+
+### A fixture, for when a marker is too coarse
+
+A marker covers the whole test. When you only care about one block:
+
+```python
+def test_detail(db, querycount):
+    with querycount(max_queries=2, no_seq_scan=True) as queries:
+        serialise(db)
+
+    assert queries.count == 2
+    assert queries.duplicates() == []
+    print(queries.report())
+```
+
+Call it with no arguments to observe without asserting -- that is how you find
+out what the budget should be before committing to one. The object from the
+`with` is the recorder, and it keeps its records after the block ends.
+
+### The report you leave switched on
+
+```bash
+pytest --querycount-report
+```
+
+```
+============================== querycount summary ==============================
+queries       time  dupes  test
+-------  ---------  -----  -------------------------------------------
+     13      0.1ms    12!  test_billing.py::test_billing_summary
+      2      0.0ms     -   test_billing.py::test_billing_summary_fixed
+
+15 queries in 0.1ms across 2 tests
+! marks a repeated query shape -- add @pytest.mark.no_n_plus_one to see the detail.
+```
+
+A budget tells you when you crossed a line you drew. This tells you where the
+lines should go, and it is the honest way to adopt the plugin on an existing
+suite: run it once, look at the rows with a `!`, write budgets for those.
+
+## Options
+
+| Flag | Effect |
+|---|---|
+| `--querycount-report` | Print the summary table |
+| `--querycount-top=N` | How many tests the table lists (default 10) |
+| `--querycount-max=N` | Apply a budget of N to every test without an explicit one |
+| `--querycount-no-seq-scan` | Apply the missing-index check to every test |
+
+`--querycount-max` is how you ratchet: set it just above your current worst
+test, then lower it as you fix things.
+
+In `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+querycount_max = "20"
+querycount_duplicate_threshold = "3"
+```
+
+## Design decisions worth knowing
+
+- **Only the call phase is measured.** Fixture setup and teardown run outside it,
+  so creating a schema and seeding it never consume a budget.
+- **A failing test is never second-guessed.** If your assertion fails, you see
+  that failure, not a complaint about query counts on top of it.
+- **`executemany` counts as one query**, because it is one round trip. That is
+  the point of it, and the fix for a loop of inserts.
+- **No backend is an error, not a pass.** If nothing is instrumented, every
+  count is zero and every budget is trivially satisfied. The plugin raises
+  instead, because a budget that cannot fail is worse than no budget.
+
+## Why not just count them yourself
+
+You can, in about twenty lines of `event.listen`. What you will not have is the
+fingerprinting that tells `WHERE id = 42` and `WHERE id = 43` apart from each
+other but together against `WHERE email = ?`; the walk up the stack to find the
+line in *your* code rather than in SQLAlchemy's; the collapsing of `IN (?,?,?)`
+so that batch size does not change the shape; or the failure message that names
+the culprit before it shows the evidence. That is what this package is.
+
+## Prior art
+
+[`nplusone`](https://pypi.org/project/nplusone/) did the detection half of this
+for Django and SQLAlchemy, but its last release was in **May 2018** and it does
+not support SQLAlchemy 2.x. Django users have `assertNumQueries` built in, which
+covers budgets but not shapes. This plugin is aimed at the SQLAlchemy side --
+FastAPI, Flask, Litestar -- where nothing is currently maintained.
+
+## Limitations
+
+- SQLAlchemy 2.x only for now. Django and raw psycopg are on the roadmap.
+- Under `pytest-xdist` the summary table is per worker, so it will be partial.
+  Budgets and N+1 detection are unaffected.
+- `no_seq_scan` is PostgreSQL only, and costs one `EXPLAIN` per SELECT while
+  enabled. Budgets and N+1 detection work on any SQLAlchemy backend.
+- The suggested `CREATE INDEX` is a starting point, not advice. Which columns to
+  index, in what order, and whether the index earns its write cost need the whole
+  query pattern, not one plan node. A filter over a function call
+  (`lower(email) = ...`) yields no suggestion at all rather than a wrong one.
+
+## Contributing
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+
+# The plan tests need PostgreSQL; without one they skip.
+docker run -d --name qc-pg -e POSTGRES_PASSWORD=querycount \
+    -e POSTGRES_DB=querycount -p 55432:5432 postgres:17-alpine
+
+pytest && ruff check src tests && mypy
+```
+
+Set `QUERYCOUNT_REQUIRE_PG=1` to turn those skips into failures, as CI does, and
+`QUERYCOUNT_TEST_PG_URL` to point elsewhere.
+
+The suite runs pytest inside pytest via `pytester`: it writes a throwaway test,
+runs it in a subprocess, and asserts on the outcome. That is the only honest way
+to test a plugin whose job is to make tests fail.
+
+## Releasing
+
+See [RELEASING.md](RELEASING.md). Publication goes through PyPI Trusted
+Publishing, so there is no API token in this repository or its secrets.
+
+## Licence
+
+MIT

pytest_querycount-0.3.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+pytest_querycount/__init__.py,sha256=mE-xK3UiI4aPN5oMNlAnMtfUmctyN3aXVSwzdLMifmk,730
+pytest_querycount/checks.py,sha256=RAP3PypqTXxgzEx0re04MOa51W4Xi4FN4QsFuo-B2zQ,5903
+pytest_querycount/errors.py,sha256=-xC9HpEEm_z1on1AqEIlZBTk69Qy3q2FhXtp-jbG_RM,1099
+pytest_querycount/explain.py,sha256=nqsnlbqeRpUsEVGuhS3xZa-VzjtygZ1reNgis8k4apc,6017
+pytest_querycount/normalize.py,sha256=xUenZDOMDdgCmuhishuAAIu5gp82PhOj-cu3kO5mZDM,3667
+pytest_querycount/plugin.py,sha256=H85cxtuk7JUOYkpo8AcbWom4qWjR4TZ74kjYykcVrAI,9185
+pytest_querycount/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytest_querycount/recorder.py,sha256=Hq18W2UMeY5rgx5kTTXC8a_G366p5DoouQ6LDswlN9A,7645
+pytest_querycount/records.py,sha256=XVLYjXA5CbqA4cRa2gGGFbIHJfi6KsHHLlM3v5UOQ_Y,2126
+pytest_querycount/report.py,sha256=J_dX6ArnVF_nysxK0MIHIYoD2zwWyvPEHyMqgZxu8ZY,2055
+pytest_querycount/backends/__init__.py,sha256=bpzplqoZw_-5QZkwBdB24uYB1fbTPZhKhVFhIRv7ar0,1831
+pytest_querycount/backends/sqlalchemy.py,sha256=mbXwb7DFBNUQv_fkr3oBYqkfyiPk8Po4YCnczh0pE4I,7167
+pytest_querycount-0.3.0.dist-info/METADATA,sha256=73I2wxovgiPYbpsO_0upqfb7rEhGGDwoj3K4rxXAtbg,13781
+pytest_querycount-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pytest_querycount-0.3.0.dist-info/entry_points.txt,sha256=oex8Hidov-J-QUtO2H-9jWjk88Yf98ctT1KGJDvf9tM,49
+pytest_querycount-0.3.0.dist-info/licenses/LICENSE,sha256=x67ZEM8AygvcybK9jS9iViUqb1igphougfREcPlJsYM,1073
+pytest_querycount-0.3.0.dist-info/RECORD,,

pytest_querycount-0.3.0.dist-info/WHEEL

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

pytest_querycount-0.3.0.dist-info/entry_points.txt

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

pytest_querycount-0.3.0.dist-info/licenses/LICENSE

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