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

{django_data_shape-0.2.0 → django_data_shape-0.3.0}/.github/workflows/tests.yml

@@ -114,8 +114,14 @@ jobs:
         run: uv sync --frozen --all-groups --all-extras --python 3.10
       - name: Name the versions that produced
         run: uv pip list
+      # No coverage gate here either. This job's claim is that the declared
+      # floors resolve and the suite passes against them -- not that every line
+      # runs. It inherited the gate from the default addopts, which went
+      # unnoticed until a test skipped below Django 5.2 left one branch
+      # uncovered and failed a job that was never meant to measure coverage.
+      # One gate, on the Postgres job, is the design.
       - name: Test
-        run: uv run --no-sync pytest
+        run: uv run --no-sync pytest --cov-fail-under=0
 
       # The step above installs every extra, and an extra can hold a shared
       # dependency *above* the floor being claimed -- masking the lie rather

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

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-09-01
+
+### Fixed
+- **A UUID primary key no longer refuses to load.** It was refused outright,
+  which made this package unusable for a whole class of Django project. The
+  reframing is the fix: the design never needed integers, it needed a
+  deterministic injection from row index to key -- which is what lets a foreign
+  key be satisfied without a lookup, what makes a self-referential tree acyclic
+  on the index rather than the value, and what makes two builds of one shape
+  agree. Integers were only the most obvious such function.
+- The primary key is prepared by its own field, like every other value. It did
+  not need to be while keys were always integers, and a UUID works either way
+  because psycopg adapts it -- but a key type needing conversion was stored
+  verbatim, which is the bug already found once on an ordinary column.
+- Two documentation examples were syntax errors -- `...` after keyword arguments,
+  in the README and on the relations page -- and would have failed the moment a
+  reader pasted them.
+- The install line is quoted. `pip install django-data-shape[postgres]` fails in
+  zsh with `no matches found`, which is the default shell on macOS.
+- The README's usage example imports the model it uses, and documents the
+  refusals a first attempt actually meets: PostgreSQL and psycopg 3, integer
+  primary keys, empty tables, and callable model defaults.
+
+### Added
+- **Key strategies.** A table's primary keys come from a deterministic function
+  of the row index rather than from a hard-coded dense `1..N` range. Integer keys
+  count from one, `UUIDField` keys are derived from the seed, and `KeyFunction`
+  declares one for any other type.
+- `SequentialKeys`, `UuidKeys`, `KeyFunction` and the `KeyStrategy` protocol,
+  plus a `keys=` argument on `Table`.
+- A composite primary key is refused by name. It is not among a model's concrete
+  fields, because it has no column of its own, so the package used to raise a
+  bare `StopIteration` from inside itself. The message says `keys=` cannot help
+  either: a strategy maps a row index to one value, and this is arity rather than
+  type.
+- The documentation's Python examples are parsed by the test suite. A docs
+  example is the first code anybody runs, so it gets a guard rather than a
+  convention.
+
 ## [0.2.0] — 2026-09-01
 
 ### Added
