django-data-shape 0.20.0__tar.gz → 0.22.0__tar.gz

{django_data_shape-0.20.0 → django_data_shape-0.22.0}/.github/workflows/release.yml

@@ -56,7 +56,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           enable-cache: true
       - name: Install

{django_data_shape-0.20.0 → django_data_shape-0.22.0}/.github/workflows/tests.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           enable-cache: true
       - name: Install
@@ -37,7 +37,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           enable-cache: true
       - name: Install with docs group
@@ -79,7 +79,7 @@ jobs:
       PGDATABASE: django_data_shape
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           enable-cache: true
       # A floor is a claim about the *oldest* version that works, and a lockfile
@@ -199,7 +199,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           enable-cache: true
       - name: Install Python ${{ matrix.python-version }}
@@ -257,7 +257,7 @@ jobs:
       PGDATABASE: django_data_shape
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           enable-cache: true
       - name: Install Python 3.13

{django_data_shape-0.20.0 → django_data_shape-0.22.0}/.github/workflows/upstream-drift.yml

@@ -41,9 +41,38 @@ jobs:
   resolve-latest:
     name: resolve unpinned + test
     runs-on: ubuntu-latest
+    # The same service tests.yml gives its own jobs. Without it this workflow
+    # resolved the newest of everything, installed it, and then failed every
+    # Postgres-backed test on `connection refused` -- so it has never once
+    # reported on upstream drift, only on its own missing database. A job that
+    # cannot pass cannot fail informatively either: the issue it opens each week
+    # names a resolve that was never the problem.
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: django_data_shape
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    # Mirrors tests.yml. The unpinned resolve includes psycopg, so a release of
+    # it that breaks the connection is exactly the drift this is here to find,
+    # and it can only be found against a real server.
+    env:
+      PGHOST: localhost
+      PGPORT: "5432"
+      PGUSER: postgres
+      PGPASSWORD: postgres
+      PGDATABASE: django_data_shape
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           enable-cache: false
 
@@ -63,27 +92,70 @@ jobs:
         run: git --no-pager diff --stat uv.lock || true
 
       - name: Install
+        id: install
         run: uv sync --all-groups --all-extras
 
       - name: Show the resolved versions
         run: uv pip list
 
+      # A resolve can succeed by backing off. When the newest release of a
+      # direct dependency conflicts with something else this project requires,
+      # uv takes the newest version that does resolve and logs an ordinary
+      # "Updated" line, so the suite below passes against a release nobody
+      # chose. That is how django-ag-ui's run went green with pydantic-ai-slim
+      # at 2.46 and 2.54 out: from 2.47 its [ag-ui] extra caps ag-ui-protocol
+      # below the 1.0 django-ag-ui requires. This compares every direct
+      # dependency with PyPI, fails on one held below a release that has been
+      # out longer than the Dependabot cooldown, and asks uv what holds it. A
+      # ceiling declared in pyproject.toml is honoured, which is how a hold is
+      # accepted on purpose. One copy for every repo, pinned like any action.
+      - name: Check no direct dependency is held back
+        id: held-back
+        uses: Artui/held-back-check@b64bbb88fd63c9c96675caba477cce13714de93e # v0.1.0
+
+      # Runs whether or not the check above failed: they answer different
+      # questions, and a hold is no reason to stop measuring what did resolve.
       - name: Test
+        id: test
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
         run: uv run pytest
 
       - name: Open or update an issue on failure
-        if: failure()
+        # Main only. A dispatch on any other branch is a trial of that branch's
+        # manifest, and an issue saying the unpinned resolve is failing would be
+        # filed against the wrong tree.
+        if: failure() && github.ref == 'refs/heads/main'
+        env:
+          HELD_BACK: ${{ steps.held-back.outcome }}
+          TESTS: ${{ steps.test.outcome }}
+          REPORT: ${{ steps.held-back.outputs.report }}
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
+            const fs = require("fs");
             const title = "upstream drift: the unpinned resolve is failing";
