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

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

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] — 2026-09-05
+
+### Added
+
+- **A lone `%` in a `sql=` statement is refused at declaration time.** The
+  statement is run with its parameters, and an empty parameter sequence is still
+  a sequence, so a `%` that is not a placeholder is read as the start of one:
+  the failure came from `psycopg/cursor.py` at build time, naming the driver and
+  nothing about the shape. A caller who passed no parameters at all had no model
+  that explained it, and the modulo operator is the reason anyone writes a bare
+  `%` in the first place.
+
+  A valid statement can never contain one, so nothing legal is refused -- which
+  is the whole reason this can be a refusal rather than an escape. `sql=` takes
+  `params=`, so pyformat is its interface and `%%` stays the spelling for the
+  operator.
+
+  `SqlValue` on the derived path escapes instead, and the two are not
+  inconsistent: there the caller supplies no parameters and has no reason to
+  know one exists. Both docstrings and the projections guide now say which is
+  which, at both call sites, because the asymmetry is exactly what a reader
+  finding one of them will next be confused by.
+
 ## [0.19.0] — 2026-09-05
 
 ### Added
@@ -1275,7 +1298,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.19.0...HEAD
+[Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.20.0...HEAD
+[0.20.0]: https://github.com/Artui/django-data-shape/compare/v0.19.0...v0.20.0
 [0.19.0]: https://github.com/Artui/django-data-shape/compare/v0.18.1...v0.19.0
 [0.18.1]: https://github.com/Artui/django-data-shape/compare/v0.18.0...v0.18.1
 [0.18.0]: https://github.com/Artui/django-data-shape/compare/v0.17.1...v0.18.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-data-shape
-Version: 0.19.0
+Version: 0.20.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.19.0 → django_data_shape-0.20.0}/django_data_shape/projection.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 from collections import Counter
 from collections.abc import Mapping, Sequence
 from copy import copy
