django-data-shape 0.18.0__tar.gz → 0.19.0__tar.gz

{django_data_shape-0.18.0 → django_data_shape-0.19.0}/CHANGELOG.md

@@ -7,6 +7,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.0] — 2026-09-05
+
+### Added
+
+- **`Paired(..., parents=)`: an edge narrowed to a subset of the partner table.**
+
+  Two through tables over one partner model chose independently -- every
+  mechanism here computes a column from the row index and nothing else -- so
+  they overlapped by construction, and any rule of the form *these two
+  relationships must not overlap* was unsatisfiable however the shape was
+  written. Declared as an invariant, such a rule correctly fired and rolled
+  every build back with nothing a declaration could change.
+
+  The family is larger than it looks: reviewer-is-not-author,
+  approver-is-not-requester, auditor-is-not-audited. It is every
+  separation-of-duties constraint there is.
+
+  It behaves as `FanOut(parents=)` does, which gained the same narrowing in
+  0.13.0 for the same class of problem one primitive over: keys are read through
+  the database as a predicate rather than filtered afterwards, named partners
+  are put back in declaration order so the weights do not follow a sort order
+  nobody wrote down, and a named key matching no row is **refused** rather than
+  silently dropped.
+
+  **Narrowing can make a declaration impossible that was fine over the whole
+  table**, because what binds is the busiest group rather than the product. The
+  existing build-time refusal already says so and now says it about the narrowed
+  set.
+
+- **`Projection(..., values={...})` and `SqlValue`: a projected column of the
+  table's own.**
+
+  A projection copies a column from the source it names or takes the model's
+  own default, and a projected table's **measure** column is neither -- the
+  score on a review, the amount on a generated line, the reading on a sample.
+
+  Leaving it to a model default was legal and was the wrong answer *for this
+  package specifically*: one value across every projected row is
+  `n_distinct = 1`, the exact shape a planner cannot use. A library whose whole
+  purpose is planner realism was building tables it had made unplannable, and
+  the declaration looked correct.
+
+  `sql=` already answered this and answered it expensively -- it replaces the
+  whole `SELECT`, so the join stops being derived from the model graph and can
+  drift from it afterwards, the copied columns are written by hand, and the key
+  strategy has to be spelled in SQL. `values=` gives up none of that:
+
+  ```python
+  Projection(
+      ReviewScore,
+      per=Review,
+      copying=Criterion,
+      values={"score": SqlValue("({per}.id * 31 + {source}.id * 17) % 5 + 1")},
+  )
+  ```
+
+  `{per}` and `{source}` are substituted with the aliases the derived statement
+  uses. They are placeholders rather than the aliases themselves because the
+  aliases are this package's private business.
+
+  **It takes SQL rather than a distribution, and that is a decision.** A
+  `Distribution` computes from `draw(stream, row)`, which is SplitMix64 --
+  expressible in PostgreSQL only through `numeric` modular arithmetic and casts
+  across the sign boundary, where one mistake gives a declaration two meanings
+  depending on which statement filled the table. That is the divergence
+  `SqlKeys` exists to refuse, and it is not worth buying convenience with.
+
+  Declaring an expression for a column the source already carries, or for a
+  column the model does not have, or alongside `sql=`, is refused at declaration
+  time.
+
+  Two things the expression carries that the declaration should not have to. A
+  literal `%` is escaped, because the statement is executed with bound
+  parameters and an unescaped one is an incomplete placeholder to psycopg and to
+  Django's SQLite wrapper alike -- the paramstyle is no more the declaration's
+  business than the join's aliases are. And the expression is the one part of a
+  shape that is **not portable**, which is documented rather than papered over:
+  `mod(x, 5)` is an integer on PostgreSQL and a REAL on SQLite, so `%` is the
+  spelling the examples use.
+
+## [0.18.1] — 2026-09-05
+
+### Fixed
+
+- **`scaled_shape` now multiplies a projection's `max_rows` by the factor.**
+  It passed a `Projection` through untouched, which is right for its *size* --
+  that grows because the tables it reads did -- and wrong for a declared
+  ceiling, which is a number in the same units and did not move. A ceiling sized
+  for the world as written therefore refused every growth assertion, because
+  those build the same declaration at a larger factor.
+
+  The consumer that asked for `max_rows` in 0.18.0 hit this on the first run:
+  10,000 declared against a world of 3,188 rows, and 29,078 at factor 10.
+
+  Multiplying is the arithmetic rather than an approximation of one, and the
+  reason is the same one that makes the size need no factor: every table scales,
+  parents included, so a parent has the same number of children at every factor
+  and the projection is a sum over `factor` times as many parents of an
+  unchanged per-parent product.
+
+  A declaration with no ceiling is still passed through by identity.
+
 ## [0.18.0] — 2026-09-05
 
 ### Added