@@ -108,7 +147,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.2.0...HEAD
+[Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/Artui/django-data-shape/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Artui/django-data-shape/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/Artui/django-data-shape/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/Artui/django-data-shape/compare/v0.0.0...v0.1.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-data-shape
-Version: 0.2.0
+Version: 0.3.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
@@ -65,9 +65,12 @@ usually is.
 ## Install
 
 ```bash
-pip install django-data-shape[postgres]
+pip install 'django-data-shape[postgres]'
 ```
 
+The quotes are not decoration: zsh globs the brackets and reports
+`no matches found` without them.
+
 ## Use
 
 ```python
@@ -75,6 +78,8 @@ import datetime
 
 from django_data_shape import Sequential, Shape, Skew, Table, Uniform, build
 
+from myapp.models import Order
+
 shape = Shape(
     Table(
         Order,
@@ -99,14 +104,21 @@ It raises on any backend that is not PostgreSQL rather than degrading quietly.
 ## Relations
 
 ```python
-Table(
-    Order,
-    rows=2_000_000,
-    # A distribution, not a number: giving every parent ten children is the one
-    # shape in which the planner is never wrong, because its n_distinct average
-    # is then the truth.
-    company=FanOut(Zipf(1.2), childless=0.35),
-    ...
+from django_data_shape import Constant, FanOut, Shape, Table, Zipf, build
+
+build(
+    Shape(
+        Table(Company, rows=50, name=Constant("acme")),
+        Table(
+            Order,
+            rows=2_000_000,
+            # A distribution, not a number: giving every parent ten children is
+            # the one shape in which the planner is never wrong, because its
+            # n_distinct average is then the truth.
+            company=FanOut(Zipf(1.2), childless=0.35),
+            status=Constant("complete"),
+        ),
+    )
 )
 ```
 
@@ -114,6 +126,23 @@ The parents can be rows this package built or rows your own code did -- their
 real keys are read, not assumed, so the ORM can own the small tables while this
 owns the large ones.
 
+## What it expects, and what it refuses
+
+A declaration that cannot describe a database raises before a row is generated,
+naming the field. In particular:
+
+- **PostgreSQL and psycopg 3.** Rows stream into `COPY FROM STDIN`, which
+  psycopg 2 cannot do without materialising them first. Both are refused by name
+  rather than degraded around.
+- **A key type it can assign.** Integer keys count from one and UUID keys are
+  derived from the seed; anything else is refused rather than guessed, and
+  `keys=KeyFunction(...)` declares one.
+- **Empty tables.** Keys start at 1 on every build, so `build()` checks first and
+  raises rather than colliding partway through.
+- **A callable model default** such as `default=uuid4` must be declared as a
+  distribution: `uuid4` varies per row and `dict` does not, and nothing on the
+  field distinguishes them.
+
 ## Status
 
 Early. Single tables and the model graph. Derived fields, collections copied

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

@@ -25,9 +25,12 @@ usually is.
 ## Install
 
 ```bash
-pip install django-data-shape[postgres]
+pip install 'django-data-shape[postgres]'
 ```
 
+The quotes are not decoration: zsh globs the brackets and reports
+`no matches found` without them.
+
 ## Use
 
 ```python
@@ -35,6 +38,8 @@ import datetime
 
 from django_data_shape import Sequential, Shape, Skew, Table, Uniform, build
 
+from myapp.models import Order
+
 shape = Shape(
     Table(
         Order,
@@ -59,14 +64,21 @@ It raises on any backend that is not PostgreSQL rather than degrading quietly.
 ## Relations
 
 ```python
-Table(
-    Order,
-    rows=2_000_000,
-    # A distribution, not a number: giving every parent ten children is the one
-    # shape in which the planner is never wrong, because its n_distinct average
-    # is then the truth.
-    company=FanOut(Zipf(1.2), childless=0.35),
-    ...
+from django_data_shape import Constant, FanOut, Shape, Table, Zipf, build
+
+build(
+    Shape(
+        Table(Company, rows=50, name=Constant("acme")),
+        Table(
+            Order,
+            rows=2_000_000,
+            # A distribution, not a number: giving every parent ten children is
+            # the one shape in which the planner is never wrong, because its
+            # n_distinct average is then the truth.
+            company=FanOut(Zipf(1.2), childless=0.35),
+            status=Constant("complete"),
+        ),
+    )
 )
 ```
 
@@ -74,6 +86,23 @@ The parents can be rows this package built or rows your own code did -- their
 real keys are read, not assumed, so the ORM can own the small tables while this
 owns the large ones.
 
+## What it expects, and what it refuses
+
+A declaration that cannot describe a database raises before a row is generated,
+naming the field. In particular:
+
+- **PostgreSQL and psycopg 3.** Rows stream into `COPY FROM STDIN`, which
+  psycopg 2 cannot do without materialising them first. Both are refused by name
+  rather than degraded around.
+- **A key type it can assign.** Integer keys count from one and UUID keys are
+  derived from the seed; anything else is refused rather than guessed, and
+  `keys=KeyFunction(...)` declares one.
+- **Empty tables.** Keys start at 1 on every build, so `build()` checks first and
+  raises rather than colliding partway through.
+- **A callable model default** such as `default=uuid4` must be declared as a
+  distribution: `uuid4` varies per row and `dict` does not, and nothing on the
+  field distinguishes them.
+
 ## Status
 
 Early. Single tables and the model graph. Derived fields, collections copied

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

@@ -11,6 +11,10 @@ from django_data_shape.distributions.uniform import Uniform
 from django_data_shape.distributions.zipf import Zipf
 from django_data_shape.fan_out import FanOut
 from django_data_shape.invalid_shape import InvalidShape
+from django_data_shape.keys.key_function import KeyFunction
+from django_data_shape.keys.key_strategy import KeyStrategy
+from django_data_shape.keys.sequential_keys import SequentialKeys
+from django_data_shape.keys.uuid_keys import UuidKeys
 from django_data_shape.shape import Shape
 from django_data_shape.shape_not_empty import ShapeNotEmpty
 from django_data_shape.table import Table
@@ -25,6 +29,10 @@ __all__ = [
     "Distribution",
     "FanOut",
     "InvalidShape",
+    "KeyFunction",
+    "KeyStrategy",
+    "SequentialKeys",
+    "UuidKeys",
     "Sequential",
     "Shape",
     "ShapeNotEmpty",

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

@@ -118,10 +118,13 @@ def _load(connection: Any, table: Table, seed: int, plans: dict[str, FanOutPlan]
     many-to-many edges arrive.
     """
     quote = connection.ops.quote_name
-    pk_column = table.model._meta.pk.column
-    columns = [quote(pk_column)] + [quote(field.column) for _, field in table.columns()]
+    pk_field = table.model._meta.pk
+    columns = [quote(pk_field.column)] + [quote(field.column) for _, field in table.columns()]
     statement = f"COPY {quote(table.db_table)} ({', '.join(columns)}) FROM STDIN"
-    prepare = [field.get_db_prep_save for _, field in table.columns()]
+    # The primary key is prepared like every other value. It did not need to be
+    # while keys were always integers; a UUID key does, and a strategy the
+    # caller wrote could return anything its column accepts.
+    prepare = [pk_field.get_db_prep_save] + [field.get_db_prep_save for _, field in table.columns()]
 
     with connection.cursor() as cursor:
         # ``copy`` is not in Django's WRAP_ERROR_ATTRS, so without this a
@@ -132,13 +135,7 @@ def _load(connection: Any, table: Table, seed: int, plans: dict[str, FanOutPlan]
         with connection.wrap_database_errors, cursor.copy(statement) as copy:
             for row in generate_rows(table, seed, plans):
                 copy.write_row(
-                    (
-                        row[0],
-                        *(
-                            prep(value, connection)
-                            for prep, value in zip(prepare, row[1:], strict=True)
-                        ),
-                    )
+                    tuple(prep(value, connection) for prep, value in zip(prepare, row, strict=True))
                 )
         return int(cursor.rowcount)
 

{django_data_shape-0.2.0 → django_data_shape-0.3.0}/django_data_shape/generate_rows.py

@@ -22,10 +22,12 @@ def generate_rows(
     and nothing here needs an instance, because no ``save`` will run and no
     signal should fire.
 
-    Primary keys are a dense ``1..N`` because this package assigns them, which is
-    what lets a child's foreign key be satisfied without a lookup and what makes
-    a self-referential tree acyclic by construction. It also obliges the caller
-    to reset the sequence afterwards; see ``build``.
+    Primary keys come from the table's key strategy, which is a deterministic
+    function of the row index -- ``row + 1`` for an integer key, a derived UUID
+    for a UUID one, a caller's own function for anything else. Determinism is the
+    requirement, not the integers: it is what lets a child compute its parent's
+    key without a lookup, and what makes a self-referential tree acyclic on the
+    index rather than on the value.
 
     ``plans`` carries the resolved fan-out for each relation column. Resolving
     happens outside this function because it has to read the parent's real keys
@@ -37,6 +39,8 @@ def generate_rows(
     nothing but peak RSS.
     """
     plans = plans or {}
+    keys = table.keys
+    key_stream = field_stream(seed, table.db_table, ":key")
     # Each column is reduced to one callable of the row index before the loop
     # starts. At a million rows the loop body runs a million times per column, so
     # the branch between a fan-out and a value distribution is worth deciding
@@ -53,7 +57,7 @@ def generate_rows(
         )
 
     for row in range(table.rows):
-        yield (row + 1, *(produce(row) for produce in emit))
+        yield (keys.key_for(row, key_stream), *(produce(row) for produce in emit))
 
 
 def _from_distribution(distribution: Distribution, stream: int, row: int) -> object:

django_data_shape-0.3.0/django_data_shape/infer_key_strategy.py

@@ -0,0 +1,27 @@
+"""Choosing a key strategy from the model, when the caller did not."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.db.models import Field, IntegerField, UUIDField
+
+from django_data_shape.keys.key_strategy import KeyStrategy
+from django_data_shape.keys.sequential_keys import SequentialKeys
+from django_data_shape.keys.uuid_keys import UuidKeys
+
+
+def infer_key_strategy(field: Field[Any, Any]) -> KeyStrategy | None:
+    """The obvious strategy for a primary key type, or None if there is none.
+
+    Only the two types where the right answer is unambiguous. Everything else
+    returns None and is refused unless the caller declares a strategy, because
+    inventing values for a semantic column is how a character primary key once
+    got loaded with the strings "1", "2" and "3" -- data the application could
+    never have written, with a whole statistics picture built on top of it.
+    """
+    if isinstance(field, IntegerField):
+        return SequentialKeys()
+    if isinstance(field, UUIDField):
+        return UuidKeys()
+    return None

django_data_shape-0.3.0/django_data_shape/keys/__init__.py

@@ -0,0 +1,8 @@
+"""How a table's primary keys are decided."""
+
+from django_data_shape.keys.key_function import KeyFunction
+from django_data_shape.keys.key_strategy import KeyStrategy
+from django_data_shape.keys.sequential_keys import SequentialKeys
+from django_data_shape.keys.uuid_keys import UuidKeys
+
+__all__ = ["KeyFunction", "KeyStrategy", "SequentialKeys", "UuidKeys"]

django_data_shape-0.3.0/django_data_shape/keys/key_function.py

@@ -0,0 +1,44 @@
+"""Keys from a function the caller supplies."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from django_data_shape.invalid_shape import InvalidShape
+
+
+class KeyFunction:
+    """A caller's own deterministic mapping from row index to key.
+
+    The escape hatch for a key this package cannot infer -- a natural key, a
+    prefixed slug, an external identifier. Integer and UUID primary keys are
+    inferred and need none of this; anything else is declared rather than
+    guessed, because a guessed value in a semantic column is how a character
+    primary key once got loaded with the strings "1", "2" and "3".
+
+    The function must be a pure function of the row index. That is checked on a
+    sample at construction rather than trusted: a key that varies between calls
+    would break reproducibility, and it would break it silently, in the one
+    column every foreign key points at.
+    """
+
+    def __init__(self, function: Callable[[int], object], *, sample: int = 64) -> None:
+        first = [function(row) for row in range(sample)]
+        if [function(row) for row in range(sample)] != first:
+            raise InvalidShape(
+                "KeyFunction must be a pure function of the row index, and this one returned "
+                "different keys for the same rows on a second call. A key that varies between "
+                "calls breaks reproducibility in the column every foreign key points at."
+            )
+        if len(set(first)) != len(first):
+            raise InvalidShape(
+                f"KeyFunction produced duplicate keys within its first {sample} rows, and a "
+                "primary key has to be unique. It must be an injection from the row index."
+            )
+        self._function = function
+
+    def key_for(self, row: int, stream: int) -> object:
+        return self._function(row)
+
+    def __repr__(self) -> str:
+        return f"KeyFunction({getattr(self._function, '__name__', self._function)!r})"

django_data_shape-0.3.0/django_data_shape/keys/key_strategy.py

@@ -0,0 +1,29 @@
+"""How a table's primary keys are decided."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class KeyStrategy(Protocol):
+    """Turns a row index into that row's primary key.
+
+    The generalisation of what used to be a hard-coded dense ``1..N`` range. The
+    range was never the requirement: what the design actually rests on is that
+    the key is a **deterministic function of the row index**, and integers were
+    only the most obvious such function.
+
+    Everything the dense range bought is bought by determinism instead. A child
+    can compute its parent's key from the parent's *index*, so a foreign key is
+    satisfied without a lookup whatever the key type. A self-referential tree is
+    acyclic because ``parent_index < child_index`` holds on the index, not on the
+    value. And two builds of one shape agree because the same seed produces the
+    same keys.
+
+    ``stream`` is a per-table value derived from the seed, so a strategy that
+    needs entropy has some. One that does not -- a counter, or a caller's own
+    function -- ignores it, exactly as a positional distribution ignores its
+    draw.
+    """
+
+    def key_for(self, row: int, stream: int) -> object: ...

django_data_shape-0.3.0/django_data_shape/keys/sequential_keys.py

@@ -0,0 +1,22 @@
+"""Dense integer keys, counting from one."""
+
+from __future__ import annotations
+
+
+class SequentialKeys:
+    """``row + 1``: the default for any integer primary key.
+
+    Counting from one rather than zero because that is what a database sequence
+    does, and a test database whose keys start at zero is subtly unlike every
+    other one the reader has seen.
+
+    This is the strategy that obliges the sequence reset after loading. It is
+    also the only one that does: a key type with no sequence behind it has
+    nothing to move.
+    """
+
+    def key_for(self, row: int, stream: int) -> object:
+        return row + 1
+
+    def __repr__(self) -> str:
+        return "SequentialKeys()"

django_data_shape-0.3.0/django_data_shape/keys/uuid_keys.py

@@ -0,0 +1,37 @@
+"""Version-4 shaped UUID keys, derived rather than random."""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+
+
+class UuidKeys:
+    """A UUID per row, deterministic in the seed and the row index.
+
+    Derived from a hash rather than drawn from ``uuid4`` for the reason the
+    whole package is built around: two builds of one shape have to agree, and a
+    random key would make the primary key -- and therefore every foreign key
+    pointing at it -- differ between runs.
+
+    A full 128 bits from the digest, not a float draw. A draw carries 53 bits,
+    which sounds ample until birthday collisions arrive around ninety million
+    rows; a table that large is exactly the kind this package exists to build.
+
+    The version and variant bits are stamped so the result is a well-formed
+    version 4 UUID. Applications store v4 keys, so a test database holding
+    something that merely looks UUID-shaped would be unlike the thing it stands
+    in for.
+    """
+
+    def key_for(self, row: int, stream: int) -> object:
+        digest = hashlib.blake2b(
+            stream.to_bytes(8, "big") + row.to_bytes(8, "big"), digest_size=16
+        ).digest()
+        raw = bytearray(digest)
+        raw[6] = (raw[6] & 0x0F) | 0x40
+        raw[8] = (raw[8] & 0x3F) | 0x80
+        return uuid.UUID(bytes=bytes(raw))
+
+    def __repr__(self) -> str:
+        return "UuidKeys()"

{django_data_shape-0.2.0 → django_data_shape-0.3.0}/django_data_shape/table.py

@@ -6,14 +6,16 @@ from collections.abc import Mapping
 from types import MappingProxyType
 from typing import Any, cast
 
-from django.db.models import Field, IntegerField, Model
+from django.db.models import Field, Model
 from django.db.models.fields import NOT_PROVIDED
 
 from django_data_shape.distributions.bounded import Bounded
 from django_data_shape.distributions.constant import Constant
 from django_data_shape.distributions.distribution import Distribution
 from django_data_shape.fan_out import FanOut
+from django_data_shape.infer_key_strategy import infer_key_strategy
 from django_data_shape.invalid_shape import InvalidShape
+from django_data_shape.keys.key_strategy import KeyStrategy
 
 
 class Table:
@@ -38,6 +40,7 @@ class Table:
         model: type[Model],
         rows: int,
         fields: Mapping[str, Distribution | FanOut] | None = None,
+        keys: KeyStrategy | None = None,
         **field_distributions: Distribution | FanOut,
     ) -> None:
         if rows < 0:
@@ -55,6 +58,7 @@ class Table:
         self._model = model
         self._rows = rows
         self._fields = declared
+        self._keys = keys
         self._validate()
 
     # Read-only, because every rule in this class is enforced once, in
@@ -70,6 +74,15 @@ class Table:
     def rows(self) -> int:
         return self._rows
 
+    @property
+    def keys(self) -> KeyStrategy:
+        """How this table's primary keys are decided.
+
+        Never None by the time anyone can read it: _validate either inferred a
+        strategy from the primary key's type or refused the declaration.
+        """
+        return cast("KeyStrategy", self._keys)
+
     @property
     def fields(self) -> Mapping[str, Distribution | FanOut]:
         """The declared distributions, including defaults filled in from the model."""
@@ -114,21 +127,27 @@ class Table:
                 f"Its concrete fields are: {', '.join(sorted(known))}."
             )
 
-        pk_fields = [field for field in known.values() if field.primary_key]
-        for field in pk_fields:
-            # The dense 1..N range this package assigns is integers, and nothing
-            # downstream converts it. Given a CharField primary key the load
-            # used to succeed and write "1", "2", "3" -- values the application
-            # could never produce, with a whole statistics picture built on top
-            # of them. Refusing is the only honest answer until a key strategy
-            # can be declared per table.
-            if not isinstance(field, IntegerField):
-                raise InvalidShape(
-                    f"{self.model.__name__}.{field.name} is a "
-                    f"{type(field).__name__} primary key, and this package assigns primary keys "
-                    "itself as a dense 1..N integer range. Only integer primary keys are "
-                    "supported."
-                )
+        pk_field = next((field for field in known.values() if field.primary_key), None)
+        if pk_field is None:
+            # A composite primary key is not among the concrete fields, because
+            # it has no column of its own. Without this the package raised a
+            # bare StopIteration from inside itself, which says nothing about
+            # what the caller did.
+            raise InvalidShape(
+                f"{self.model.__name__} has a composite primary key, which this package cannot "
+                "assign. A key strategy maps a row index to one value and a composite key is "
+                "several columns, so keys= cannot help either: this is arity, not type."
+            )
+        if self._keys is None:
+            self._keys = infer_key_strategy(pk_field)
+        if self._keys is None:
+            raise InvalidShape(
+                f"{self.model.__name__}.{pk_field.name} is a {type(pk_field).__name__} primary "
+                "key, and only integer and UUID keys are inferred. Pass keys= with a strategy "
+                "for it -- KeyFunction takes any deterministic function of the row index. "
+                "Inventing values for a key column is how a character primary key once got "
+                'loaded with the strings "1", "2" and "3".'
+            )
 
         pk_names = {name for name, field in known.items() if field.primary_key}
         declared_pk = sorted(pk_names & set(self.fields))

{django_data_shape-0.2.0 → django_data_shape-0.3.0}/django_data_shape/version.py

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

{django_data_shape-0.2.0 → django_data_shape-0.3.0}/docs/index.md

@@ -58,13 +58,14 @@ print(result.rows)
 
 ## What it decides for you
 
-- **Primary keys are assigned here**, as a dense `1..N` range. That is what will
-  let a foreign key be satisfied without a lookup when relations land, and what
-  makes a self-referential tree acyclic by construction. The identity sequence is
-  moved past them afterwards, so the first `objects.create()` in your test does
-  not collide with a key that already exists. Only integer primary keys are
-  supported, and a model with any other kind is refused rather than filled with
-  numbers in a character column.
+- **Primary keys are assigned here**, by a *key strategy*: a deterministic
+  function of the row index. Integer keys count from one and the identity
+  sequence is moved past them afterwards; UUID keys are derived from the seed, so
+  two builds of one shape agree. Determinism is the requirement, not integers --
+  it is what lets a foreign key be satisfied without a lookup and what makes a
+  self-referential tree acyclic. A key type with no obvious strategy is refused
+  rather than guessed, and `keys=KeyFunction(...)` declares one. See
+  [Keys](keys.md).
 - **Every value goes through its field's `get_db_prep_save`.** Without it a naive
   datetime lands in the database verbatim rather than localised, which under a
   non-UTC `TIME_ZONE` is hours from where `save()` would have put it, and a