django-data-shape 0.3.0__tar.gz → 0.4.0__tar.gz

{django_data_shape-0.3.0 → django_data_shape-0.4.0}/CHANGELOG.md

@@ -7,6 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-09-02
+
+### Added
+- **The pytest surface**, in `django_data_shape.fixtures`. `shape_fixture(shape)`
+  returns a session-scoped fixture that builds a shape once for a whole run;
+  bind it to a name in `conftest.py` and request that name from a test. It
+  composes with pytest-django rather than replacing it, asking for
+  `django_db_setup` and `django_db_blocker` by name so the coupling is to two
+  fixture names and not to pytest-django's internals. Session scope is
+  load-bearing: pytest creates higher-scoped fixtures first, so the rows are
+  committed before the transaction that wraps a test is opened, and every test
+  sees them while everything a test writes is rolled back with it.
+- **The scale protocol**, which is what a growth assertion asks a world for:
+  make the world be at factor F, then let the caller run its block.
+  `scaled_world(shape, factor)` is a context manager that builds it and undoes
+  it; `scale_fixture(shape)` is the same thing as a fixture; and `ScaleProtocol`
+  is the structural type both satisfy, so a consumer asserting that a query
+  count is `O(1)` rather than `O(N)` depends on the shape of the call rather
+  than on this package. What the context manager yields is a plain row count,
+  not a `BuildResult`, for the same reason: a seam a stranger cannot implement
+  is not a seam.
+- `scaled_shape(shape, factor)`, the declaration transform underneath it. **A
+  factor varies the declaration rather than subsetting one larger build**, because
+  a subset is not a smaller database but the same database with a filter -- the
+  statistics still describe every row, and the block under test would have to
+  cooperate by restricting itself, which puts the harness inside the thing being
+  measured. Every table scales, parents included, so the average fan-out is the
+  same at every factor and two worlds differ in size alone. The scaled tables go
+  through `Table`'s own constructor, so a declaration that only holds at its
+  original size is refused at the factor that breaks it, naming the factor.
+- `skip_unless_postgres(connection, operation)`, the pytest twin of the backend
+  refusal. Both fixtures skip with the refusal's own message as the reason where
+  a shaped database cannot exist, so a suite that also runs on SQLite reports
+  what it did not check rather than passing over a database nobody shaped.
+- A `pytest` extra. It is an extra rather than a dependency because the rest of
+  the package has nothing to do with pytest, which is also why these fixtures are
+  not re-exported from the top-level `__init__`: importing them is what requires
+  pytest, not importing the package.
+- **`build(shape, require_statistics=False)` loads rows on any backend.** It asks
+  for rows and cardinality rather than for a database the planner can reason
+  about, and it is written as a requirement being dropped rather than as work
+  being skipped: on PostgreSQL it changes nothing at all, since `COPY` and
+  `ANALYZE` are both free and leaving them out would manufacture the unanalyzed
+  table this package exists to condemn. Elsewhere the rows are inserted in chunks
+  and no statistics are gathered. SQLite's own `ANALYZE` is deliberately not run,
+  because running it would claim the plan realism this package says it will not
+  claim. The driver check is unaffected: psycopg 2 is still refused on a
+  PostgreSQL connection, because the vendor picks the route and not the caller.
+- **The growth harness works on every backend Django supports** and no longer
+  skips. A query count is an ORM property and means the same anywhere, so a
+  growth assertion is honest off PostgreSQL where a plan assertion is not, and
+  the scale harness was the only thing standing between a consumer on SQLite and
+  the milestone's headline seam. `shape_fixture` still skips: it exists to build
+  a world a planner will believe.
+
+### Fixed
+- `ScaleProtocol` rejected the implementations its own docstring offered. A
+  structural type matches parameter names too, so a hand-rolled callable taking
+  `n` rather than `factor` did not satisfy it -- exactly the five-line callable
+  the documentation tells a consumer to write. The factor is positional-only now,
+  and two files of consumers and impostors are type-checked by the suite, because
+  a type-level claim with no type-level test is what let this ship.
+- `ShapeNotEmpty` names the likely cause and not only the remedy. The first
+  consumer met it by composing both fixtures over one model, where the rows are
+  real, correct and written by a fixture the failing test never mentions -- so
+  "empty the table first" read as advice about somebody else's data.
+
 ## [0.3.0] — 2026-09-01
 
 ### Fixed