@@ -1173,7 +1275,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.18.0...HEAD
+[Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.19.0...HEAD
+[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
 [0.18.0]: https://github.com/Artui/django-data-shape/compare/v0.17.1...v0.18.0
 [0.17.1]: https://github.com/Artui/django-data-shape/compare/v0.17.0...v0.17.1
 [0.17.0]: https://github.com/Artui/django-data-shape/compare/v0.16.0...v0.17.0

{django_data_shape-0.18.0 → django_data_shape-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-data-shape
-Version: 0.18.0
+Version: 0.19.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.18.0 → django_data_shape-0.19.0}/django_data_shape/__init__.py

@@ -52,6 +52,7 @@ 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.sql_value import SqlValue
 from django_data_shape.table import Table
 from django_data_shape.table_result import TableResult
 from django_data_shape.template_database import template_database
@@ -98,6 +99,7 @@ __all__ = [
     "ShapeNotEmpty",
     "Skew",
     "SqlKeys",
+    "SqlValue",
     "Table",
     "TableResult",
     "UnhashableShape",

{django_data_shape-0.18.0 → django_data_shape-0.19.0}/django_data_shape/paired.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
+
 from django_data_shape.distributions.distribution import Distribution
 from django_data_shape.invalid_shape import InvalidShape
 
@@ -56,7 +58,13 @@ class Paired:
     derived shape nobody quotes is a shape nobody can check.
     """
 
-    def __init__(self, relation: str, weights: Distribution) -> None:
+    def __init__(
+        self,
+        relation: str,
+        weights: Distribution,
+        *,
+        parents: Sequence[object] | None = None,
+    ) -> None:
         if not isinstance(relation, str) or not relation:
             raise InvalidShape(
                 f"Paired needs the name of the fan-out it is paired with, got {relation!r}. "
@@ -65,6 +73,7 @@ class Paired:
             )
         self._relation = relation
         self._weights = weights
+        self._parents = None if parents is None else tuple(parents)
 
     @property
     def relation(self) -> str:
@@ -74,9 +83,44 @@ class Paired:
     def weights(self) -> Distribution:
         return self._weights
 
+    @property
+    def parents(self) -> tuple[object, ...] | None:
+        """The partner keys this edge may use, or ``None`` for all of them.
+
+        The same narrowing
+        :class:`~django_data_shape.fan_out.FanOut` takes, and it is here for the
+        one thing a fan-out's version cannot do: **two through tables over the
+        same partner model cannot otherwise be made disjoint.**
+
+        Every mechanism in this package computes a column from the row index
+        alone, so two ``Paired`` declarations over one partner table choose
+        independently and overlap by construction. Any rule of the form *these
+        two relationships must not overlap* is then violated however the shape
+        is written -- a reviewer who is also an author, an approver who is also
+        the requester, an auditor auditing their own team. That family is every
+        separation-of-duties constraint there is, and it was inexpressible.
+
+        Narrowing the two sides to disjoint subsets is what makes it
+        expressible, and it is also how the domains themselves work: a venue
+        keeps a reviewer board, an organisation separates approvers from
+        requesters. The declaration says the thing the business already says.
+
+        Keys are read through the database as a predicate rather than filtered
+        afterwards, and a named key matching no row is refused rather than
+        silently dropped -- both for the reasons the fan-out's version gives.
+        """
+        return self._parents
+
     def canonical(self) -> object:
-        """The fan-out it pairs with and the weights over partners. See ``Canonical``."""
-        return (self._relation, self._weights)
+        """The fan-out it pairs with, the weights, and any narrowing. See ``Canonical``.
+
+        ``parents`` is part of the digest because it changes which rows exist:
+        two declarations differing only in their subset build different
+        databases, and a cache key that agreed would serve one for the other.
+        """
+        return (self._relation, self._weights, self._parents)
 
     def __repr__(self) -> str:
-        return f"Paired({self._relation!r}, {self._weights!r})"
+        if self._parents is None:
+            return f"Paired({self._relation!r}, {self._weights!r})"
+        return f"Paired({self._relation!r}, {self._weights!r}, parents={list(self._parents)!r})"

{django_data_shape-0.18.0 → django_data_shape-0.19.0}/django_data_shape/projection.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from collections import Counter
 from collections.abc import Mapping, Sequence
+from copy import copy
 from types import MappingProxyType
 from typing import Any, cast
 
@@ -13,6 +14,7 @@ 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
 from django_data_shape.keys.sql_keys import SqlKeys
+from django_data_shape.sql_value import SqlValue
 from django_data_shape.utils import (
     check_not_inherited,
     check_statistics_target,
@@ -178,6 +180,7 @@ class Projection:
         keys: KeyStrategy | None = None,
         statistics: Mapping[str, int] | None = None,
         max_rows: int | None = None,
+        values: Mapping[str, SqlValue] | None = None,
     ) -> None:
         self._model = model
         self._per = per
@@ -197,6 +200,8 @@ class Projection:
                 "nothing is already refused."
             )
         self._max_rows = max_rows
+        self._values = dict(values or {})
+        self._expressions: tuple[tuple[str, SqlValue], ...] = ()
         self._copied: tuple[tuple[str, str, str], ...] = ()
         self._literals: tuple[tuple[str, object], ...] = ()
         self._columns: tuple[str, ...] = ()
@@ -207,6 +212,16 @@ class Projection:
         # runs it first: under multi-table inheritance ``_meta.concrete_fields``
         # spans two tables and every column decision below would be made about
         # the wrong one.
+        if self._values and sql is not None:
+            # `sql=` is the whole SELECT, so there is nowhere for an expression
+            # to be put and no join for it to be written over. Two ways of
+            # saying one column is the over-determination refused everywhere
+            # else in this package.
+            raise InvalidShape(
+                f"{model.__name__} declares values= and sql= together. `sql=` is the entire "
+                "SELECT the insert reads from, so an expression has nowhere to go -- write it "
+                "into that statement instead."
+            )
         check_not_inherited(model)
         pk_field = primary_key_field(model)
         if sql is None:
@@ -302,6 +317,31 @@ class Projection:
         defaults = tuple(value for _column, value in self._literals)
         return f"{into} {self._select(quote, seed)}", defaults
 
+    def scaled(self, factor: int) -> Projection:
+        """This declaration at another size, which for a projection is its ceiling.
+
+        A projection has no row count to multiply -- its size is
+        ``count(per JOIN copying)``, so scaling the tables it reads scales it
+        without anything being said. ``max_rows`` is different: it is a declared
+        number in the same units as that size, and a ceiling that does not move
+        with the factor fires on the first growth assertion.
+
+        **Multiplying it by the factor is the right arithmetic rather than an
+        approximation of one**, and for the same reason the count needs no
+        factor. ``scaled_shape`` scales *every* table, parents included, so a
+        parent has the same number of children at every factor; the projection
+        is then a sum over ``factor`` times as many parents of an unchanged
+        per-parent product, which is ``factor`` times the original.
+
+        Returns ``self`` when there is no ceiling, so a declaration that did not
+        ask for one keeps the identity it always had here.
+        """
+        if self._max_rows is None:
+            return self
+        scaled = copy(self)
+        scaled._max_rows = self._max_rows * factor
+        return scaled
+
     def count_statement(self, connection: Any) -> tuple[str, tuple[object, ...]]:
         """How many rows the insert would write, without writing them.
 
@@ -346,6 +386,13 @@ class Projection:
         key = cast("SqlKeys", self._keys).key_sql(field_stream(seed, self.db_table, ":key"), row)
         values = [key]
         values.extend(f"{quote(alias)}.{quote(column)}" for _target, alias, column in self._copied)
+        # Between the copied columns and the bound literals, matching the order
+        # `_columns` was built in -- the two lists are one statement and a
+        # disagreement between them would write every column into the wrong slot.
+        values.extend(
+            expression.render(quote(_PER), quote(_SOURCE))
+            for _target, expression in self._expressions
+        )
         values.extend("%s" for _column, _value in self._literals)
         per_link, source_link = self._join
         return (
@@ -404,6 +451,7 @@ class Projection:
         source_pk = _column(primary_key_field(source))
 
         copied: list[tuple[str, str, str]] = []
+        expressions: list[tuple[str, SqlValue]] = []
         literals: list[tuple[str, object]] = []
         callables: list[str] = []
         missing: list[str] = []
@@ -418,6 +466,8 @@ class Projection:
                 copied.append((_column(field), _PER, _column(primary_key_field(per))))
             elif field.is_relation and field.related_model is source:
                 copied.append((_column(field), _SOURCE, source_pk))
+            elif field.name in self._values:
+                expressions.append((_column(field), self._values[field.name]))
             elif field.name in available:
                 copied.append((_column(field), _SOURCE, _column(available[field.name])))
             elif field.has_default() and callable(field.default):
@@ -429,6 +479,21 @@ class Projection:
             else:
                 missing.append(field.name)
 
+        declared = {field.name for field in self._model._meta.concrete_fields}
+        unknown = sorted(set(self._values) - declared)
+        if unknown:
+            raise InvalidShape(
+                f"{self._model.__name__} has no column(s) {', '.join(unknown)}, named in "
+                f"values=. Its columns are: {', '.join(sorted(declared))}."
+            )
+        answered = sorted(name for name in self._values if name in available)
+        if answered:
+            raise InvalidShape(
+                f"{self._model.__name__}.{', '.join(answered)} is named in values= and is also "
+                f"a column {source.__name__} carries under the same name, so the declaration "
+                "says two things about one column. Rename it, or drop it from values= and let "
+                "it be copied."
+            )
         if callables:
             raise InvalidShape(
                 f"{self._model.__name__}.{', '.join(callables)} has a callable default, which "
@@ -446,10 +511,12 @@ class Projection:
             )
 
         self._copied = tuple(copied)
+        self._expressions = tuple(expressions)
         self._literals = tuple(literals)
         self._columns = (
             _column(pk_field),
             *(column for column, _alias, _source in copied),
+            *(column for column, _expression in expressions),
             *(column for column, _value in literals),
         )
 
@@ -555,6 +622,10 @@ class Projection:
             self._columns,
             self._sql,
             self._params,
+            # The expressions decide the values in the columns they fill, so two
+            # declarations differing only here build different databases and a
+            # key that agreed would serve one for the other.
+            tuple((column, expression.canonical()) for column, expression in self._expressions),
             # In the key although it writes no column, because it decides load
             # order and load order reaches the data: a raw statement selecting
             # from a table built before it and after it returns different rows.

{django_data_shape-0.18.0 → django_data_shape-0.19.0}/django_data_shape/resolve_paired.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import math
 import numbers
 from decimal import Decimal
-from typing import Any
+from typing import Any, cast
 
 from django.db.models import Model
 
@@ -52,7 +52,9 @@ def resolve_paired(
     is resolved, so this is the one structural refusal that has to wait for the
     build.
     """
-    keys = _read_partner_keys(partner, connection)
+    keys = _read_partner_keys(partner, connection, paired.parents)
+    _require_every_named_partner(paired.parents, keys, partner, table, field)
+    keys = _in_declared_order(paired.parents, keys)
     sizes = plan.sizes()
     if not keys and rows:
         raise InvalidShape(
@@ -84,23 +86,92 @@ def resolve_paired(
     )
 
 
-def _read_partner_keys(partner: type[Model], connection: Any) -> list[int]:
+def _read_partner_keys(
+    partner: type[Model], connection: Any, named: tuple[object, ...] | None = None
+) -> list[int]:
     """The partner's real keys, queried rather than assumed.
 
     The same correction a fan-out carries: a project may have built the partner
     table with the ORM, so its keys are whatever the sequence handed out and a
     child pointing at ``1..N`` would point at nothing.
+
+    ``named`` narrows through the database as a predicate rather than as a
+    filter applied afterwards, so an edge table pinned to one half of a partner
+    table reads that half instead of every key it is about to ignore. The keys
+    go out as parameters, so a value from a caller never reaches the statement
+    as text.
     """
     pk_column = partner._meta.pk.column
     quote = connection.ops.quote_name
-    with connection.cursor() as cursor:
-        cursor.execute(
+    statement = (
+        f"SELECT {quote(pk_column)} FROM {quote(partner._meta.db_table)} "
+        f"ORDER BY {quote(pk_column)}"
+    )
+    params: tuple[object, ...] = ()
+    if named is not None:
+        placeholders = ", ".join(["%s"] * len(named)) or "NULL"
+        statement = (
             f"SELECT {quote(pk_column)} FROM {quote(partner._meta.db_table)} "
-            f"ORDER BY {quote(pk_column)}"
+            f"WHERE {quote(pk_column)} IN ({placeholders}) ORDER BY {quote(pk_column)}"
         )
+        params = tuple(named)
+    with connection.cursor() as cursor:
+        cursor.execute(statement, params)
         return [row[0] for row in cursor.fetchall()]
 
 
+def _require_every_named_partner(
+    named: tuple[object, ...] | None,
+    keys: list[int],
+    partner: type[Model],
+    table: str,
+    field: str,
+) -> None:
+    """Every key ``parents=`` named has to be a row, or the narrowing is a lie.
+
+    The database does the narrowing, so a key matching nothing simply does not
+    come back -- and the edges that would have used it go to whatever else was
+    named instead, or the table comes out empty if it was the only one. Both are
+    silent, and both produce a world the declaration does not describe.
+
+    The same refusal a fan-out makes, and the likely causes are the same: a key
+    from another test, a factory row that was rolled back, or a list built from
+    a queryset filtered differently from the one in the reader's head. None of
+    them is visible in the shape.
+    """
+    if named is None:
+        return
+    missing = [key for key in named if key not in set(keys)]
+    if not missing:
+        return
+    raise InvalidShape(
+        f"{table}.{field} names partner key(s) {missing!r} in parents=, and "
+        f"{partner.__name__} has no row with them. The narrowing runs in the database, so "
+        "a key that matches nothing is not an error there -- the edges that would have used "
+        "it go to the other named partners, or this table comes out empty. Load the partner "
+        "first, or name keys that exist."
+    )
+
+
+def _in_declared_order(named: tuple[object, ...] | None, keys: list[int]) -> list[int]:
+    """Put named partners back in the order the declaration named them.
+
+    Weights below are assigned by *position*, and keys arrive ordered by primary
+    key because that is how they are read -- so without this the popularity of a
+    partner would follow the sort order of values nobody wrote down. The fan-out
+    carries the same correction for the same reason, and there it was measured:
+    one declaration gave the first-named parent 5, 11 or 79 rows across twelve
+    builds, because the sort order moved with the keys.
+    """
+    if named is None:
+        return keys
+    present = set(keys)
+    # cast rather than a narrowing check: `named` holds whatever key type the
+    # partner's primary key is, and membership in `present` is what proves each
+    # one is a key this table actually read back.
+    return [cast("int", key) for key in named if key in present]
+
+
 def _weights(paired: Paired, keys: list[int], seed: int, table: str, field: str) -> list[float]:
     """A weight per partner, scattered across the key range rather than ordered.
 

{django_data_shape-0.18.0 → django_data_shape-0.19.0}/django_data_shape/scaled_shape.py

@@ -71,14 +71,23 @@ def scaled_shape(shape: Shape, factor: int) -> Shape:
     because a message about a row count the caller never wrote is a message that
     knows more than it says.
 
-    **A :class:`~django_data_shape.projection.Projection` passes through
-    untouched, and needs no factor of its own.** It has no declared row count to
+    **A :class:`~django_data_shape.projection.Projection` needs no factor for
+    its size, and one for its ceiling.** It has no declared row count to
     multiply: its size is ``count(per JOIN copying)``, so scaling the tables it
     reads scales it by exactly the same amount without anything being said.
     That is the determined-not-distributed property paying for itself -- a
     mirroring vocabulary with a row count in it would have needed a rule here,
     and would have had to pick between scaling the count and scaling the thing
     the count was derived from.
+
+    ``max_rows`` **is** multiplied, and the same reasoning is why. A ceiling is
+    a declared number in the same units as that size, so one that stayed put
+    would fire on the first growth assertion -- which is exactly what a consumer
+    hit within a run of asking for the feature. Because every table scales,
+    parents included, a parent has the same number of children at every factor
+    and the projection is a sum over ``factor`` times as many parents of an
+    unchanged per-parent product: linear, so multiplying the ceiling is the
+    arithmetic rather than an approximation of it.
     """
     # A whole number, checked rather than rounded. Rounding would let each table
     # decide its own size at a fractional factor, so two tables in one shape
@@ -94,7 +103,7 @@ def scaled_shape(shape: Shape, factor: int) -> Shape:
 
     try:
         tables = tuple(
-            table
+            table.scaled(factor)
             if isinstance(table, Projection)
             # ``fields`` rather than keyword arguments, because a model may have
             # a column named ``rows`` or ``model``. Everything else is forwarded

django_data_shape-0.19.0/django_data_shape/sql_value.py

@@ -0,0 +1,112 @@
+"""A projected column written as an expression the database evaluates."""
+
+from __future__ import annotations
+
+from django_data_shape.invalid_shape import InvalidShape
+
+_PER_PLACEHOLDER = "{per}"
+_SOURCE_PLACEHOLDER = "{source}"
+
+
+class SqlValue:
+    """One projected column's value, as SQL over the join the projection derives.
+
+    A projection copies a column from the source it names, or takes the model's
+    own default, and those are the only two answers it has. A projected table's
+    **measure** column is neither: the score on a review, the amount on a
+    generated line, the reading on a sample. It belongs to the projected row and
+    to nothing the source carries.
+
+    Leaving it to the model default is legal and is the wrong answer *for this
+    package specifically*: one value across every projected row is
+    ``n_distinct = 1``, which is the exact shape a planner cannot use. A library
+    whose whole purpose is planner realism would then be building a table it had
+    made unplannable, and the declaration would look correct.
+
+    ``sql=`` already answers this and answers it expensively: it replaces the
+    whole ``SELECT``, so the join stops being derived from the model graph and
+    can drift from it afterwards, the copied columns are written out by hand,
+    and the key strategy has to be spelled in SQL. ``values=`` gives up none of
+    that and writes one expression for the one column that needs one::
+
+        Projection(
+            ReviewScore,
+            per=Review,
+            copying=Criterion,
+            values={"score": SqlValue("({per}.id * 31 + {source}.id * 17) % 5 + 1")},
+        )
+
+    ``{per}`` and ``{source}`` are substituted with the aliases the derived
+    statement uses, quoted for the connection. They are placeholders rather than
+    the aliases themselves because the aliases are this package's private
+    business: a declaration that spelled them would break the day they changed,
+    and a reader could not tell which side was which.
+
+    **It is SQL rather than a distribution, and that is a decision worth
+    stating.** A :class:`~django_data_shape.distributions.distribution.Distribution`
+    computes from ``draw(stream, row)``, which is SplitMix64 -- expressible in
+    PostgreSQL only through ``numeric`` modular arithmetic and casts across the
+    sign boundary, where a single mistake gives one declaration two meanings
+    depending on which statement filled the table. That is the divergence
+    :class:`~django_data_shape.keys.sql_keys.SqlKeys` exists to refuse, and it
+    is not worth buying convenience with. An expression the caller wrote is
+    honest about being the caller's.
+
+    **It is the one part of a shape that is not portable, and it cannot be
+    made portable.** Everything else here is a declaration this package
+    compiles per backend; an expression is SQL the database evaluates as
+    written. ``mod(x, 5)`` returns an integer on PostgreSQL and a REAL on
+    SQLite, so one declaration writes ``5`` into one database and ``5.0`` into
+    the other -- which is why the example above uses ``%``, integer on both.
+    Nothing here can detect that: the expression is opaque until the database
+    reads it. Write it for the backend the shape is built on, and cast when it
+    has to be both.
+
+    ``%`` is passed through as the operator, which takes an escape this package
+    applies rather than asking for. The statement is executed with bound
+    parameters, so a literal ``%`` in it is an incomplete placeholder to both
+    psycopg and Django's SQLite wrapper, and the declaration fails at execution
+    with a paramstyle error naming nothing in the shape. The paramstyle is this
+    package's private business for the same reason the join's aliases are: a
+    declaration that spelled it would be spelling how the statement happens to
+    be run.
+
+    The expression is inert data, so a shape holding one still digests.
+    """
+
+    def __init__(self, expression: str) -> None:
+        if not isinstance(expression, str) or not expression.strip():
+            raise InvalidShape(
+                f"SqlValue needs a SQL expression, got {expression!r}. An empty one would "
+                "produce a statement the database refuses, at a point far from the "
+                "declaration that caused it."
+            )
+        self._expression = expression
+
+    @property
+    def expression(self) -> str:
+        return self._expression
+
+    def render(self, per_alias: str, source_alias: str) -> str:
+        """The expression with the join's aliases substituted and ``%`` escaped.
+
+        The escape is last so it also covers a ``%`` inside a quoted alias,
+        and it is unconditional because the statement always carries a
+        parameter sequence -- an empty one is still a sequence, and both
+        drivers interpolate on anything that is not ``None``.
+        """
+        return (
+            self._expression.replace(_PER_PLACEHOLDER, per_alias)
+            .replace(_SOURCE_PLACEHOLDER, source_alias)
+            .replace("%", "%%")
+        )
+
+    def canonical(self) -> object:
+        """The expression itself, which is what decides the rows. See ``Canonical``."""
+        return ("SqlValue", self._expression)
+
+    def __repr__(self) -> str:
+        return f"SqlValue({self._expression!r})"
+
+
+__all__ = ["SqlValue"]

{django_data_shape-0.18.0 → django_data_shape-0.19.0}/django_data_shape/version.py

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