+            const run = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            const sections = [];
+            if (process.env.TESTS === "failure") {
+              sections.push([
+                "The weekly unpinned resolve failed. A dependency released a version",
+                "that `pyproject.toml` admits and the suite does not survive.",
+                "",
+                "The `git diff --stat uv.lock` step in that run names what moved.",
+              ].join("\n"));
+            }
+            if (process.env.HELD_BACK === "failure") {
+              sections.push(fs.existsSync(process.env.REPORT)
+                ? fs.readFileSync(process.env.REPORT, "utf8")
+                : "The held-back check failed before writing its report; the run's log says why.");
+            }
+            if (!sections.length) {
+              sections.push("A step before the suite failed; the run's log names it.");
+            }
             const body = [
-              "The weekly unpinned resolve failed. A dependency released a version",
-              "that `pyproject.toml` admits and the suite does not survive.",
-              "",
-              `Run: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+              ...sections,
               "",
-              "The `git diff --stat uv.lock` step in that run names what moved.",
+              `Run: ${run}`,
               "",
               "Fix forward (adopt the new version) or add a floor/ceiling that says",
               "why, but do not silence the job — it is the control that lets this",

{django_data_shape-0.20.0 → django_data_shape-0.22.0}/CHANGELOG.md

@@ -7,6 +7,390 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.22.0] — 2026-10-07
+
+### Added
+
+- **`template_database(shape, base=...)` starts a template from a database
+  that is already migrated.** A template was always built into an empty
+  database that `migrate` replayed the whole history into, and on a project
+  with a long one that replay is most of the cost: a consumer with about 330
+  migrations measured thirteen and a half minutes of `migrate` against about a
+  minute to build a 4.4-million-row shape, paid again by every template a
+  change to the declaration makes. With a base, the template starts as
+  `CREATE DATABASE ... TEMPLATE <base>`: the tables `migrate` builds for apps
+  without migrations are rebuilt from the models, and everything else the base
+  holds is carried as it is. Apps with migrations are brought forward by their
+  history: `migrate --run-syncdb` still runs over the copy, applying whatever
+  the base has yet to and firing `post_migrate`. Apps without migrations have
+  no history, so the tables `run_syncdb` makes for them -- their managed
+  models' tables and the many-to-many tables Django creates for those models'
+  relations, read the way `run_syncdb` reads them, router and models module
+  included, and found under the name PostgreSQL stores, which cuts a
+  `db_table` longer than 63 bytes -- are dropped from the copy first and made
+  again from the current models, as in an empty database. `run_syncdb` never alters an existing table, so a table the
+  base made from an older model would otherwise survive under a key naming the
+  new one. The base's rows in those tables do not carry over; the rest of its
+  rows, an unmanaged model's table and the tables of an app no longer installed
+  are carried. A foreign key or view in the base that points into a rebuilt
+  table stops the drop, which runs without `CASCADE` so that nothing is
+  removed silently, and is refused as `UnusableBase` from the copy. So is a
+  rebuilt table the connecting role may not drop: `DROP TABLE` needs ownership
+  of the table or of its schema, and a copy keeps every owner the base gave, so
+  the message names each such table, its owner and the remedies -- connect as
+  the owner or a member of it that inherits its privileges, reassign the tables
+  in the base, or pass `base=None`. The check runs in the copy rather than the
+  base, because the role that makes the copy owns it and so holds the
+  privileges of `pg_database_owner`, which owns `public` from PostgreSQL 15: a
+  role owning none of those tables can still drop them from its own copy, and
+  is not refused.
+  `base=None`, the default, behaves and keys exactly as before.
+
+  **A base behind the migrations on disk is migrated forward in the copy; only
+  a history migrating cannot repair is refused**, with the new `UnusableBase`,
+  before anything is created. Migrating forward always ends at the checkout's schema for the
+  apps with migrations, whatever prefix of their history the base holds, and
+  the others are rebuilt, so the key stays sound without the
+  base's applied migrations entering it -- the same reason Django's own
+  PostgreSQL `TEST: {"TEMPLATE": ...}` can migrate a copy forward. A base far
+  behind pays its `migrate` once per key, never more than building from empty,
+  and the base a project has most often, one behind because a branch added a
+  migration, builds rather than being refused. *Ahead* is an applied migration
+  of an installed app that no migration on disk is or replaces: of the
+  histories a base can record, the one migrating cannot bring to the
+  checkout's schema, since a branch
+  migration that adds only an index would otherwise build silently and skew
+  plan assertions. The rows a squash leaves behind while it still lists them in
+  `replaces`, once all of them are applied, and the rows of an app that is no
+  longer installed, are not ahead. The message names up to three migrations
+  and both remedies: `manage.py migrate <app> --prune` for rows left by
+  squashed migrations deleted after their squash's `replaces` was removed, and
+  migrating the base back or recreating it for a migration from another
+  branch. Where `--prune` would decline, because a squash on disk still lists
+  in `replaces` a migration the base records as applied and that is gone from
+  disk -- one of the app being pruned from Django 5.1, of any app before -- it
+  names the squash and says to finish it first, and nowhere else, since
+  finishing a squash whose replaced files are still on disk splits the app
+  into two leaf migrations. Two
+  histories `migrate` would mishandle are refused too: a squash applied to the
+  base only in part, when a replaced migration it has yet to apply is gone
+  from disk -- Django then runs neither the squash nor the rest of what it
+  replaces, so the template would silently lack them, read off the graph
+  Django's loader builds, so that from Django 6.0 a squash of a squash is
+  judged over everything under it -- and a base holding the tables of an app
+  with a migration on disk that it records no applied migration for, which
+  `migrate` would try to create again: one with no `django_migrations` table,
+  one restored from `pg_dump --schema-only`, which brings that table back
+  empty, or one made before the app had migrations. An app whose migrations
+  would create nothing, such as a `0001_initial` holding only
+  `SeparateDatabaseAndState` state operations, is refused the same way,
+  although `migrate` would accept it. A base that does not
+  exist, one that does not accept connections, a name holding a double quote
+  -- which Django's quoting cannot carry intact, so the database checked and
+  the database copied could differ -- and a template this package made or the
+  partial of one are each refused by name rather than failing inside Django or
+  the server. Only a name the package generates counts as a template, so a
+  database of your own whose name starts `data_shape_` is not mistaken for one.
+
+  The key also takes the base's name and its database oid, so dropping and
+  recreating a base -- the usual way one restored from a dump is refreshed,
+  with the rows of `django_migrations` alongside the schema -- is a new
+  template. The base is checked on a cache hit too. Rows
+  the base holds become template content; changing them in place, by hand or
+  by migrating the base, neither of which moves its name or oid, is not seen
+  by the key, and is stated beside the
+  existing `RunSQL` gap with the same remedy, `drop_database`. One case no
+  check can see is stated too: a migration regenerated under a name the base
+  has already applied is skipped by `migrate`, so the copy keeps the version
+  the base ran; recreating the base is the remedy. Nor can one more: SQL an
+  applied migration of an app with migrations ran against a table of an app
+  without them -- an index, a trigger, a policy, a grant or a comment -- is
+  lost when the copy rebuilds that table, and recreating the base does not
+  help, so that template is built from empty with `base=None`. The process's
+  own connection is closed before the copy, so a project whose test database
+  is the base can pass it as one.
+
+### Changed
+
+- **Every module the package owns now lives in a subpackage named for a
+  concern.** The root held forty-five modules against four to eight in the
+  sibling libraries, and no rule had been broken: the structural rules all
+  governed a *file* -- one exported symbol, named after it, fully annotated --
+  and none governed a directory, so a package could satisfy every one of them
+  and still put everything it does in one place. The root now holds
+  `__init__.py`, `version.py` and `utils.py`.
+
+  The new directories are `declaration/` (what a user writes, and everything
+  that refuses it before a row exists), `relations/` (fan-out and paired edges,
+  declared and resolved against the keys that exist), `generation/`, `loading/`,
+  `invariants/`, `databases/`, `backends/`, `scaling/` and `types/`.
+  `infer_key_strategy` moved into the existing `keys/`. There is no
+  `exceptions/`: an exception stays beside the code that raises it, so
+  `DerivationQueriedDatabase` sits with the guard that raises it and
+  `UnsupportedBackend` with the two backend gates.
+
+  **No public import changes.** `__all__` is unchanged, name for name and in the
+  same order, and every symbol is still imported the same way -- the only paths
+  that moved are the ones a caller was never meant to reach into. The
+  `django_data_shape.fixtures` surface is untouched.
+
+- **`tests/test_package_layout.py` gates the layout**, asserting that the root
+  holds only the allowlisted modules and that no module name is used at two
+  levels. Prose is what failed here: a convention that names only files is
+  obeyed exactly as far as files go, and the drift it permitted was invisible
+  for twenty-one releases.
+
+### Fixed
+
+- **A scaled world no longer empties tables it does not declare, including
+  parents reached through a chain of foreign keys.** On PostgreSQL the emptying
+  was `TRUNCATE ... CASCADE`, and `CASCADE` follows foreign keys by schema,
+  transitively, whatever the rows hold. In an application whose billing points
+  back at its clubs -- a section belongs to a club, a fee to a section, and a
+  club references its selected fee -- a shape declaring only `Section` emptied
+  the clubs too. A fan-out narrowed to a club the caller had made, with
+  `parents=`, was then refused with `InvalidShape` for naming a key that was
+  "not a row of" the club table, blaming the caller's key for the package's own
+  statement; without `parents=` nothing was refused, and tables the caller had
+  filled were silently empty for the life of the block.
+
+  A world now removes the rows of its declared tables and nothing else, and no
+  statement it issues changes a table its shape does not declare, even inside
+  the block. On PostgreSQL it reads, from `pg_constraint`, every table
+  referencing a declared table that holds rows -- the set `CASCADE` would have
+  taken -- and when none of those holds rows it issues one `TRUNCATE` that
+  lists them all, without `CASCADE`: nothing outside the declaration loses a
+  row, and a list that ever missed a table would be refused by PostgreSQL
+  rather than silently widened. That is the route a session world under a
+  scaled world over the same graph takes every time. Otherwise each declared
+  table is emptied by `DELETE`, children first, and every undeclared row stays
+  where it was. A `DELETE` fires row-level `DELETE` triggers, which `TRUNCATE`
+  did not: a trigger on a declared table runs inside the world, and what it
+  writes elsewhere is rolled back with the block, while a `BEFORE DELETE`
+  trigger that keeps its rows leaves the build refusing the table with
+  `ShapeNotEmpty`. A world over empty tables issues no emptying statement and
+  fires no foreign-key checks.
+
+  A declared table with `Disjoint` keys is still left alone and built beside --
+  unless it holds rows and has a foreign key into a declared table the world
+  empties, directly or through another such table. Then it is emptied too, since
+  its rows are declared rows and cannot outlive the parents they point at. In
+  0.21.0 `CASCADE` emptied such a table on PostgreSQL, along with everything
+  else referencing the declared tables, and off PostgreSQL its rows were left
+  pointing at parents the world had deleted. The foreign keys that decide it
+  are the models', so a `ForeignKey(db_constraint=False)` pulls its table in as
+  well. A `Disjoint` table pointing at nothing the world empties keeps its
+  rows, which over a session world declaring it are the session's, and the
+  world builds beside them with keys of its own. `UuidKeys` and `Md5Keys` make
+  each key from the row and a stream derived from the seed, which scaling
+  keeps, so in 0.21.0 a world over a session world built from the same shape
+  made the session's keys and failed on the primary key. Every `Disjoint`
+  table a world builds is now handed a stream of the world's own, never the
+  one `build()` uses for the same seed and table, so inside a world its keys
+  are not the ones `build()` gives the same declaration. That stream does not
+  depend on the factor, so row *i* has one key at every factor, as an integer
+  key does, and a world opened inside another over the same table draws from
+  another stream again. Foreign keys into such a table need nothing, since a
+  fan-out reads its parents' keys from the table. And a world now reads
+  `Disjoint` as `build()` does: a key strategy implementing the protocol whose
+  `is_disjoint_from_existing_rows()` answers no is emptied like any other,
+  where the world used to leave its rows in place for the build to refuse with
+  `ShapeNotEmpty`.
+
+  **One behaviour changes: a scaled world declaring a parent over rows whose
+  undeclared children reference it is now refused**, where 0.21.0 silently
+  emptied them on PostgreSQL and left them pointing at nothing elsewhere.
+  Removing the parent's rows would leave those references pointing at nothing
+  or take the children along, so the world raises the new `ShapeReferenced`
+  before removing anything, naming each reference as
+  `referencing_table.column -> declared_table` and the ways out: declare that
+  table in the shape too, so its rows are the world's, or do not create those
+  rows in the test. Where following it would end the refusal, it also offers
+  `Disjoint` keys, so the world builds beside the rows already there: only
+  where every declared table it names has a primary key that accepts the UUIDs
+  `UuidKeys` and `Md5Keys` make, so never an integer key or one that is itself
+  a foreign key, and only where none of them is a projected table, has
+  `Disjoint` keys already, or has a foreign key into another table being
+  emptied, which would pull it back into the emptying. A scaled
+  world over part of a session world's graph meets it the same way, and the
+  remedy is the same. A foreign key left null is not a reference, and only a
+  foreign key the database enforces is seen: `ForeignKey(db_constraint=False)`
+  and `GenericForeignKey` are invisible to it. The refusal is made on every
+  backend: PostgreSQL's catalogue answers it there, and Django's introspection
+  everywhere else. It runs before any `DELETE` on both, which is what keeps a
+  `DELETE` inside the declaration: one can reach past its table through a
+  database-level `ON DELETE`, such as the one Django 6.1's `DB_CASCADE`
+  creates, but by then no row outside the tables being emptied references
+  them, so all it can reach is declared rows being removed anyway. Introspection reports each column of a
+  composite foreign key on its own, so off PostgreSQL such a key counts as soon
+  as any column is set; Django never creates one.
+
+  The `parents=` refusal names the one way a key can still vanish inside a
+  world: a parent table declared in the same shape, which the world empties
+  before building. The `scaled_world`, `scale_fixture` and `shape_fixture`
+  docstrings and the pytest page describe the rule, where the two fixtures'
+  docstrings still said a scaled world could not build over a session world at
+  all.
+
+- **A scaled world builds over child rows the caller wrote earlier in the same
+  transaction.** On PostgreSQL it failed on the way in with `cannot TRUNCATE
+  "..." because it has pending trigger events`. Django creates PostgreSQL
+  foreign keys `DEFERRABLE INITIALLY DEFERRED`, so a child row leaves its
+  foreign-key check queued until commit, and PostgreSQL refuses to truncate a
+  table with checks still pending. An insert into a parent alone queues nothing,
+  which is why only a caller who wrote a child met it; the usual way in is a
+  factory's `SubFactory` in a test's own setup.
+
+  `scaled_world` now fires the pending checks before a `TRUNCATE`. That changes
+  only *when* they run: a row that genuinely violates a constraint now raises
+  `IntegrityError` at world entry, naming the constraint, rather than when the
+  enclosing transaction next checks. The `DELETE` route the entry above adds,
+  taken on PostgreSQL when an undeclared table holds rows, fires them after its
+  `DELETE` statements instead, so a row outside the declaration that breaks a
+  constraint raises at entry on either route. The two routes part on an orphan
+  the caller wrote in a declared table: the `TRUNCATE` route raises for it,
+  while the `DELETE` route removes it first, PostgreSQL skips the check of a row
+  that is gone, and the world builds. Once the checks are fired, on either
+  route, every deferrable constraint is deferred for the rest of the block, one
+  declared `INITIALLY IMMEDIATE` included; the mode is transaction state, so
+  the rollback of the world's own block restores the caller's. Off PostgreSQL
+  nothing is fired, because nothing there refuses a pending check.
+
+  **`build()` sets a declared statistics target over checks still queued in its
+  transaction**, where PostgreSQL refused the `ALTER TABLE ... SET STATISTICS`
+  with `cannot ALTER TABLE "..." because it has pending trigger events`. A table
+  with `Disjoint` keys is built beside the rows already there, so a row the
+  caller wrote into it earlier in the transaction left its check queued on the
+  very table the build then altered -- and a scaled world over such a table
+  empties nothing, so it met the same refusal. Each row a world's `DELETE`
+  removes from a referenced table queues a check too. `apply_statistics_targets`
+  now fires the pending checks before its first `ALTER TABLE`, and only for a
+  table that declares a target, so a table declaring none issues no statement
+  more. A row that breaks a constraint raises `IntegrityError` there, naming
+  it. Firing them ends with `SET CONSTRAINTS ALL DEFERRED`, so a build inside a
+  transaction of the caller's leaves every deferrable constraint deferred until
+  that transaction ends.
+
+  The docstring claimed this package never issues a destructive statement
+  against a table it did not fill. Beside `CASCADE` that was untrue. What holds
+  now, and what the docstring says, is that no statement a world issues changes
+  a table its shape does not declare: the only statement naming an undeclared
+  table is a `TRUNCATE` of tables that hold no rows.
+
+  The PostgreSQL statement count a capture around a world sees over empty
+  tables is nineteen, the same at every factor; over a session world declaring
+  the same tables, emptying them first adds five more where another table
+  references them, four where none does, also the same at every factor. The
+  figure quoted in the `scaled_world` and `scale_fixture` docstrings
+  and in the pytest page had drifted from the measured one in all three places;
+  they now quote both, and a test holds them to it. The `execute_wrapper` figure
+  the `scaled_world` docstring quotes beside it, seventeen -- two fewer, because
+  `COPY` reaches the debug cursor's log but not the wrapper hook -- is now
+  measured and held to the prose the same way.
+
+- **The `ShapeNotEmpty` message and the pytest page describe the refusal the
+  package makes.** Since 0.17.0 a scaled world empties the tables it declares
+  inside the transaction it rolls back, so it builds over a session world's
+  rows -- yet the message still said a scaled world cannot build over them, and
+  the pytest page's "The two fixtures do not share a table" still called that
+  composition refused and prescribed different models. The message now names
+  the causes that remain: a second build over a session world's rows, another
+  `shape_fixture` or `build()` called directly, and a template started from a
+  base database that holds rows in a declared table. Its remedies are a scaled
+  world, different models, or emptying the table, in the base if that is where
+  the rows came from. The page's section is now "A scaled world can sit over a
+  session world", quoting the new message, and a test holds the quotation to
+  the message raised.
+
+- **Statistics targets are looked up under the name Django created the table
+  with.** `build()` read each column's current target through `regclass`,
+  binding the model's raw `db_table`, and `regclass` input is parsed as an
+  identifier: a capital letter folded to lower case and a dot split the name
+  into a schema and a table. A model whose `db_table` held either stopped the
+  build with "relation does not exist" before a row was written, or, where a
+  table of the folded name existed, was checked against that table's targets,
+  so a shape its own column could not record went through unrefused. The name
+  is now quoted by the connection, as Django's `CREATE TABLE` quoted it, which
+  also resolves a `db_table` written already quoted, such as
+  `'"schema"."table"'`.
+
+- **`drop_database` and `clone_database` refuse a database name holding a
+  double quote**, with `ValueError`, before any statement. Django's
+  `quote_name` wraps a name in double quotes without escaping one inside it,
+  and passes a name already wrapped in them through unchanged, so a statement
+  could name a different database from the one the same string names as a
+  value: `drop_database('"x"')` looked up a database literally named `"x"`,
+  reported that it was not there, and dropped `x`, and a quote followed by a
+  clause made the clause part of the statement. `template_database` already
+  refused such a base; all three now share one check, and no name this package
+  makes holds a double quote.
+
+## [0.21.0] — 2026-09-06
+
+### Added
+
+- **`values=` expressions can name one another, as `{values.<name>}`.** A
+  projected table's measure columns are usually related to each other -- a
+  requested amount and an approved one, a quantity and a total, an amount and
+  the rate derived from it -- and an expression could not say so. The
+  relationship had to be restated from whatever both columns were computed from,
+  with coefficients chosen so that it happens to hold: a reader could only find
+  the invariant by doing the arithmetic, and nothing rechecked it when either
+  expression was edited.
+
+  The name is dotted rather than a bare `{requested_amount}` because `{per}` and
+  `{source}` already occupy that space and a model is entitled to a column
+  called `per`. Only `values=` entries are referenceable -- a copied column is
+  already reachable as `{source}.name`, and the primary key is the
+  `row_number()` window itself and is reachable nowhere.
+
+  **It is substitution, not sharing**, which is what the spelling says: the
+  referenced expression is written out again, parenthesised, and the database
+  evaluates it once per reference. That is free for a deterministic expression,
+  and every expression here already had to be deterministic -- `template_database`
+  reuses a database keyed on the declaration and nothing else. What a reference
+  adds is that a volatile expression now disagrees with itself *within one
+  build*, so the documentation pairs the feature with an `Invariant` rather than
+  leaving the rule stated and unchecked.
+
+  A subquery computing each expression once was declined: the key is a
+  `row_number()` window whose outer `ORDER BY` decides where rows physically
+  land, so nesting moves the one thing this package exists to control -- and a
+  shape using no reference would have had its statement changed to buy a feature
+  it does not use. Substitution leaves every existing shape's SQL byte-identical.
+
+  A reference that names nothing, and a cycle, are refused at declaration time
+  and name the path. A name that is a *copied* column is refused separately and
+  hands over `{source}.name`, because that is a mistake about the spelling
+  rather than about the column.
+
+### Fixed
+
+- **The documented `SqlValue` example was a type error on UUID-keyed models.**
+  `({per}.id * 31 + {source}.id * 17) % 5 + 1` works on Django's default
+  `BigAutoField` and has no operator at all on a schema whose models carry
+  `id = UUIDField(primary_key=True)` -- which a shared abstract base makes an
+  ordinary layout rather than an unusual one. So the first thing such a reader
+  copied out of the documentation did not run, and it failed from inside a
+  generated statement at build time rather than at declaration.
+
+  The guide and the docstring now carry a worked example for UUID keys, and it
+  is **executed by the suite** rather than asserted: the documentation's Python
+  blocks are only parsed, and an expression is a string literal that parses
+  perfectly, which is exactly how this shipped. Two parts of the replacement are
+  load-bearing and fail rarely enough to reach production -- `::bigint` before
+  `abs`, because `hashtext` returns `int4` and `abs(-2147483648)` is `integer
+  out of range`; and `abs` at all, because PostgreSQL's `%` keeps the sign of
+  the dividend, so a measure column would hold negatives and every plan over it
+  would still look fine.
+
+- **The projections guide implied UUID keys were settled by one sentence about
+  `sql=`.** That sentence is about the *projected table's own* primary key. The
+  tables named by `per=` and `copying=` may be keyed however they like, and the
+  care an expression over one of them needs is a different subject that the page
+  did not cover -- so a reader with UUID keys throughout read a paragraph that
+  appeared to address them and was sent onward into the broken example.
+
 ## [0.20.0] — 2026-09-05
 
 ### Added
@@ -1298,7 +1682,9 @@ 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.20.0...HEAD
+[Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.22.0...HEAD
+[0.22.0]: https://github.com/Artui/django-data-shape/compare/v0.21.0...v0.22.0
+[0.21.0]: https://github.com/Artui/django-data-shape/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/Artui/django-data-shape/compare/v0.19.0...v0.20.0
 [0.19.0]: https://github.com/Artui/django-data-shape/compare/v0.18.1...v0.19.0
 [0.18.1]: https://github.com/Artui/django-data-shape/compare/v0.18.0...v0.18.1

{django_data_shape-0.20.0 → django_data_shape-0.22.0}/CLAUDE.md

@@ -51,6 +51,25 @@ make docs-build    # mkdocs build --strict
 - `__init__.py` is the only re-export point, and holds no logic.
 - Every annotated module starts with `from __future__ import annotations`. Ruff's
   `required-imports` enforces this rather than leaving it to memory.
+- **The package root is a table of contents, not a drawer.** It holds
+  `__init__.py`, `version.py` and `utils.py`; everything this package does lives
+  in a subpackage named for a concern. Those are `declaration/` (what a user
+  writes and what refuses it), `relations/`, `generation/`, `loading/`,
+  `invariants/`, `databases/`, `backends/`, `scaling/`, the vocabulary
+  directories `derivations/`, `distributions/` and `keys/`, the value carriers in
+  `types/`, and the pytest surface in `fixtures/`. Three modules on one concern
+  earn a directory; below three they join the neighbouring concern rather than
+  sitting at the root. A name says what the code does, so `helpers/`, `core/`,
+  `common/` and `misc/` are refused -- each is the flat root again one level
+  down. An exception lives beside the code that raises it, or, where many
+  modules raise it, in the subpackage whose failure it names, which is why there
+  is no `exceptions/`.
+
+  This rule is asserted in `tests/test_package_layout.py` rather than trusted,
+  because prose is what failed the first time: the six rules above all govern a
+  *file*, every one of them was satisfied, and forty-two modules still piled up
+  at the package root. The test gates both halves -- the root allowlist, and
+  that no module name is used at two levels.
 
 ## The rules the design rests on
 

{django_data_shape-0.20.0 → django_data_shape-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-data-shape
-Version: 0.20.0
+Version: 0.22.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
@@ -268,6 +268,15 @@ clone_database(template, "test_myapp", replace=True)
 
 The template is named after a content hash of the declaration, the schema, the
 relevant settings and this package's version, so a stale one is never asked for.
+A project with a long migration history can start templates from a database it
+already keeps migrated, `template_database(shape, base="myproject_base")`, rather
+than replaying every migration into an empty one. Apps with migrations are
+migrated forward in the copy, which always ends at the checkout's schema; the
+tables `migrate` builds for apps without them are rebuilt from the models, so the
+base's rows in those do not carry over; and everything else the base holds, its
+other rows and its unmanaged tables among them, is carried as it is. Only a
+history no forward migration can fix, such as a base ahead of the migrations on
+disk, is refused.
 A shape holding a `Derived` or a `KeyFunction` is refused rather than hashed --
 there is no honest digest of a callable, and every way of guessing one agrees
 while the data has changed. See

{django_data_shape-0.20.0 → django_data_shape-0.22.0}/README.md

@@ -225,6 +225,15 @@ clone_database(template, "test_myapp", replace=True)
 
 The template is named after a content hash of the declaration, the schema, the
 relevant settings and this package's version, so a stale one is never asked for.
+A project with a long migration history can start templates from a database it
+already keeps migrated, `template_database(shape, base="myproject_base")`, rather
+than replaying every migration into an empty one. Apps with migrations are
+migrated forward in the copy, which always ends at the checkout's schema; the
+tables `migrate` builds for apps without them are rebuilt from the models, so the
+base's rows in those do not carry over; and everything else the base holds, its
+other rows and its unmanaged tables among them, is carried as it is. Only a
+history no forward migration can fix, such as a base ahead of the migrations on
+disk, is refused.
 A shape holding a `Derived` or a `KeyFunction` is refused rather than hashed --
 there is no honest digest of a callable, and every way of guessing one agrees
 while the data has changed. See