django-data-shape 0.14.0__tar.gz → 0.16.0__tar.gz

{django_data_shape-0.14.0 → django_data_shape-0.16.0}/.pre-commit-config.yaml

@@ -65,3 +65,15 @@ repos:
         language: pygrep
         types: [text]
         exclude: '^\.pre-commit-config\.yaml$'
+
+      # Structural rather than a pattern, so it is a script where the guards
+      # above are pygrep. A merge or a rebase can rearrange this file without
+      # conflicting: a released heading and an unreleased entry insert after the
+      # same line, git resolves them silently, and shipped work ends up filed
+      # under a version already published. It has happened four times across two
+      # repositories and every catch was a habit rather than a gate.
+      - id: check-changelog
+        name: "check CHANGELOG structure (merge and rebase leave it silently wrong)"
+        entry: scripts/check-changelog
+        language: script
+        files: '^CHANGELOG\.md$'

{django_data_shape-0.14.0 → django_data_shape-0.16.0}/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] — 2026-09-04
+
+### Fixed
+- **A `FanOut(parents=[...])` partition no longer depends on what the keys are.**
+  Keys are read back ordered by primary key and the sizes are assigned by
+  position, so the weights followed the *sort order of the values* rather than
+  the declaration. With integer keys that is merely surprising; with the UUID
+  primary keys a factory row has on a modern schema it means **the same shape
+  builds differently every run** -- measured, one declaration gave the
+  first-named parent 5, 11 or 79 rows across twelve builds. That is the promise
+  the package rests on, and the same reason `UuidKeys` derives rather than
+  draws, so a narrowing that broke it was a defect and not a preference. Named
+  parents are put back in the order they were named before anything is weighed.
+  - **Reversing the list is now a different declaration**, which is what a
+    reader writing one would expect and was the symptom reported.
+  - **Weights are still scattered across positions**, so the reasoning that
+    argued for scattering survives: a caller's *order* decides which key lands
+    where, and nothing correlates a parent's key with its child count.
+  - Worth knowing for anyone testing near this: a test written over
+    **integer** parents passes against the broken behaviour, because the
+    database's sort order matches insertion order there. Only UUID parents show
+    it.
+- **`shape_from_factory` takes `defaults=`, and names a factory that cannot be
+  called.** Most factories in a real codebase take arguments and need them; a
+  `TeamFactory` wanting a `permission_role`, called with nothing, left a
+  required column empty and failed as a raw `IntegrityError` naming a
+  constraint. That said nothing about what the caller ran, which is the one
+  thing every other refusal here avoids. Anything the factory raises is now
+  named with the call number, because "it failed" and "it failed after three"
+  are different bugs.
+
+
+## [0.15.0] — 2026-09-04
+
+### Added
+- **`shape_from_factory` runs a factory you already have and returns source, not
+  a `Shape`.** That is the design rather than a limitation of it: a shape this
+  package builds is *declared*, which is what makes it reviewable and
+  assertable, and a shape learned from a sample is neither -- one used directly
+  would change whenever the factory did, silently. So it returns text, and a
+  person decides what of it to keep.
+  - **What it finds matters more than what it writes**, because a faithful
+    reading of a typical factory produces the flat world this package exists to
+    argue against. Factories are written for single-object tests, so they fix
+    values and reach foreign keys in the two most unrealistic ways there are.
+    Every such column is a **finding**, and the report leads with them.
+  - **A sub-factory is the sharpest case and the reason to run it.**
+    `company = SubFactory(CompanyFactory)` creates one parent per child, which is
+    a fan-out of degree one: every parent has exactly one row, the average is the
+    truth, and a join over it cannot be misestimated. It is invisible in the
+    factory's own source, so it is detected by watching which other tables grew
+    and by how much. A round-robin over four parents is the same defect with a
+    different number, and is reported too.
+  - A relation is rendered as a `FanOut` and never as a value distribution,
+    because `Table` refuses the second -- emitting it would hand back source that
+    cannot be built, which is worse than a wrong number. A factory that already
+    varies everything gets a declaration and **no findings**: if the quiet case
+    were not quiet, the loud one would stop meaning anything.
+  - Nothing is left behind. The calls run inside a transaction that is rolled
+    back, so it can be pointed at a development database without writing to one.
+    The sample size is stated in the output, because the answer moves with it.
+
+
+### Fixed
+- **`Md5Keys` could not fill a projection on about half of all tables.**
+  `key_sql` wrote `to_hex(<stream>::bigint)`, asking PostgreSQL to re-derive a
+  number Python produced as **unsigned** -- and `bigint` is signed, so any
+  stream above 2^63 raised `NumericValueOutOfRange` before a row was written.
+  The stream is a hash of the table and field names, so it is a coin flip per
+  table rather than anything about a schema or a seed: measured, 49% of table
+  names land above the limit. The stream is a constant by the time the statement
+  is built, so the sixteen hex digits are embedded and nothing is re-derived.
+  - **Reported by a consumer, and it had never executed for them.** In 0.13.0
+    the join-ambiguity refusal answered first, so `key_sql` was unreachable;
+    fixing that in 0.14.0 with `through=` is what exposed a feature 0.13.0 had
+    shipped and nobody could run.
+  - **The test that was supposed to prove the two halves agree used
+    `stream=12345`** -- a number chosen for a test rather than one the producer
+    makes. It now uses a pair `field_stream` actually produced, one either side
+    of the limit, and asserts that the pair straddles it so a later change to
+    how streams are derived cannot quietly make both tests vacuous.
+
+
 ## [0.14.0] — 2026-09-03
 
 ### Added