@@ -147,7 +214,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   into `COPY FROM STDIN`, which psycopg 2 cannot do without materialising them
   first.
 
-[Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/Artui/django-data-shape/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/Artui/django-data-shape/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Artui/django-data-shape/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/Artui/django-data-shape/compare/v0.1.0...v0.1.1

{django_data_shape-0.3.0 → django_data_shape-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-data-shape
-Version: 0.3.0
+Version: 0.4.0
 Summary: A realistically shaped test database from Django models: declare cardinality, skew and fan-out, load by COPY, and make the query planner believe it.
 Project-URL: Homepage, https://github.com/Artui/django-data-shape
 Project-URL: Repository, https://github.com/Artui/django-data-shape
@@ -36,6 +36,9 @@ Requires-Python: >=3.10
 Requires-Dist: django>=4.2
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]>=3.2.0; extra == 'postgres'
+Provides-Extra: pytest
+Requires-Dist: pytest-django>=4.9.0; extra == 'pytest'
+Requires-Dist: pytest>=8.0.0; extra == 'pytest'
 Description-Content-Type: text/markdown
 
 # django-data-shape
@@ -99,7 +102,10 @@ build(shape)
 
 `build()` generates the rows, loads them with `COPY`, moves the identity sequence
 past the keys it assigned, and runs `ANALYZE` so the planner can see the shape.
-It raises on any backend that is not PostgreSQL rather than degrading quietly.
+It raises on any backend that is not PostgreSQL rather than degrading quietly --
+unless you say `require_statistics=False`, which asks for rows and cardinality
+instead of a database the planner can reason about, and is what the growth
+harness below is built on.
 
 ## Relations
 
@@ -126,6 +132,37 @@ The parents can be rows this package built or rows your own code did -- their
 real keys are read, not assumed, so the ORM can own the small tables while this
 owns the large ones.
 
+## From pytest
+
+```python
+# conftest.py
+from django_data_shape import Constant, Shape, Table
+from django_data_shape.fixtures import scale_fixture, shape_fixture
+
+orders = shape_fixture(Shape(Table(Order, rows=100_000, status=Constant("complete"))))
+world = scale_fixture(Shape(Table(Order, rows=100, status=Constant("complete"))))
+```
+
+`orders` is one world built once for the whole session, composed with
+pytest-django rather than replacing it. `world` is the **scale protocol**: make
+the world be at factor F, then let the caller run its block, which is what a
+query count asserted to be `O(1)` rather than `O(N)` needs.
+
+```python
+def test_the_dashboard_does_not_grow(world, django_assert_num_queries):
+    for factor in (1, 10):
+        with world(factor):
+            with django_assert_num_queries(3):
+                dashboard()
+```
+
+A factor varies the declaration rather than subsetting one larger build, and
+`pip install 'django-data-shape[pytest]'` is what these two need. **The growth
+harness works on any backend Django supports**, because a query count is an ORM
+property and means the same everywhere; the session world **skips with a stated
+reason** where a shaped database cannot exist, because a plan over it is the
+thing it exists to make honest.
+
 ## What it expects, and what it refuses
 
 A declaration that cannot describe a database raises before a row is generated,
@@ -133,7 +170,10 @@ naming the field. In particular:
 
 - **PostgreSQL and psycopg 3.** Rows stream into `COPY FROM STDIN`, which
   psycopg 2 cannot do without materialising them first. Both are refused by name
-  rather than degraded around.
+  rather than degraded around. PostgreSQL is required for the statistics half
+  only: `build(shape, require_statistics=False)` loads rows on any backend and
+  claims nothing about a plan. psycopg 2 is refused either way, because the
+  vendor picks the route and not the caller.
 - **A key type it can assign.** Integer keys count from one and UUID keys are
   derived from the seed; anything else is refused rather than guessed, and
   `keys=KeyFunction(...)` declares one.
@@ -145,8 +185,9 @@ naming the field. In particular:
 
 ## Status
 
-Early. Single tables and the model graph. Derived fields, collections copied
-along a join, per-group invariants and template-database reuse come next.
+Early. Single tables, the model graph and the pytest surface. Derived fields,
+collections copied along a join, per-group invariants and template-database reuse
+come next.
 
 Full documentation: <https://artui.github.io/django-data-shape/>
 

{django_data_shape-0.3.0 → django_data_shape-0.4.0}/README.md

@@ -59,7 +59,10 @@ build(shape)
 
 `build()` generates the rows, loads them with `COPY`, moves the identity sequence
 past the keys it assigned, and runs `ANALYZE` so the planner can see the shape.
-It raises on any backend that is not PostgreSQL rather than degrading quietly.
+It raises on any backend that is not PostgreSQL rather than degrading quietly --
+unless you say `require_statistics=False`, which asks for rows and cardinality
+instead of a database the planner can reason about, and is what the growth
+harness below is built on.
 
 ## Relations
 
@@ -86,6 +89,37 @@ The parents can be rows this package built or rows your own code did -- their
 real keys are read, not assumed, so the ORM can own the small tables while this
 owns the large ones.
 
+## From pytest
+
+```python
+# conftest.py
+from django_data_shape import Constant, Shape, Table
+from django_data_shape.fixtures import scale_fixture, shape_fixture
+
+orders = shape_fixture(Shape(Table(Order, rows=100_000, status=Constant("complete"))))
+world = scale_fixture(Shape(Table(Order, rows=100, status=Constant("complete"))))
+```
+
+`orders` is one world built once for the whole session, composed with
+pytest-django rather than replacing it. `world` is the **scale protocol**: make
+the world be at factor F, then let the caller run its block, which is what a
+query count asserted to be `O(1)` rather than `O(N)` needs.
+
+```python
+def test_the_dashboard_does_not_grow(world, django_assert_num_queries):
+    for factor in (1, 10):
+        with world(factor):
+            with django_assert_num_queries(3):
+                dashboard()
+```
+
+A factor varies the declaration rather than subsetting one larger build, and
+`pip install 'django-data-shape[pytest]'` is what these two need. **The growth
+harness works on any backend Django supports**, because a query count is an ORM
+property and means the same everywhere; the session world **skips with a stated
+reason** where a shaped database cannot exist, because a plan over it is the
+thing it exists to make honest.
+
 ## What it expects, and what it refuses
 
 A declaration that cannot describe a database raises before a row is generated,
@@ -93,7 +127,10 @@ naming the field. In particular:
 
 - **PostgreSQL and psycopg 3.** Rows stream into `COPY FROM STDIN`, which
   psycopg 2 cannot do without materialising them first. Both are refused by name
-  rather than degraded around.
+  rather than degraded around. PostgreSQL is required for the statistics half
+  only: `build(shape, require_statistics=False)` loads rows on any backend and
+  claims nothing about a plan. psycopg 2 is refused either way, because the
+  vendor picks the route and not the caller.
 - **A key type it can assign.** Integer keys count from one and UUID keys are
   derived from the seed; anything else is refused rather than guessed, and
   `keys=KeyFunction(...)` declares one.
@@ -105,8 +142,9 @@ naming the field. In particular:
 
 ## Status
 
-Early. Single tables and the model graph. Derived fields, collections copied
-along a join, per-group invariants and template-database reuse come next.
+Early. Single tables, the model graph and the pytest surface. Derived fields,
+collections copied along a join, per-group invariants and template-database reuse
+come next.
 
 Full documentation: <https://artui.github.io/django-data-shape/>
 

{django_data_shape-0.3.0 → django_data_shape-0.4.0}/django_data_shape/__init__.py

@@ -15,6 +15,9 @@ from django_data_shape.keys.key_function import KeyFunction
 from django_data_shape.keys.key_strategy import KeyStrategy
 from django_data_shape.keys.sequential_keys import SequentialKeys
 from django_data_shape.keys.uuid_keys import UuidKeys
+from django_data_shape.scale_protocol import ScaleProtocol
+from django_data_shape.scaled_shape import scaled_shape
+from django_data_shape.scaled_world import scaled_world
 from django_data_shape.shape import Shape
 from django_data_shape.shape_not_empty import ShapeNotEmpty
 from django_data_shape.table import Table
@@ -31,6 +34,7 @@ __all__ = [
     "InvalidShape",
     "KeyFunction",
     "KeyStrategy",
+    "ScaleProtocol",
     "SequentialKeys",
     "UuidKeys",
     "Sequential",
@@ -44,4 +48,6 @@ __all__ = [
     "UnsupportedBackend",
     "__version__",
     "build",
+    "scaled_shape",
+    "scaled_world",
 ]

{django_data_shape-0.3.0 → django_data_shape-0.4.0}/django_data_shape/build.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from collections.abc import Iterator
+from itertools import islice
 from typing import Any, cast
 
 from django.core.management.color import no_style
@@ -20,8 +22,14 @@ from django_data_shape.shape_not_empty import ShapeNotEmpty
 from django_data_shape.table import Table
 from django_data_shape.table_result import TableResult
 
+# Big enough that the per-statement overhead disappears and small enough that
+# the peak list is a rounding error next to the rows themselves.
+_INSERT_CHUNK = 1000
 
-def build(shape: Shape, using: str = DEFAULT_DB_ALIAS) -> BuildResult:
+
+def build(
+    shape: Shape, using: str = DEFAULT_DB_ALIAS, *, require_statistics: bool = True
+) -> BuildResult:
     """Generate, load, reset sequences and analyze every table in ``shape``.
 
     The order of those steps is the whole function, and it is not
@@ -36,9 +44,24 @@ def build(shape: Shape, using: str = DEFAULT_DB_ALIAS) -> BuildResult:
     statistics work proper -- per-column targets, and caching a built database
     as a template -- comes later. A loader that leaves its table unanalyzed
     ships the exact state this package exists to condemn.
+
+    ``require_statistics=False`` asks for rows and cardinality rather than for a
+    database the planner can reason about, and it is the only way to build on a
+    backend without ``COPY`` and column statistics. It is written as a
+    requirement being dropped rather than as work being skipped, because that is
+    what it does: **on PostgreSQL it changes nothing at all** -- the load is
+    still ``COPY`` and ``ANALYZE`` still runs, since both are free and leaving
+    them out would manufacture the unanalyzed table this package exists to
+    condemn. Elsewhere the rows are inserted instead and no statistics are
+    gathered, so cardinality is real and nothing about a plan is claimed.
+
+    The distinction is the one this package draws everywhere: generation and
+    cardinality are backend-neutral, planner realism is not. A query *count* is
+    an ORM property and means the same on any backend, which is why a growth
+    assertion can be honest here while a plan assertion still cannot.
     """
     connection = connections[using]
-    require_postgres(connection, "Building a shape")
+    require_postgres(connection, "Building a shape", statistics=require_statistics)
 
     results: list[TableResult] = []
     # One transaction around every table. Without it a shape whose second table
@@ -82,6 +105,13 @@ def _require_empty(connection: Any, table: Table) -> None:
     the same table collides on the primary key. That surfaced as a bare
     UniqueViolation naming an index, which tells the reader nothing about what
     they did or what to do instead.
+
+    The message names the likely cause and not only the remedy, because the
+    first consumer met this from a direction the remedy does not fit: a
+    session-scoped ``shape_fixture`` and a scaled world pointed at one model.
+    The rows are then real, correct, and put there by a fixture the failing test
+    never mentions -- so "empty the table first" reads as advice about somebody
+    else's data.
     """
     with connection.cursor() as cursor:
         cursor.execute(f"SELECT EXISTS (SELECT 1 FROM {connection.ops.quote_name(table.db_table)})")
@@ -89,7 +119,10 @@ def _require_empty(connection: Any, table: Table) -> None:
     if row[0]:
         raise ShapeNotEmpty(
             f"{table.db_table} already holds rows, and this package assigns primary keys from 1, "
-            "so building over them would collide. Empty the table first."
+            "so building over them would collide. If nothing in the test wrote them, the usual "
+            "cause is a world that was already there: a session-scoped shape_fixture over this "
+            "model holds its rows for the whole run, and a scaled world cannot build over them. "
+            "Give the two different models, or empty this table first."
         )
 
 
@@ -98,12 +131,7 @@ def _require_empty(connection: Any, table: Table) -> None:
 # class, so annotating the real wrapper type would mean asserting the checker
 # out of the way on every line that uses it.
 def _load(connection: Any, table: Table, seed: int, plans: dict[str, FanOutPlan]) -> int:
-    """Stream generated rows into the table with ``COPY FROM STDIN``.
-
-    ``bulk_create`` is the obvious alternative and is roughly an order of
-    magnitude too slow at the row counts that make a plan meaningful. ``COPY``
-    is also why the generator yields tuples rather than model instances: there
-    is no instance to build, and no ``save`` to run.
+    """Stream generated rows into the table, by the fastest route the backend has.
 
     Each declared value is passed through its field's ``get_db_prep_save``
     first, and that is not a formality. Skipping it is how a naive datetime got
@@ -111,7 +139,9 @@ def _load(connection: Any, table: Table, seed: int, plans: dict[str, FanOutPlan]
     non-UTC ``TIME_ZONE`` -- silently, on the exact column ``Sequential`` exists
     to make realistic -- and how a ``JSONField`` failed to load at all. The
     generator stays backend-neutral because the preparation happens here rather
-    than inside it.
+    than inside it, and that is also why the preparation sits **above** the
+    branch below: a value is prepared by its field for its connection, which is
+    the same work whichever statement carries it.
 
     Returns the number of rows the database actually took, not the number
     declared. They are the same today and stop being so once deduplicated
@@ -120,12 +150,31 @@ def _load(connection: Any, table: Table, seed: int, plans: dict[str, FanOutPlan]
     quote = connection.ops.quote_name
     pk_field = table.model._meta.pk
     columns = [quote(pk_field.column)] + [quote(field.column) for _, field in table.columns()]
-    statement = f"COPY {quote(table.db_table)} ({', '.join(columns)}) FROM STDIN"
     # The primary key is prepared like every other value. It did not need to be
     # while keys were always integers; a UUID key does, and a strategy the
     # caller wrote could return anything its column accepts.
     prepare = [pk_field.get_db_prep_save] + [field.get_db_prep_save for _, field in table.columns()]
+    rows = (
+        tuple(prep(value, connection) for prep, value in zip(prepare, row, strict=True))
+        for row in generate_rows(table, seed, plans)
+    )
+
+    if connection.vendor == "postgresql":
+        return _copy(connection, table.db_table, columns, rows)
+    return _insert(connection, table.db_table, columns, rows)
 
+
+def _copy(
+    connection: Any, db_table: str, columns: list[str], rows: Iterator[tuple[Any, ...]]
+) -> int:
+    """``COPY FROM STDIN``, which is the reason this package can be worth using.
+
+    ``bulk_create`` is the obvious alternative and is roughly an order of
+    magnitude too slow at the row counts that make a plan meaningful. ``COPY``
+    is also why the generator yields tuples rather than model instances: there
+    is no instance to build, and no ``save`` to run.
+    """
+    statement = f"COPY {connection.ops.quote_name(db_table)} ({', '.join(columns)}) FROM STDIN"
     with connection.cursor() as cursor:
         # ``copy`` is not in Django's WRAP_ERROR_ATTRS, so without this a
         # Postgres error escapes as a raw psycopg exception: the caller cannot
@@ -133,13 +182,41 @@ def _load(connection: Any, table: Table, seed: int, plans: dict[str, FanOutPlan]
         # block never learns it needs a rollback, so the next query inside it
         # fails with "current transaction is aborted" instead of a Django error.
         with connection.wrap_database_errors, cursor.copy(statement) as copy:
-            for row in generate_rows(table, seed, plans):
-                copy.write_row(
-                    tuple(prep(value, connection) for prep, value in zip(prepare, row, strict=True))
-                )
+            for row in rows:
+                copy.write_row(row)
         return int(cursor.rowcount)
 
 
+def _insert(
+    connection: Any, db_table: str, columns: list[str], rows: Iterator[tuple[Any, ...]]
+) -> int:
+    """The portable route, for a backend that has no ``COPY``.
+
+    Reached only when the caller said it does not require planner statistics,
+    which is the honest shape of the trade: this writes real rows in real
+    cardinality and buys nothing at all for a plan. It is slower than ``COPY``
+    and that is the wrong thing to worry about at the sizes it is for --
+    measured on SQLite, the insert costs about 1.6 ms per thousand rows against
+    8 ms to generate them, so the load is not what a growth assertion pays for.
+
+    Chunked rather than handed the whole iterator, because ``executemany``
+    materialises what it is given: streaming into ``COPY`` is the property this
+    package is built on, and a portable path that quietly held a million tuples
+    in memory would be a different bargain from the one above.
+    """
+    placeholders = ", ".join(["%s"] * len(columns))
+    statement = (
+        f"INSERT INTO {connection.ops.quote_name(db_table)} "
+        f"({', '.join(columns)}) VALUES ({placeholders})"
+    )
+    loaded = 0
+    with connection.cursor() as cursor:
+        while chunk := list(islice(rows, _INSERT_CHUNK)):
+            cursor.executemany(statement, chunk)
+            loaded += len(chunk)
+    return loaded
+
+
 def _reset_sequence(connection: Any, table: Table) -> None:
     """Move the identity sequence past the keys this package just assigned.
 
@@ -161,6 +238,15 @@ def _analyze(connection: Any, table: Table) -> None:
     selectivity and commits to it, which is how a two-million-row table gets
     bitmap-scanned through an index for a value matching 98% of it. Measured at
     81 ms on that table, because ``ANALYZE`` samples rather than scans.
+
+    Nothing is gathered on another backend, and SQLite is the case worth being
+    explicit about: it has an ``ANALYZE`` of its own and running it is one line.
+    It is deliberately not run. Plan realism on SQLite is out of this package's
+    scope -- support the generation, refuse the pretence -- and a table with
+    ``sqlite_stat1`` behind it would be this package claiming, in the only way a
+    library can, that the plan over it means something.
     """
+    if connection.vendor != "postgresql":
+        return
     with connection.cursor() as cursor:
         cursor.execute(f"ANALYZE {connection.ops.quote_name(table.db_table)}")

django_data_shape-0.4.0/django_data_shape/fixtures/__init__.py

@@ -0,0 +1,19 @@
+"""The pytest surface, deliberately outside the top-level re-exports.
+
+Everything in here imports ``pytest``, and ``pytest`` is an optional extra
+rather than a dependency. Re-exporting these from ``django_data_shape/__init__``
+would make ``import django_data_shape`` fail for a project that runs its suite
+with Django's own runner, so the import boundary is drawn where the dependency
+boundary already is: ``from django_data_shape.fixtures import shape_fixture``
+says out loud that pytest is required for this half and not for the other.
+"""
+
+from django_data_shape.fixtures.scale_fixture import scale_fixture
+from django_data_shape.fixtures.shape_fixture import shape_fixture
+from django_data_shape.fixtures.skip_unless_postgres import skip_unless_postgres
+
+__all__ = [
+    "scale_fixture",
+    "shape_fixture",
+    "skip_unless_postgres",
+]

django_data_shape-0.4.0/django_data_shape/fixtures/scale_fixture.py

@@ -0,0 +1,76 @@
+"""One shape, offered at whatever size the test asks for."""
+
+from __future__ import annotations
+
+from functools import partial
+
+import pytest
+from django.db import DEFAULT_DB_ALIAS
+
+from django_data_shape.scale_protocol import ScaleProtocol
+from django_data_shape.scaled_world import scaled_world
+from django_data_shape.shape import Shape
+
+
+# ``object`` for the same reason as in shape_fixture: the type of a fixture is
+# pytest's own and it changed shape between pytest 8.0 and 8.4.
+def scale_fixture(shape: Shape, *, using: str = DEFAULT_DB_ALIAS) -> object:
+    """A pytest fixture yielding a :class:`~django_data_shape.scale_protocol.ScaleProtocol`.
+
+    The pytest face of the scale protocol. Bind it in ``conftest.py``::
+
+        from django_data_shape import Constant, Shape, Table
+        from django_data_shape.fixtures import scale_fixture
+
+        world = scale_fixture(Shape(Table(Order, rows=100, status=Constant("new"))))
+
+    and a growth assertion has somewhere to ask for a bigger world::
+
+        def test_the_dashboard_query_is_constant(world, django_assert_num_queries):
+            for factor in (1, 10):
+                with world(factor):
+                    with django_assert_num_queries(3):
+                        dashboard()
+
+    The declared row counts are the world at factor 1, so the base declaration
+    should be the smallest world that still means something -- a hundred rows
+    against a thousand is the regime this is for, and it is milliseconds per
+    factor. Size, in the two-million-row sense that makes a query *plan*
+    realistic, is a different assertion with a different cost and does not vary
+    a factor at all.
+
+    Function-scoped, and it requests pytest-django's ``db`` fixture, which does
+    two things worth knowing. A test using this needs no ``django_db`` marker of
+    its own. And each world is then built inside the transaction that wraps the
+    test, so tearing it down is a savepoint rollback: cheap, exact, and leaving
+    the test's own transaction usable afterwards. A test that marks itself
+    ``transaction=True`` still works -- the marker wins over the fixture, and
+    the rollback is then an ordinary one.
+
+    **Not over a model a session world already holds.** Each world here is built
+    from empty and undone again, so a table that
+    :func:`~django_data_shape.fixtures.shape_fixture.shape_fixture` filled for
+    the session is one this cannot build into at all -- the rows are still there,
+    and the build is refused. The two compose over a graph by taking different
+    models, not by taking turns over one.
+
+    **It works on any backend Django supports**, because what a growth
+    assertion measures -- the number of queries a block emits -- is an ORM
+    property rather than a planner one. Where the backend has ``COPY`` and
+    column statistics the world is built with them; where it does not, the rows
+    are inserted and no statistics are gathered, so the cardinality is real and
+    nothing about a plan is claimed. That is the one place this package builds
+    outside PostgreSQL, and it is allowed precisely because the assertion it
+    serves does not need the planner. A plan assertion still skips: see
+    :func:`~django_data_shape.fixtures.skip_unless_postgres.skip_unless_postgres`.
+    """
+
+    @pytest.fixture
+    def scaled_worlds(db: None) -> ScaleProtocol:
+        # Binding, not wrapping. The fixture's whole job is to attach one shape
+        # and one connection to the protocol; everything about what a world is
+        # and how it is undone belongs to scaled_world, where a consumer not
+        # using pytest can reach it too.
+        return partial(scaled_world, shape, using=using)
+
+    return scaled_worlds

django_data_shape-0.4.0/django_data_shape/fixtures/shape_fixture.py

@@ -0,0 +1,94 @@
+"""One shape, built once for a whole test session."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from django.db import DEFAULT_DB_ALIAS, connections
+
+from django_data_shape.build import build
+from django_data_shape.build_result import BuildResult
+from django_data_shape.fixtures.skip_unless_postgres import skip_unless_postgres
+from django_data_shape.shape import Shape
+
+
+# The return type is ``object`` on purpose. What ``pytest.fixture`` hands back
+# is pytest's own -- a plain function on pytest 8.0 and a
+# ``FixtureFunctionDefinition`` from 8.4 onwards -- so naming it here would pin
+# this package's floor to a pytest version in exchange for nothing: the caller
+# binds the value to a name and never calls it.
+def shape_fixture(shape: Shape, *, using: str = DEFAULT_DB_ALIAS) -> object:
+    """A session-scoped pytest fixture that builds ``shape`` once.
+
+    Bind it to a name in ``conftest.py`` and request that name from a test::
+
+        from django_data_shape import Constant, Shape, Table
+        from django_data_shape.fixtures import shape_fixture
+
+        orders = shape_fixture(Shape(Table(Order, rows=100_000, status=Constant("new"))))
+
+    ::
+
+        import pytest
+
+        @pytest.mark.django_db
+        def test_the_dashboard_query(orders):
+            assert orders.rows == 100_000
+
+    It **composes with pytest-django rather than replacing it**. The fixture
+    requests ``django_db_setup``, which is the seam a project overrides to
+    decide how its test database is made, so whatever a project has done there
+    -- a template database, ``--reuse-db``, a different creation strategy -- has
+    already happened before a row is generated. It then writes through
+    ``django_db_blocker.unblock()``, the mechanism pytest-django documents for
+    populating a database once. Neither of those is imported: they are asked for
+    by name, so this package depends on two fixture names and not on
+    pytest-django's internals.
+
+    **Session scope is load-bearing, not a performance choice.** pytest creates
+    higher-scoped fixtures before lower-scoped ones, so a session-scoped build
+    always runs before the function-scoped ``db`` fixture opens the transaction
+    that wraps a test -- which is what makes the rows committed and visible to
+    every later test. A function-scoped build would be ordered against ``db`` by
+    the accident of argument order, and on the losing side of that order it
+    would be rolled back with the test that happened to build it.
+
+    Yields the :class:`~django_data_shape.build_result.BuildResult`, so a test
+    can assert on the size of the world it was handed.
+
+    **One caveat, and it is worth stating plainly**: a test marked
+    ``django_db(transaction=True)`` truncates every table at teardown, and takes
+    the session's rows with it. Nothing rebuilds them, so a later test that
+    reads this fixture is measuring an empty database. Keep transactional tests
+    off the tables a shape owns, mark them ``serialized_rollback=True``, or
+    build per test with
+    :func:`~django_data_shape.scaled_world.scaled_world` at factor 1 -- which
+    undoes itself and therefore does not care.
+
+    **One world per table.** A session world holds its rows for the whole run,
+    so :func:`~django_data_shape.fixtures.scale_fixture.scale_fixture` over the
+    same model cannot build: the second build meets a table that is not empty
+    and is refused. Give the two different models -- the session world the tables
+    a plan assertion needs to be big, the scale harness the tables a growth
+    assertion counts. It is the first thing a consumer composing both hits, and
+    the refusal now names it.
+
+    On a connection that cannot carry a shaped database the fixture skips with
+    the reason rather than raising, so a suite that also runs on SQLite reports
+    what it did not check instead of erroring or, worse, passing.
+    """
+
+    # The blocker is typed loosely because naming its class would mean importing
+    # pytest_django, and the whole point of asking for it by name is that this
+    # package does not. It is a pytest-django fixture; what is used of it is
+    # ``unblock()``.
+    @pytest.fixture(scope="session")
+    def built_shape(django_db_setup: None, django_db_blocker: Any) -> BuildResult:
+        # ``vendor`` is a class attribute, so the gate is read before anything
+        # is unblocked and a skip costs no connection at all.
+        skip_unless_postgres(connections[using], "Building a shape for the test session")
+        with django_db_blocker.unblock():
+            return build(shape, using=using)
+
+    return built_shape