@@ -29,6 +30,12 @@ from django_data_shape.utils import (
 _PER = "per"
 _SOURCE = "src"
 
+# Every pyformat shape psycopg 3 and Django's SQLite wrapper accept: a doubled
+# `%%`, a positional placeholder (psycopg also takes `%b` and `%t`), and a named
+# one. Written as what is *allowed* rather than as what is wrong, because the
+# set of legal placeholders is short and closed and the set of mistakes is not.
+_PLACEHOLDER = re.compile(r"%(?:%|[sbt]|\([^)]*\)[sbt])")
+
 
 class Projection:
     """One row per pair, copied along a join, by ``INSERT ... SELECT``.
@@ -543,6 +550,7 @@ class Projection:
                 "what this package would use to write the key column, and here the statement "
                 f"writes it: put {pk_field.name} in columns= and produce it in the select."
             )
+        _refuse_a_lone_percent(self._model, cast("str", self._sql))
         if columns is None:
             raise InvalidShape(
                 f"{self._model.__name__} declares sql= without columns=. The select's columns "
@@ -647,6 +655,42 @@ class Projection:
         )
 
 
+def _refuse_a_lone_percent(model: type[Model], sql: str) -> None:
+    """Refuse a ``%`` that is neither a placeholder nor doubled, here rather than at build.
+
+    ``sql=`` is a **parameterised** statement -- the caller writes ``%s`` and
+    passes ``params=``, which is the documented interface -- so pyformat is part
+    of that contract and a literal ``%`` has to be doubled. That is correct and
+    is not what this refusal changes.
+
+    What it changes is where the mistake surfaces. The statement reaches the
+    driver with a parameter sequence, and an empty sequence is still a sequence,
+    so an unescaped ``%`` is an incomplete placeholder: the exception comes from
+    ``psycopg/cursor.py``, at build time, naming nothing in the shape. A caller
+    who passed no parameters at all has no model that explains it, and the
+    modulo operator is the reason anyone writes a bare ``%`` in the first place.
+
+    A valid statement can never contain one, so nothing legal is refused -- the
+    check is the whole reason this can be a refusal rather than an escape.
+    ``SqlValue`` on the derived path *does* escape, and the two are not
+    inconsistent: there the caller supplies no parameters and has no reason to
+    know one exists.
+    """
+    position = 0
+    while (found := sql.find("%", position)) != -1:
+        placeholder = _PLACEHOLDER.match(sql, found)
+        if placeholder is None:
+            raise InvalidShape(
+                f"{model.__name__} declares sql= containing a lone '%' in "
+                f"{sql[max(0, found - 12) : found + 8].strip()!r}. The statement is run with "
+                "its parameters, so a '%' that is not a placeholder is read as the start of "
+                "one and the driver refuses it far from here. Write '%%' for the modulo "
+                "operator. (A derived projection's SqlValue needs no escaping, because there "
+                "you supply no parameters and the package escapes for you.)"
+            )
+        position = placeholder.end()
+
+
 def _addressable(model: type[Model]) -> dict[str, Field[Any, Any]]:
     """Every concrete field under both names a caller might reasonably use.
 

{django_data_shape-0.19.0 → django_data_shape-0.20.0}/django_data_shape/sql_value.py

@@ -63,7 +63,8 @@ class SqlValue:
     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
+    applies rather than asking for -- unlike ``sql=``, which takes ``params=``
+    and so owns its own placeholders; a lone ``%`` is refused there instead. 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

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

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

{django_data_shape-0.19.0 → django_data_shape-0.20.0}/docs/projections.md

@@ -299,6 +299,28 @@ package owns the keys, and a statement it did not write has to say what they are
 rather than leave them to a sequence whose current value is not part of any
 declaration.
 
+### One thing is inspected: a lone `%`
+
+The statement is run **with its parameters**, and an empty parameter sequence is
+still a sequence — so a `%` that is not a placeholder is read as the start of one
+and the driver refuses it, at build time, with a message naming `psycopg` and
+nothing about the shape. Write `%%` for the modulo operator:
+
+```python
+sql = "SELECT row_number() OVER (ORDER BY e.id), e.id, e.id %% 5 FROM app_event e"
+```
+
+That is the pyformat contract and it is deliberate here: `sql=` takes `params=`,
+so the placeholders are the interface. The declaration is checked for a lone `%`
+only so the refusal arrives where the mistake is, rather than one layer down. A
+valid statement can never contain one, so nothing legal is refused.
+
+`SqlValue` on the derived path is the other way round and that is not an
+inconsistency: there you supply no parameters and have no reason to know one
+exists, so `%` is escaped for you. The rule is the same in both places — the
+paramstyle belongs to whoever wrote the statement, and on the derived path that
+is this package.
+
 Nothing else about the select is inspected — that is what an escape hatch is —
 but the build still gives it the emptiness check, the sequence reset, the
 `ANALYZE` and the transaction.

{django_data_shape-0.19.0 → django_data_shape-0.20.0}/pyproject.toml

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

django_data_shape-0.20.0/tests/test_projection_sql_percent.py

@@ -0,0 +1,98 @@
+"""A lone ``%`` in a supplied select, refused where the declaration is.
+
+``sql=`` is a parameterised statement -- the caller writes ``%s`` and passes
+``params=``, which is the documented interface -- so pyformat is part of that
+contract and a literal ``%`` has to be doubled. That is correct and stays.
+
+What was wrong is where it was discovered. The statement reaches the driver with
+a parameter sequence, so an unescaped ``%`` is an incomplete placeholder, and
+the exception comes from ``psycopg/cursor.py`` at build time naming nothing in
+the shape. A caller who passed no parameters at all has no model that explains
+it.
+
+The asymmetry with ``SqlValue`` is deliberate and the refusal says so: on the
+derived path the caller supplies no parameters and has no reason to know one
+exists, so ``render()`` escapes for them.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from django_data_shape import Constant, FanOut, InvalidShape, Projection, Shape, Table, Uniform
+from tests.testapp.models import Event, EventSession, Template
+
+pytestmark = pytest.mark.django_db
+
+
+def _projection(sql: str, params: tuple[object, ...] = ()) -> Projection:
+    return Projection(
+        EventSession,
+        columns=("id", "event", "title"),
+        sql=sql,
+        params=params,
+        reads=(Event,),
+    )
+
+
+def test_a_lone_percent_is_refused_at_declaration_time() -> None:
+    with pytest.raises(InvalidShape) as caught:
+        _projection("SELECT e.id, e.id, e.name FROM testapp_event e WHERE e.id % 5 = 0")
+
+    message = str(caught.value)
+    assert "EventSession" in message, "the refusal has to name the declaration"
+    assert "%%" in message, "and say what to write instead"
+    # Named, so the refusal cannot be mistaken for a complaint about the
+    # placeholders the same statement is allowed to carry.
+    assert "e.id % 5" in message
+
+
+def test_the_refusal_explains_why_sqlvalue_differs() -> None:
+    """The asymmetry is the thing a reader will next be confused by."""
+    with pytest.raises(InvalidShape) as caught:
+        _projection("SELECT e.id, e.id, e.name FROM testapp_event e WHERE e.id % 5 = 0")
+
+    assert "SqlValue" in str(caught.value)
+
+
+@pytest.mark.parametrize(
+    "fragment",
+    [
+        "e.name <> %s",
+        "e.name <> %(name)s",
+        "e.name <> %s AND e.id % 5 = 0",
+    ],
+)
+def test_a_placeholder_is_not_a_lone_percent(fragment: str) -> None:
+    """Every pyformat shape survives, including one beside a doubled operator."""
+    sql = f"SELECT e.id, e.id, e.name FROM testapp_event e WHERE {fragment.replace('% 5', '%% 5')}"
+    params = ("x",) if "%s" in fragment or "%(name)s" in fragment else ()
+
+    projection = _projection(sql, params)
+
+    assert projection.model is EventSession
+
+
+def test_a_doubled_percent_still_reaches_the_database_as_an_operator() -> None:
+    """The refusal teaches a spelling that has to work, so it is run."""
+    shape = Shape(
+        Table(Template, rows=3, name=Constant("t")),
+        Table(Event, rows=12, template=FanOut(Uniform(1, 3)), name=Constant("e")),
+        Projection(
+            EventSession,
+            columns=("id", "event", "title", "minutes", "channel"),
+            sql=(
+                "SELECT row_number() OVER (ORDER BY e.id), e.id, "
+                "cast(e.id %% 5 AS varchar(200)), 30, 'web' FROM testapp_event e"
+            ),
+            reads=(Event,),
+        ),
+        seed=5,
+    )
+
+    from django_data_shape import build
+
+    build(shape, require_statistics=False)
+
+    titles = {title for title in EventSession.objects.values_list("title", flat=True)}
+    assert len(titles) > 1, "the operator has to have run, not been sent as a placeholder"