@@ -967,7 +1050,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.14.0...HEAD
+[Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.16.0...HEAD
+[0.16.0]: https://github.com/Artui/django-data-shape/compare/v0.15.0...v0.16.0
+[0.15.0]: https://github.com/Artui/django-data-shape/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/Artui/django-data-shape/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/Artui/django-data-shape/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/Artui/django-data-shape/compare/v0.11.0...v0.12.0

{django_data_shape-0.14.0 → django_data_shape-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-data-shape
-Version: 0.14.0
+Version: 0.16.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.14.0 → django_data_shape-0.16.0}/django_data_shape/__init__.py

@@ -47,6 +47,7 @@ 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_digest import shape_digest
+from django_data_shape.shape_from_factory import shape_from_factory
 from django_data_shape.shape_not_empty import ShapeNotEmpty
 from django_data_shape.table import Table
 from django_data_shape.table_result import TableResult
@@ -108,6 +109,7 @@ __all__ = [
     "fan_out_sizes",
     "require_clone_strategy",
     "scaled_shape",
+    "shape_from_factory",
     "scaled_world",
     "shape_digest",
     "template_database",

{django_data_shape-0.14.0 → django_data_shape-0.16.0}/django_data_shape/keys/md5_keys.py

@@ -47,17 +47,26 @@ class Md5Keys:
         a test computes both for the same rows and compares them, which is the
         only form of agreement that means anything here.
 
-        ``md5`` takes the same eight-byte big-endian pair Python hashes, built
-        with ``to_hex``/``lpad`` and turned back into bytes by ``decode``, so
-        neither side is hashing a rendering of the other's input. The stamp is
-        two ``overlay`` calls on the hex digest: nibble 13 is the version and is
-        always ``4``, and nibble 17 is the variant, which keeps its low two bits
-        and takes ``8`` in the high two.
+        ``md5`` takes the same eight-byte big-endian pair Python hashes, turned
+        back into bytes by ``decode``, so neither side is hashing a rendering of
+        the other's input. The stamp is two ``overlay`` calls on the hex digest:
+        nibble 13 is the version and is always ``4``, and nibble 17 is the
+        variant, which keeps its low two bits and takes ``8`` in the high two.
+
+        **The stream is embedded as hex rather than converted by the server**,
+        and that is a fix rather than a preference. It used to be written
+        ``to_hex(<stream>::bigint)``, which asks PostgreSQL to re-derive a
+        number Python produced as *unsigned* -- and ``bigint`` is signed, so any
+        stream above 2^63 raised ``NumericValueOutOfRange`` before a row was
+        written. That is a coin flip per table, not a property of any schema:
+        the stream is a hash of the table and field names, so roughly half of
+        all table names land above the limit. It is a constant by the time this
+        statement is built, so nothing about it needs deriving at all.
+
+        ``row`` stays a conversion because it is genuinely an expression the
+        server evaluates, and a row index is far below the limit.
         """
-        digest = (
-            f"md5(decode(lpad(to_hex({stream}::bigint), 16, '0') || "
-            f"lpad(to_hex(({row})::bigint), 16, '0'), 'hex'))"
-        )
+        digest = f"md5(decode('{stream:016x}' || lpad(to_hex(({row})::bigint), 16, '0'), 'hex'))"
         variant = f"to_hex((('x' || substr({digest}, 17, 1))::bit(4)::int & 3) | 8)"
         return (
             f"(overlay(overlay({digest} placing '4' from 13 for 1) "

{django_data_shape-0.14.0 → django_data_shape-0.16.0}/django_data_shape/resolve_fan_out.py

@@ -45,6 +45,7 @@ def resolve_fan_out(
     """
     keys, parent_values = _read_parents(parent, parent_fields, connection, fan_out.parents)
     _require_every_named_parent(fan_out.parents, keys, parent, table, field)
+    keys, parent_values = _in_declared_order(fan_out.parents, keys, parent_values)
 
     if not keys and rows:
         raise InvalidShape(
@@ -71,6 +72,51 @@ def resolve_fan_out(
     )
 
 
+def _in_declared_order(
+    named: tuple[object, ...] | None,
+    keys: list[int],
+    parent_values: dict[str, list[object]],
+) -> tuple[list[int], dict[str, list[object]]]:
+    """Put named parents back in the order the declaration named them.
+
+    **The partition has to be a function of the declaration, and this is what
+    makes it one.** Keys arrive ordered by primary key because that is how they
+    are read, and the sizes below are assigned by *position* -- so without this
+    the weights followed the sort order of values nobody wrote down. With
+    integer keys that is merely surprising; with the UUID keys a factory row has
+    on a modern schema it means **the same shape builds differently every run**.
+    Measured before this existed: one declaration gave the first-named parent 5,
+    11 or 79 rows across twelve builds, because the sort order moved with the
+    keys.
+
+    That is the promise the whole package rests on -- two builds of one shape
+    agree, which is why ``UuidKeys`` derives rather than draws -- so a narrowing
+    that broke it was a defect rather than a preference.
+
+    **The weights are still scattered across positions**, and the reasoning for
+    that survives unchanged: it is a caller's *order* that decides which key
+    lands where, not their key values, so nothing here correlates a parent's key
+    with its child count. What it does mean is that reversing the list is a
+    different declaration, which is what a reader writing one would expect.
+
+    Parent values move with their keys, or a derivation would read the right
+    column off the wrong row.
+    """
+    if named is None:
+        return keys, parent_values
+    # `dict[object, int]` rather than the `list[int]` this module annotates its
+    # keys with, because that annotation is not true: a primary key is whatever
+    # the model declares, and the UUID case is exactly the one this function
+    # exists for. Widening it everywhere is a change of its own; narrowing here
+    # would be a lie that type-checks.
+    position: dict[object, int] = {key: index for index, key in enumerate(keys)}
+    order = [position[key] for key in named]
+    return (
+        [keys[index] for index in order],
+        {name: [values[index] for index in order] for name, values in parent_values.items()},
+    )
+
+
 def _require_every_named_parent(
     named: tuple[object, ...] | None,
     keys: list[int],

django_data_shape-0.16.0/django_data_shape/shape_from_factory.py

@@ -0,0 +1,252 @@
+"""Read what a factory actually produces, and say what it does not."""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from django.apps import apps
+from django.db import DEFAULT_DB_ALIAS, transaction
+from django.db.models import Field, Model
+
+from django_data_shape.invalid_shape import InvalidShape
+
+_MANY_VALUES = 12
+
+
+def shape_from_factory(
+    factory: Callable[..., Model],
+    *,
+    samples: int = 200,
+    defaults: Mapping[str, object] | None = None,
+    using: str = DEFAULT_DB_ALIAS,
+) -> str:
+    """Run a factory, measure what it made, and return a declaration **as source**.
+
+    **Source to read, edit and check in -- never a ``Shape`` to build from**, and
+    that is the whole design rather than a limitation of it. A shape this package
+    builds is *declared*, which is what makes it reviewable and assertable; a
+    shape learned from a sample is neither, and one used directly would change
+    whenever the factory did, silently. So what comes back is text, and a person
+    decides what of it to keep.
+
+    **Because the thing it usually finds is that the factory is flat.** Factories
+    are written for single-object tests, so they fix values: one status, one
+    parent, one count. Measured on exactly that shape, faithful inference emits
+    ``status=Constant('ACTIVE'), company=Constant(1)`` -- the uniform world this
+    package exists to argue against, now with a declaration blessing it. So every
+    such column is reported as a **finding** rather than quietly written down,
+    and the report leads with them.
+
+    **A sub-factory is the sharpest case and the one worth running this for.**
+    ``company = SubFactory(CompanyFactory)`` creates one parent per child, which
+    is a fan-out of degree one: every parent has exactly one row, the average is
+    the truth, and the join estimate cannot miss. It is the single most
+    unrealistic thing a fixture can do and it is invisible in the factory's own
+    source, so it is detected by watching which other tables grew and by how
+    much.
+
+    ``defaults`` is passed to every call, because **most factories in a mature
+    codebase need arguments**. A ``TeamFactory`` wanting a ``permission_role``,
+    called with nothing, leaves a required column empty and fails as a raw
+    ``IntegrityError`` naming a constraint -- which says nothing about what the
+    caller did. Anything the factory raises is caught and named here instead,
+    with the call number, because "it failed" and "it failed after three" are
+    different bugs.
+
+    Nothing is left behind: the calls run inside a transaction that is rolled
+    back, so this can be pointed at a development database without writing to it.
+
+    ``samples`` decides how much of the tail is seen, and the answer moves with
+    it -- fifty runs saw nineteen distinct parents where a thousand saw
+    forty-nine. That is stated in the output rather than hidden, because two
+    people running this at different sizes should not be surprised by two
+    different declarations.
+    """
+    if samples < 2:
+        raise InvalidShape(
+            f"shape_from_factory needs at least two samples to see a shape, got {samples}. "
+            "One row cannot tell a constant from a distribution."
+        )
+    before = _counts(using)
+    made: list[Model] = []
+    arguments = dict(defaults or {})
+    with transaction.atomic(using=using):
+        for index in range(samples):
+            try:
+                row = factory(**arguments)
+            except Exception as error:
+                # Re-raised rather than propagated, because the failure a caller
+                # sees otherwise is a database constraint naming a column, which
+                # describes neither what they ran nor what to do about it. The
+                # driver's own words are kept: unlike a refusal about a
+                # declaration, the column their factory left empty is the whole
+                # of the information, and nothing here retains a generated value.
+                raise InvalidShape(
+                    f"the factory could not be called on call {index + 1} of {samples}: "
+                    f"{type(error).__name__}: {error}. Most factories in a real codebase take "
+                    "arguments and need them -- pass them with defaults={...}, which is handed "
+                    "to every call."
+                ) from error
+            if not isinstance(row, Model):
+                raise InvalidShape(
+                    f"shape_from_factory expects the factory to return a model instance, got "
+                    f"{type(row).__name__}. A factory that returns nothing cannot be measured, "
+                    "because what it made is what is being read."
+                )
+            made.append(row)
+        after = _counts(using)
+        transaction.set_rollback(True, using=using)
+    return _render(made[0].__class__, made, _grown(before, after, made[0].__class__), samples)
+
+
+def _counts(using: str) -> dict[type[Model], int]:
+    """How many rows every model holds, so growth elsewhere can be seen."""
+    return {
+        model: model._base_manager.using(using).count()
+        for config in apps.get_app_configs()
+        for model in config.get_models()
+        if not model._meta.proxy
+    }
+
+
+def _grown(
+    before: dict[type[Model], int], after: dict[type[Model], int], made: type[Model]
+) -> dict[type[Model], int]:
+    return {
+        model: after[model] - before[model]
+        for model in after
+        if model is not made and after[model] != before.get(model, 0)
+    }
+
+
+def _describe(values: list[object], rows: int) -> tuple[str, str | None]:
+    """A declaration for one column, and the finding it deserves if any."""
+    counts = Counter(values)
+    if len(counts) == 1:
+        only = next(iter(counts))
+        return (
+            f"Constant({only!r})",
+            f"every row got {only!r}. The factory fixes this column, so the declaration above "
+            "says the planner will see one value -- decide what the real spread is.",
+        )
+    if len(counts) == rows:
+        return (
+            "Sequential(...)  # every value distinct",
+            "every value was distinct. Sequential fills that cheaply; a unique short code needs "
+            "a generator of its own.",
+        )
+    if len(counts) <= _MANY_VALUES:
+        shares = ", ".join(
+            f"{value!r}: {count / rows:.2f}" for value, count in counts.most_common()
+        )
+        return f"Skew({{{shares}}})", None
+    return (
+        f"Skew({{...}})  # {len(counts)} distinct values, "
+        f"top share {counts.most_common(1)[0][1] / rows:.0%}",
+        f"{len(counts)} distinct values is more than a Skew wants written out. If they are "
+        "evenly spread, Uniform says it in one line; if they are not, keep the head and let the "
+        "tail share a weight.",
+    )
+
+
+def _relation(values: list[object], rows: int) -> tuple[str, str | None]:
+    """A declaration for a foreign key, which is a fan-out and never a draw.
+
+    Its own function rather than a branch in :func:`_describe`, because the
+    answer is a different *kind* of thing. ``Table`` refuses a value
+    distribution on a relation -- it would emit keys drawn from nothing -- so
+    emitting one here would hand back source that cannot be built, which is a
+    worse failure than a wrong number: the reader would take it for a starting
+    point and it is not even a valid one.
+
+    The finding is what matters anyway. A factory reaches a foreign key in one
+    of two unrealistic ways and both come out here: a sub-factory gives every
+    parent exactly one child, and a round-robin gives every parent the same
+    number. Either way the average is the truth and a join over that column
+    cannot be misestimated, which is the defect this package exists to make
+    reproducible.
+    """
+    counts = Counter(values)
+    spread = sorted(counts.values(), reverse=True)
+    parents = len(counts)
+    if parents == 1:
+        return (
+            "FanOut(Zipf()),  # every row pointed at one parent",
+            "every row pointed at the same parent. That is not a fan-out at all -- the column has "
+            "one value, so the planner sees no distribution across the join.",
+        )
+    if spread[0] == spread[-1]:
+        return (
+            f"FanOut(Zipf()),  # was flat: {parents} parents, {spread[0]} row(s) each",
+            f"every one of the {parents} parents got exactly {spread[0]} row(s). A flat fan-out "
+            "is the one shape in which a join estimate cannot miss, because the average is the "
+            "truth -- declare the tail you actually have, and childless= for the parents nobody "
+            "references.",
+        )
+    return (
+        f"FanOut(Zipf()),  # {parents} parents, {spread[0]} at the head and {spread[-1]} at the tail",
+        None,
+    )
+
+
+def _render(
+    model: type[Model], made: list[Model], grown: dict[type[Model], int], samples: int
+) -> str:
+    lines = [
+        f"# Measured from {samples} calls. This is source to read and edit, not a shape to",
+        "# build from: what it found is what your factory does, which is not the same",
+        "# question as what your production data looks like.",
+        "",
+    ]
+    findings: list[str] = []
+    for model_grown, delta in sorted(grown.items(), key=lambda pair: pair[0].__name__):
+        if delta == samples:
+            findings.append(
+                f"{model_grown.__name__} grew by exactly one per call -- a sub-factory. That is a "
+                "fan-out of degree one: every parent has exactly one child, so the average is the "
+                "truth and a join over it cannot be misestimated. It is the most unrealistic "
+                "thing a fixture can do, and nothing in the factory's source says so."
+            )
+        else:
+            findings.append(
+                f"{model_grown.__name__} grew by {delta} over {samples} calls, about "
+                f"{samples / delta:.1f} children per parent."
+            )
+
+    body = [f"Table({model.__name__}, rows=...,"]
+    for field in model._meta.concrete_fields:
+        if field.primary_key:
+            continue
+        values = [getattr(row, _read(field)) for row in made]
+        if field.is_relation:
+            declaration, finding = _relation(values, len(made))
+        else:
+            declaration, finding = _describe(values, len(made))
+        body.append(f"    {field.name}={declaration},")
+        if finding:
+            findings.append(f"{model.__name__}.{field.name}: {finding}")
+    body.append(")")
+
+    if findings:
+        lines.append("# What your factory does not vary, which is what this is for:")
+        lines.extend(f"#   - {finding}" for finding in findings)
+        lines.append("")
+    lines.extend(body)
+    lines.append("")
+    lines.append(
+        f"# Read at {samples} samples. A larger run sees more of the tail, so the numbers above "
+        "move with it."
+    )
+    return "\n".join(lines)
+
+
+def _read(field: Field[Any, Any]) -> str:
+    """The attribute holding this column's value on an unsaved-or-saved instance.
+
+    ``attname`` rather than ``name`` for a relation, so a foreign key is read as
+    the key it stores rather than by fetching the parent -- which would be a
+    query per row and would describe the parent instead of this column.
+    """
+    return field.attname

{django_data_shape-0.14.0 → django_data_shape-0.16.0}/django_data_shape/version.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__: str = "0.14.0"
+__version__: str = "0.16.0"
 
 __all__ = ["__version__"]

{django_data_shape-0.14.0 → django_data_shape-0.16.0}/docs/index.md

@@ -79,6 +79,11 @@ print(result.rows)
   stand in for a fan-out the way it stands in for a scalar. A required relation
   carrying one is refused by name, like any other undeclared required relation.
   A real `db_default` is DDL, so a column carrying one is left to the database.
+- **A factory you already have can be measured, but never learned from.**
+  `shape_from_factory` runs one and returns **source to read and edit** — see
+  [Reading a factory](#reading-a-factory-you-already-have). It never returns a
+  `Shape`, because a shape this package builds is declared, and a declaration
+  learned from a sample is neither reviewable nor stable.
 - **A callable default is refused.** `uuid4` varies per row and `dict` does not,
   and nothing on the field distinguishes them. Declare a distribution instead.
 - **A declaration is read-only once built.** Every rule runs in the constructor,
@@ -171,3 +176,69 @@ declaration from a database or a factory that already exists. The first two are
 for a through table points at the escape hatch that does build one today: a
 `Projection` with your own `sql=`, which can select the pairs already
 deduplicated.
+
+## Reading a factory you already have
+
+```python
+from django_data_shape import shape_from_factory
+
+print(shape_from_factory(ProjectFactory, samples=200))
+```
+
+**Most factories in a real codebase take arguments and need them.** `defaults=`
+is handed to every call:
+
+```python
+print(shape_from_factory(TeamFactory, samples=200, defaults={"permission_role": role}))
+```
+
+Called without them, a factory leaves a required column empty and the database
+answers with a constraint name. That failure is caught and named here instead,
+with the call number — because "it failed" and "it failed after three" are
+different bugs.
+
+It runs the factory, measures what the calls wrote, rolls the transaction back
+and returns **source**. Not a `Shape` — text, for you to read, edit and check
+in.
+
+That is the design and not a limitation of it. A shape this package builds is
+*declared*, which is what makes it reviewable and assertable. A shape learned
+from a sample is neither, and one used directly would change whenever the
+factory did, silently.
+
+### The point is what it finds, not what it writes
+
+Factories are written for single-object tests, so they fix values and they reach
+foreign keys in the two most unrealistic ways there are. Measured faithfully,
+inference would emit `status=Constant('ACTIVE'), company=FanOut(...)` over one
+parent per child — the uniform world this library exists to argue against, now
+with a declaration blessing it. So those are reported as **findings** and the
+report leads with them:
+
+```text
+# What your factory does not vary, which is what this is for:
+#   - Company grew by exactly one per call -- a sub-factory. That is a fan-out of
+#     degree one: every parent has exactly one child, so the average is the truth
+#     and a join over it cannot be misestimated.
+#   - Session.label: every row got 's'. The factory fixes this column, so the
+#     declaration above says the planner will see one value -- decide what the
+#     real spread is.
+```
+
+**A sub-factory is the sharpest case and the reason to run this.**
+`company = SubFactory(CompanyFactory)` creates one parent per child, which is
+invisible in the factory's own source and is the single most unrealistic thing a
+fixture can do. A round-robin over four parents is the same defect wearing a
+different number: every parent gets the same count, so the average is still the
+truth.
+
+A factory that already varies everything gets a declaration and **no findings** —
+if the quiet case were not quiet, the loud one would stop meaning anything.
+
+### What it cannot tell you
+
+The sample size decides how much of the tail is seen, and the answer moves with
+it: fifty runs saw nineteen distinct parents where a thousand saw forty-nine.
+The report says which size produced it. And a column with many distinct values is
+reported as a count and a head share rather than written out — a `Skew` listing
+sixty entries is not a declaration anybody keeps.

{django_data_shape-0.14.0 → django_data_shape-0.16.0}/docs/reference.md

@@ -60,6 +60,8 @@
 
 ::: django_data_shape.scaled_shape.scaled_shape
 
+::: django_data_shape.shape_from_factory.shape_from_factory
+
 ## Derivations
 
 ::: django_data_shape.derivations.derivation.Derivation

{django_data_shape-0.14.0 → django_data_shape-0.16.0}/docs/relations.md

@@ -73,6 +73,16 @@ Table(Session, rows=50, company=FanOut(Constant(1), parents=[tenant.pk]), label=
 
 Real keys, read out of the parent table like any other fan-out — a key that
 matches no row is refused by name rather than quietly taking a smaller share.
+
+**The order you name them in is part of the declaration.** Keys come back from
+the database sorted by primary key, and the weights are assigned by position, so
+they are put back into the order you wrote before anything is weighed. Without
+that the partition followed the *values* of the keys: with the UUID primary keys
+a factory row has, one declaration gave the first-named parent 5, 11 or 79 rows
+across twelve builds. Two builds of one shape have to agree, which is the same
+reason `UuidKeys` derives rather than draws. Reversing the list is therefore a
+different declaration, and weights are still scattered across positions — so
+nothing correlates a parent's key with its child count.
 A **list of keys, never a queryset**: a declaration needs no connection, and
 evaluating a queryset here would give it one. Build the list yourself, which is
 the query you were going to run anyway.

{django_data_shape-0.14.0 → django_data_shape-0.16.0}/pyproject.toml

@@ -170,7 +170,7 @@ skip-magic-trailing-comma = false
 root = ["./django_data_shape"]
 
 [tool.bumpversion]
-current_version = "0.14.0"
+current_version = "0.16.0"
 allow_dirty = false
 commit = false
 tag = false