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

{django_data_shape-0.22.0 → django_data_shape-0.23.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@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
         with:
           enable-cache: true
       - name: Install

{django_data_shape-0.22.0 → django_data_shape-0.23.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@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.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@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.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@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.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@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.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@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
         with:
           enable-cache: true
       - name: Install Python 3.13
@@ -273,7 +273,7 @@ jobs:
             --cov-report=html:htmlcov
       - name: Upload coverage artifact
         if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: coverage-postgres-${{ matrix.django-version }}
           path: |
@@ -339,7 +339,7 @@ jobs:
           fi
       - name: Download canonical coverage artifact
         if: steps.gate.outputs.skip != 'true'
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           # The Postgres job is the only run that reaches every line, so it is
           # the only one whose number means anything. Pinned to one cell of it:
@@ -428,12 +428,37 @@ jobs:
 
   tests-passed:
     name: tests
+    # always(), never !cancelled(): a skipped job reports a skipped check, and
+    # branch protection counts a skipped required check as passing.
     if: always()
     needs: [lint, docs, floor, test, test-postgres]
     runs-on: ubuntu-latest
     steps:
-      - name: Verify required jobs succeeded
+      # Pass on an exact `success` from every job above, rather than failing on
+      # a list of bad results: such a list passes whatever it does not name, and
+      # GitHub reports a result it does not document. A job no hosted runner
+      # ever picks up ("The job was not acquired by Runner of type hosted even
+      # after multiple attempts") shows as cancelled on its own check but
+      # reaches `needs` as `abandoned`, and a gate that failed only on `failure`
+      # and `cancelled` went green over exactly that while the jobs it guards
+      # never ran. A matrix reaches `needs` as one result, and one cell that did
+      # not succeed is enough to make it something other than `success`.
+      #
+      # None of the jobs above has an `if:`, so `skipped` can only mean one of
+      # them never ran, and it fails like any other result. A job that gains a
+      # legitimate skip gets an exception naming it, never `skipped` accepted
+      # from all of them.
+      #
+      # The results come in through `env` rather than being spliced into the
+      # script, and every one is printed, so a red gate says which job and what
+      # GitHub reported for it.
+      - name: Verify every required job succeeded
+        env:
+          NEEDS: ${{ toJSON(needs) }}
         run: |
-          if [ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" = "true" ]; then
-            echo "a required job failed"; exit 1
+          echo "$NEEDS" | jq -r 'to_entries[] | "\(.key): \(.value.result)"'
+          not_ok="$(echo "$NEEDS" | jq -r '[to_entries[] | select(.value.result != "success") | "\(.key)=\(.value.result)"] | join(" ")')"
+          if [ -n "$not_ok" ]; then
+            echo "::error::required jobs did not succeed: $not_ok"
+            exit 1
           fi

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

@@ -72,7 +72,7 @@ jobs:
       PGDATABASE: django_data_shape
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
         with:
           enable-cache: false
 

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

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] — 2026-10-23
+
+### Added
+
+- **`FanOut(max_children=)` caps how many children any one parent gets.** A
+  power-law fan-out gives its busiest parent a share that the seed moves by a
+  factor of five to twelve, and production's tails are bounded by the business,
+  so calibrating a world against production needs a ceiling. The cap applies
+  to the integer partition: the rows a capped parent gives up are re-spread
+  over the uncapped ones by their weights, a childless parent still gets none,
+  and a declaration whose parents cannot hold every row under the cap is
+  refused with the arithmetic. It is part of the declaration's digest, so a
+  cached uncapped world is never served for a capped one, and `fan_out_sizes`
+  reports the capped sizes. `max_children=1` is a one-to-one: a skewed
+  fan-out with a childless share is accepted on a unique column under it,
+  where without it only `FanOut(Constant(1))` with no childless share was.
+- **Documentation:** the relations page has a table of the busiest parent's
+  share of the rows for each `Zipf` exponent at 100, 1,000 and 10,000 parents,
+  drawn over twenty seeds. A test re-measures it, so it cannot drift from
+  what the partition draws.
+- **Documentation:** the statistics page says that anything writing to a built world leaves its
+  statistics stale and shows the `ANALYZE` to run, and how to declare a
+  placeholder for a column a later step fills.
+
+### Changed
+
+- **`scaled_world` is annotated `-> Generator[int]` instead of
+  `-> Iterator[int]`.** `ty` 0.0.86 warns that a `@contextmanager` function
+  annotated with `Iterator` is deprecated. Nothing changes at runtime, and a
+  caller's annotation of the context manager it returns is unaffected. The
+  protocol's docstring example and the type-level fixtures follow.
+
+### Fixed
+
+- **A key named in `parents=` as a string is the parent it spells.** The keys
+  read back from the parent table are the primary key's own type, so on
+  PostgreSQL a UUID named as the string it was loaded from JSON as found its
+  row and was then compared unequal to it, and the refusal said the row did not
+  exist -- pointing at a rollback rather than at the spelling. Each named key
+  now goes through the primary key field's `to_python` before it is compared,
+  for `FanOut(parents=)` and `Paired(parents=)` alike. A value the field cannot
+  read as a key is refused naming the table, the field and the value, where it
+  used to reach the driver, including from a field whose `to_python` raises
+  `ValueError` or `TypeError` rather than Django's `ValidationError`. The
+  reading is not taken on trust: on an integer key only the integer or its
+  string is taken, so `1.5`, `Decimal("1.9")` or a `uuid.UUID`, which `int()`
+  would turn into a row nobody named, is refused, as is a `bool` on any key;
+  and one row named in two spellings is refused as a repeat.
+- **`parents=` narrows a UUID-keyed parent on SQLite.** The keys went to the
+  database as raw parameters, and SQLite has no binding for a UUID, so naming a
+  UUID-keyed parent failed there in every spelling. They are now prepared by
+  the primary key field, as the ORM prepares them.
+- **`Paired(parents=)` refuses a repeated key.** It had no repeat check at all,
+  so a partner named twice was weighed twice without a word.
+- **A negative or non-finite fan-out size is refused.** Nothing checked the
+  sign, so `Uniform(-2, 10)` or a `Skew` with a negative key built a partition
+  whose sizes were negative or did not add up to the rows, and an infinite size,
+  or finite sizes summing past a float, gave rows to childless parents or
+  failed inside the arithmetic. Each is now refused naming the table and field.
+- **`fan_out_sizes` raises `WorldChanged` for a parent table that was emptied
+  since the build.** A declared parent with no rows left was refused as
+  `InvalidShape` saying the parent has no rows, before the check that names a
+  moved world could run, so a transactional test truncating a session world --
+  a cause the docstring names -- was told its declaration was wrong. Any
+  refusal of the partition over a declared parent that no longer holds the
+  declared rows is now `WorldChanged`, with the refusal chained as its cause.
+  `WorldChanged` is not an `InvalidShape`, so a caller catching `InvalidShape`
+  for that case no longer catches it.
+
 ## [0.22.0] — 2026-10-07
 
 ### Added
@@ -1682,7 +1751,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.22.0...HEAD
+[Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.23.0...HEAD
+[0.23.0]: https://github.com/Artui/django-data-shape/compare/v0.22.0...v0.23.0
 [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-data-shape
-Version: 0.22.0
+Version: 0.23.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

{django_data_shape-0.22.0 → django_data_shape-0.23.0}/django_data_shape/declaration/check_constraints.py

@@ -243,8 +243,8 @@ def _check_a_fan_out_beside_a_draw(
     :class:`~django_data_shape.distributions.sequential.Sequential` beside a
     fan-out keeps the constraint in every row with nothing arranged around it. A
     partition that gives no parent two rows is the second -- there is then no
-    group for two draws to collide inside -- and :func:`_cannot_collide` is the
-    four conditions that establish it. Neither exemption is "this usually works":
+    group for two draws to collide inside -- and :func:`_cannot_collide` is what
+    establishes it, by a cap of one or by four conditions together. Neither exemption is "this usually works":
     a shape that merely usually works is the case this refusal is for, and the
     measured ones sit at ten and eleven times out of twenty.
 
@@ -330,9 +330,10 @@ def _check_a_fan_out_on_a_unique_column(table: Table, rows_of: dict[type[Model],
             "table's rows over the parent's keys by weight, so a skew putting two rows on one "
             "parent is what it was asked for -- and the unique index then refuses the second, "
             "inside COPY, at a row number that moves when the seed does. A one-to-one is filled "
-            "by a fan-out whose sizes give every parent the same weight and whose rows do not "
-            "outnumber the parents: FanOut(Constant(1)) over at least as many parents as this "
-            "table has rows. childless= is how a parent with no row at all is asked for."
+            "by max_children=1, which caps every parent at one row whatever the sizes weigh and "
+            "leaves childless= free to ask for parents with no row at all; or by "
+            "FanOut(Constant(1)) with no childless share over at least as many parents as this "
+            "table has rows."
         )
 
 
@@ -409,7 +410,13 @@ def _cannot_collide(table: Table, column: str, rows_of: dict[type[Model], int])
     partition in which no group holds two rows cannot produce one, whatever the
     other column draws and whatever the seed.
 
-    Four conditions, and all four are needed. The sizes have to be provably flat
+    The first way is a cap of one. ``max_children=1`` bounds the partition
+    itself, so no parent holds two rows whatever the sizes weigh, whatever the
+    childless share, and wherever the parents come from; a declaration whose
+    rows outnumber the parents that can hold them is refused when the partition
+    is drawn, naming the arithmetic, before a row reaches ``COPY``.
+
+    Without it, four conditions, and all four are needed. The sizes have to be provably flat
     -- ``Bounded`` with exactly one distinct value, so every parent is weighed
     the same -- because ``_sizes`` divides ``rows`` by a total and hands the
     remainder to the parents with the largest fractional part: flat weights make
@@ -439,7 +446,7 @@ def _cannot_collide(table: Table, column: str, rows_of: dict[type[Model], int])
 
     .. warning::
 
-       **The coverage gate cannot see these four conditions, and the tests are
+       **The coverage gate cannot see these five conditions, and the tests are
        what hold them.** They are one boolean expression, so they are one branch
        arc: drop any single conjunct and the suite still reports 100% line and
        branch, because the surviving expression is still taken both ways. The
@@ -447,6 +454,9 @@ def _cannot_collide(table: Table, column: str, rows_of: dict[type[Model], int])
        against a tree with that condition removed. If you edit this expression,
        edit those with it -- they are, in order:
 
+       - ``max_children == 1`` --
+         ``test_a_cap_of_one_is_a_proof_whatever_the_sizes``, beside the
+         ``test_a_cap_of_two_is_not`` that keeps the comparison from widening.
        - ``Bounded`` with one value -- ``test_sizes_that_are_not_provably_flat_are_not_exempt``,
          which uses ``Uniform(1, 10)`` sizes because they give a largest group of
          two where ``Constant(1)`` gives one, at identical numbers.
@@ -460,7 +470,7 @@ def _cannot_collide(table: Table, column: str, rows_of: dict[type[Model], int])
     """
     fan_out = cast("FanOut", table.fields[column])
     parent_rows = _parents_available(table, column, fan_out, rows_of)
-    return (
+    return fan_out.max_children == 1 or (
         isinstance(fan_out.sizes, Bounded)
         and fan_out.sizes.distinct_values() == 1
         and not fan_out.childless

{django_data_shape-0.22.0 → django_data_shape-0.23.0}/django_data_shape/declaration/table.py

@@ -692,8 +692,8 @@ class Table:
                 f"{because} A relation is declared as "
                 f"a fan-out over the parent's real keys -- {required_relations[0]}=FanOut(Zipf()) "
                 "for the realistic heavy tail, FanOut(Uniform(1, 10)) for something flatter, and "
-                "FanOut(Constant(1)) over at least as many parents as this table has rows for a "
-                "one-to-one. childless= is the share of parents nobody references. The parent's "
+                "FanOut(Zipf(), max_children=1) for a one-to-one. childless= is the share of "
+                "parents nobody references. The parent's "
                 "own table has to be built in the same shape or already loaded, because that is "
                 "where the keys are read from."
             )

{django_data_shape-0.22.0 → django_data_shape-0.23.0}/django_data_shape/relations/fan_out.py

@@ -48,6 +48,23 @@ class FanOut:
     cosmetic. Emitting them parent by parent gives a perfectly clustered table
     that no production system has and that flatters every index scan; the
     default interleaves them the way rows really arrive.
+
+    ``max_children`` is a ceiling on any one parent's share. **It lives here and
+    not on the size distribution** because the weights are normalised: capping
+    a ``Zipf`` weight caps nothing, since the realised count is a share of
+    ``rows`` that the other weights decide. The cap applies to the integer
+    partition, and the rows a capped parent gives up are re-spread over the
+    others by their weights; a childless parent still gets none. It exists for
+    calibrating against production, whose tails the business bounds. **A cap
+    flattens the head into the body**, which the planner sees, so a capped
+    fan-out is a different world from the uncapped one rather than a free
+    improvement on it -- and choosing a ``Zipf`` exponent that already gives
+    production's maximum is often the better fix.
+
+    The cap counts every row the partition places, the ones ``null`` then
+    leaves without a parent included, so a parent at the cap can end with fewer
+    non-null children but never more. A cap of one is a one-to-one, whatever
+    the sizes weigh.
     """
 
     def __init__(
@@ -58,6 +75,7 @@ class FanOut:
         childless: float = 0.0,
         null: float = 0.0,
         placement: str = "arrival",
+        max_children: int | None = None,
     ) -> None:
         for name, share in (("childless", childless), ("null", null)):
             if not 0.0 <= share < 1.0:
@@ -68,6 +86,15 @@ class FanOut:
             raise InvalidShape(
                 f"FanOut placement must be one of {', '.join(PLACEMENTS)}, got {placement!r}."
             )
+        # bool is an int, and a cap of one spelled True has almost certainly
+        # been written for a different argument.
+        if max_children is not None and (
+            isinstance(max_children, bool) or not isinstance(max_children, int) or max_children < 1
+        ):
+            raise InvalidShape(
+                f"FanOut max_children is the most children any one parent may have, so it must "
+                f"be a whole number of at least 1, got {max_children!r}."
+            )
         narrowed = None if parents is None else tuple(parents)
         if narrowed is not None:
             # An empty sequence is falsy, and reading it as "not declared" would
@@ -97,6 +124,7 @@ class FanOut:
         self._childless = childless
         self._null = null
         self._placement = placement
+        self._max_children = max_children
 
     @property
     def sizes(self) -> Distribution:
@@ -118,6 +146,10 @@ class FanOut:
     def placement(self) -> str:
         return self._placement
 
+    @property
+    def max_children(self) -> int | None:
+        return self._max_children
+
     def canonical(self) -> object:
         """The size distribution, the parents it spreads over, and the shares. See ``Canonical``.
 
@@ -125,13 +157,22 @@ class FanOut:
         afterwards: two shapes differing only in which parents they cover are
         two different worlds, and the template-database cache keys on this. A
         clone built for one tenant handed to a test asking for another would be
-        the cache serving a world nobody declared.
+        the cache serving a world nobody declared. ``max_children`` is here for
+        the same reason.
         """
-        return (self._sizes, self._parents, self._childless, self._null, self._placement)
+        return (
+            self._sizes,
+            self._parents,
+            self._childless,
+            self._null,
+            self._placement,
+            self._max_children,
+        )
 
     def __repr__(self) -> str:
         narrowed = "" if self._parents is None else f"parents={self._parents!r}, "
+        capped = "" if self._max_children is None else f", max_children={self._max_children!r}"
         return (
             f"FanOut({self._sizes!r}, {narrowed}childless={self._childless!r}, "
-            f"null={self._null!r}, placement={self._placement!r})"
+            f"null={self._null!r}, placement={self._placement!r}{capped})"
         )

{django_data_shape-0.22.0 → django_data_shape-0.23.0}/django_data_shape/relations/fan_out_sizes.py

@@ -104,34 +104,54 @@ def fan_out_sizes(
     relation = dict(declaration.relations())[field]
     parent = cast("type[Model]", cast("Field[object, object]", relation).related_model)
 
-    plan = resolve_fan_out(
-        fan_out,
-        parent,
-        declaration.rows,
-        shape.seed,
-        declaration.db_table,
-        field,
-        connections[using],
-    )
-    keys = plan.parent_keys()
-
     # A narrowed fan-out covers the keys it named and no others, so the parent
     # table holding more rows than the partition covers is the declaration
     # working rather than the world moving. The failure WorldChanged exists for
     # is still caught, and caught earlier: a named key that is no longer a row is
-    # refused by name when the partition is resolved, above.
+    # refused by name when the partition is resolved, below.
     parent_declaration = (
         None if fan_out.parents is not None else declared.get(parent._meta.db_table)
     )
-    if isinstance(parent_declaration, Table) and len(keys) != parent_declaration.rows:
-        raise WorldChanged(
-            f"{parent.__name__} holds {len(keys)} rows and this shape declares "
-            f"{parent_declaration.rows}, so the fan-out for {model.__name__}.{field} would be "
-            "spread over parents the children were never spread across. The counts are derived "
-            "from the parent keys rather than counted off the child table, so an answer here "
-            "would describe a world that was never built. The usual causes are a test that "
-            "created more parents before asking, and a transactional test that truncated the "
-            "tables a session-scoped fixture built."
+    try:
+        plan = resolve_fan_out(
+            fan_out,
+            parent,
+            declaration.rows,
+            shape.seed,
+            declaration.db_table,
+            field,
+            connections[using],
         )
+    except InvalidShape as refused:
+        # A partition the build drew can still be refused here, over parents
+        # that have since gone: fewer of them can no longer hold the rows under
+        # max_children, or none of them is left. Blaming the declaration then
+        # sends the reader to change a shape that built, so a parent table that
+        # no longer holds what the shape declares is named as the cause.
+        if isinstance(parent_declaration, Table):
+            holds = parent._base_manager.using(using).count()
+            if holds != parent_declaration.rows:
+                raise _world_changed(
+                    parent, holds, parent_declaration.rows, model, field
+                ) from refused
+        raise
+    keys = plan.parent_keys()
+
+    if isinstance(parent_declaration, Table) and len(keys) != parent_declaration.rows:
+        raise _world_changed(parent, len(keys), parent_declaration.rows, model, field)
 
     return ChildrenPerParent(keys, plan.sizes(), fan_out.null)
+
+
+def _world_changed(
+    parent: type[Model], holds: int, declares: int, model: type[Model], field: str
+) -> WorldChanged:
+    return WorldChanged(
+        f"{parent.__name__} holds {holds} rows and this shape declares "
+        f"{declares}, so the fan-out for {model.__name__}.{field} would be "
+        "spread over parents the children were never spread across. The counts are derived "
+        "from the parent keys rather than counted off the child table, so an answer here "
+        "would describe a world that was never built. The usual causes are a test that "
+        "created more parents before asking, and a transactional test that truncated the "
+        "tables a session-scoped fixture built."
+    )