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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (180) hide show
  1. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/CHANGELOG.md +106 -1
  2. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/PKG-INFO +1 -1
  3. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/__init__.py +2 -0
  4. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/paired.py +48 -4
  5. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/projection.py +89 -0
  6. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/resolve_paired.py +77 -6
  7. django_data_shape-0.20.0/django_data_shape/sql_value.py +113 -0
  8. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/version.py +1 -1
  9. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/projections.md +77 -0
  10. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/reference.md +2 -0
  11. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/relations.md +53 -0
  12. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/pyproject.toml +1 -1
  13. django_data_shape-0.20.0/tests/test_paired_parents.py +147 -0
  14. django_data_shape-0.20.0/tests/test_projection_sql_percent.py +98 -0
  15. django_data_shape-0.20.0/tests/test_projection_values.py +153 -0
  16. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.github/CODEOWNERS +0 -0
  17. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.github/SECURITY.md +0 -0
  18. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.github/dependabot.yml +0 -0
  19. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.github/workflows/release.yml +0 -0
  20. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.github/workflows/tests.yml +0 -0
  21. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.github/workflows/upstream-drift.yml +0 -0
  22. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.gitignore +0 -0
  23. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.pre-commit-config.yaml +0 -0
  24. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/CLAUDE.md +0 -0
  25. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/LICENSE +0 -0
  26. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/Makefile +0 -0
  27. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/README.md +0 -0
  28. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/apply_statistics_targets.py +0 -0
  29. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/build.py +0 -0
  30. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/build_result.py +0 -0
  31. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/canonical.py +0 -0
  32. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/check_constraints.py +0 -0
  33. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/check_invariants.py +0 -0
  34. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/children_per_parent.py +0 -0
  35. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/clone_database.py +0 -0
  36. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivation_queried_database.py +0 -0
  37. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/__init__.py +0 -0
  38. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/after.py +0 -0
  39. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/aligned.py +0 -0
  40. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/copied.py +0 -0
  41. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/derivation.py +0 -0
  42. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/derived.py +0 -0
  43. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/given.py +0 -0
  44. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/offset.py +0 -0
  45. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/per_parent.py +0 -0
  46. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/product.py +0 -0
  47. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/scope.py +0 -0
  48. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/__init__.py +0 -0
  49. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/ascending.py +0 -0
  50. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/bounded.py +0 -0
  51. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/categorical.py +0 -0
  52. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/constant.py +0 -0
  53. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/distinct.py +0 -0
  54. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/distribution.py +0 -0
  55. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/sequential.py +0 -0
  56. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/skew.py +0 -0
  57. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/uniform.py +0 -0
  58. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/zipf.py +0 -0
  59. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/drop_database.py +0 -0
  60. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fan_out.py +0 -0
  61. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fan_out_plan.py +0 -0
  62. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fan_out_sizes.py +0 -0
  63. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fixtures/__init__.py +0 -0
  64. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fixtures/scale_fixture.py +0 -0
  65. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fixtures/shape_fixture.py +0 -0
  66. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fixtures/skip_unless_postgres.py +0 -0
  67. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/generate_rows.py +0 -0
  68. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/infer_key_strategy.py +0 -0
  69. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/invalid_shape.py +0 -0
  70. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/invariant.py +0 -0
  71. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/invariant_violated.py +0 -0
  72. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/__init__.py +0 -0
  73. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/disjoint.py +0 -0
  74. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/key_function.py +0 -0
  75. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/key_strategy.py +0 -0
  76. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/md5_keys.py +0 -0
  77. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/sequential_keys.py +0 -0
  78. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/sql_keys.py +0 -0
  79. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/uuid_keys.py +0 -0
  80. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/order_derivations.py +0 -0
  81. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/order_tables.py +0 -0
  82. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/paired_plan.py +0 -0
  83. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/py.typed +0 -0
  84. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/refuse_queries.py +0 -0
  85. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/require_clone_strategy.py +0 -0
  86. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/require_postgres.py +0 -0
  87. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/resolve_fan_out.py +0 -0
  88. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/scale_protocol.py +0 -0
  89. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/scaled_shape.py +0 -0
  90. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/scaled_world.py +0 -0
  91. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/shape.py +0 -0
  92. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/shape_digest.py +0 -0
  93. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/shape_from_factory.py +0 -0
  94. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/shape_not_empty.py +0 -0
  95. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/table.py +0 -0
  96. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/table_result.py +0 -0
  97. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/template_database.py +0 -0
  98. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/unhashable_shape.py +0 -0
  99. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/unsupported_backend.py +0 -0
  100. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/utils.py +0 -0
  101. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/world_changed.py +0 -0
  102. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/derivations.md +0 -0
  103. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/index.md +0 -0
  104. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/invariants.md +0 -0
  105. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/keys.md +0 -0
  106. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/pytest.md +0 -0
  107. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/statistics.md +0 -0
  108. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/mkdocs.yml +0 -0
  109. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/scripts/check-changelog +0 -0
  110. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/scripts/release-publish.sh +0 -0
  111. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/__init__.py +0 -0
  112. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/conftest.py +0 -0
  113. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/conftest_settings.py +0 -0
  114. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/__init__.py +0 -0
  115. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_after.py +0 -0
  116. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_after_units.py +0 -0
  117. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_aligned.py +0 -0
  118. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_canonical_arithmetic.py +0 -0
  119. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_derived.py +0 -0
  120. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_given.py +0 -0
  121. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_per_parent.py +0 -0
  122. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/distributions/__init__.py +0 -0
  123. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/distributions/test_constant.py +0 -0
  124. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/distributions/test_sequential.py +0 -0
  125. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/distributions/test_skew.py +0 -0
  126. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/distributions/test_uniform.py +0 -0
  127. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/distributions/test_zipf.py +0 -0
  128. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/keys/__init__.py +0 -0
  129. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/keys/test_key_function.py +0 -0
  130. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/keys/test_md5_keys.py +0 -0
  131. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/keys/test_sequential_keys.py +0 -0
  132. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/keys/test_uuid_keys.py +0 -0
  133. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/scale_protocol_consumers.py +0 -0
  134. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/scale_protocol_impostors.py +0 -0
  135. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_apply_statistics_targets.py +0 -0
  136. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build.py +0 -0
  137. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_derivations.py +0 -0
  138. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_graph.py +0 -0
  139. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_invariants.py +0 -0
  140. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_keys.py +0 -0
  141. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_m2m.py +0 -0
  142. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_portable.py +0 -0
  143. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_projection.py +0 -0
  144. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_check_constraints.py +0 -0
  145. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_children_per_parent.py +0 -0
  146. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_documentation.py +0 -0
  147. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_fan_out.py +0 -0
  148. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_fan_out_sizes.py +0 -0
  149. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_fixtures.py +0 -0
  150. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_generate_rows.py +0 -0
  151. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_infer_key_strategy.py +0 -0
  152. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_invariant.py +0 -0
  153. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_order_derivations.py +0 -0
  154. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_order_tables.py +0 -0
  155. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_paired.py +0 -0
  156. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_paired_plan.py +0 -0
  157. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_projection.py +0 -0
  158. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_projection_ceiling.py +0 -0
  159. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_reference_documents_the_public_surface.py +0 -0
  160. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_refuse_queries.py +0 -0
  161. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_require_clone_strategy.py +0 -0
  162. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_require_postgres.py +0 -0
  163. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_resolve_fan_out.py +0 -0
  164. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_resolve_paired.py +0 -0
  165. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_scale_protocol.py +0 -0
  166. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_scaled_projection_ceiling.py +0 -0
  167. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_scaled_shape.py +0 -0
  168. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_scaled_world.py +0 -0
  169. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_scaled_world_over_a_session_world.py +0 -0
  170. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_scaled_world_restores_sequences.py +0 -0
  171. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_shape.py +0 -0
  172. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_shape_digest.py +0 -0
  173. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_shape_from_factory.py +0 -0
  174. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_table.py +0 -0
  175. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_template_database.py +0 -0
  176. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_utils.py +0 -0
  177. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_version.py +0 -0
  178. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/testapp/__init__.py +0 -0
  179. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/testapp/models.py +0 -0
  180. {django_data_shape-0.18.1 → django_data_shape-0.20.0}/uv.lock +0 -0
@@ -7,6 +7,109 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.20.0] — 2026-09-05
11
+
12
+ ### Added
13
+
14
+ - **A lone `%` in a `sql=` statement is refused at declaration time.** The
15
+ statement is run with its parameters, and an empty parameter sequence is still
16
+ a sequence, so a `%` that is not a placeholder is read as the start of one:
17
+ the failure came from `psycopg/cursor.py` at build time, naming the driver and
18
+ nothing about the shape. A caller who passed no parameters at all had no model
19
+ that explained it, and the modulo operator is the reason anyone writes a bare
20
+ `%` in the first place.
21
+
22
+ A valid statement can never contain one, so nothing legal is refused -- which
23
+ is the whole reason this can be a refusal rather than an escape. `sql=` takes
24
+ `params=`, so pyformat is its interface and `%%` stays the spelling for the
25
+ operator.
26
+
27
+ `SqlValue` on the derived path escapes instead, and the two are not
28
+ inconsistent: there the caller supplies no parameters and has no reason to
29
+ know one exists. Both docstrings and the projections guide now say which is
30
+ which, at both call sites, because the asymmetry is exactly what a reader
31
+ finding one of them will next be confused by.
32
+
33
+ ## [0.19.0] — 2026-09-05
34
+
35
+ ### Added
36
+
37
+ - **`Paired(..., parents=)`: an edge narrowed to a subset of the partner table.**
38
+
39
+ Two through tables over one partner model chose independently -- every
40
+ mechanism here computes a column from the row index and nothing else -- so
41
+ they overlapped by construction, and any rule of the form *these two
42
+ relationships must not overlap* was unsatisfiable however the shape was
43
+ written. Declared as an invariant, such a rule correctly fired and rolled
44
+ every build back with nothing a declaration could change.
45
+
46
+ The family is larger than it looks: reviewer-is-not-author,
47
+ approver-is-not-requester, auditor-is-not-audited. It is every
48
+ separation-of-duties constraint there is.
49
+
50
+ It behaves as `FanOut(parents=)` does, which gained the same narrowing in
51
+ 0.13.0 for the same class of problem one primitive over: keys are read through
52
+ the database as a predicate rather than filtered afterwards, named partners
53
+ are put back in declaration order so the weights do not follow a sort order
54
+ nobody wrote down, and a named key matching no row is **refused** rather than
55
+ silently dropped.
56
+
57
+ **Narrowing can make a declaration impossible that was fine over the whole
58
+ table**, because what binds is the busiest group rather than the product. The
59
+ existing build-time refusal already says so and now says it about the narrowed
60
+ set.
61
+
62
+ - **`Projection(..., values={...})` and `SqlValue`: a projected column of the
63
+ table's own.**
64
+
65
+ A projection copies a column from the source it names or takes the model's
66
+ own default, and a projected table's **measure** column is neither -- the
67
+ score on a review, the amount on a generated line, the reading on a sample.
68
+
69
+ Leaving it to a model default was legal and was the wrong answer *for this
70
+ package specifically*: one value across every projected row is
71
+ `n_distinct = 1`, the exact shape a planner cannot use. A library whose whole
72
+ purpose is planner realism was building tables it had made unplannable, and
73
+ the declaration looked correct.
74
+
75
+ `sql=` already answered this and answered it expensively -- it replaces the
76
+ whole `SELECT`, so the join stops being derived from the model graph and can
77
+ drift from it afterwards, the copied columns are written by hand, and the key
78
+ strategy has to be spelled in SQL. `values=` gives up none of that:
79
+
80
+ ```python
81
+ Projection(
82
+ ReviewScore,
83
+ per=Review,
84
+ copying=Criterion,
85
+ values={"score": SqlValue("({per}.id * 31 + {source}.id * 17) % 5 + 1")},
86
+ )
87
+ ```
88
+
89
+ `{per}` and `{source}` are substituted with the aliases the derived statement
90
+ uses. They are placeholders rather than the aliases themselves because the
91
+ aliases are this package's private business.
92
+
93
+ **It takes SQL rather than a distribution, and that is a decision.** A
94
+ `Distribution` computes from `draw(stream, row)`, which is SplitMix64 --
95
+ expressible in PostgreSQL only through `numeric` modular arithmetic and casts
96
+ across the sign boundary, where one mistake gives a declaration two meanings
97
+ depending on which statement filled the table. That is the divergence
98
+ `SqlKeys` exists to refuse, and it is not worth buying convenience with.
99
+
100
+ Declaring an expression for a column the source already carries, or for a
101
+ column the model does not have, or alongside `sql=`, is refused at declaration
102
+ time.
103
+
104
+ Two things the expression carries that the declaration should not have to. A
105
+ literal `%` is escaped, because the statement is executed with bound
106
+ parameters and an unescaped one is an incomplete placeholder to psycopg and to
107
+ Django's SQLite wrapper alike -- the paramstyle is no more the declaration's
108
+ business than the join's aliases are. And the expression is the one part of a
109
+ shape that is **not portable**, which is documented rather than papered over:
110
+ `mod(x, 5)` is an integer on PostgreSQL and a REAL on SQLite, so `%` is the
111
+ spelling the examples use.
112
+
10
113
  ## [0.18.1] — 2026-09-05
11
114
 
12
115
  ### Fixed
@@ -1195,7 +1298,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1195
1298
  into `COPY FROM STDIN`, which psycopg 2 cannot do without materialising them
1196
1299
  first.
1197
1300
 
1198
- [Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.18.1...HEAD
1301
+ [Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.20.0...HEAD
1302
+ [0.20.0]: https://github.com/Artui/django-data-shape/compare/v0.19.0...v0.20.0
1303
+ [0.19.0]: https://github.com/Artui/django-data-shape/compare/v0.18.1...v0.19.0
1199
1304
  [0.18.1]: https://github.com/Artui/django-data-shape/compare/v0.18.0...v0.18.1
1200
1305
  [0.18.0]: https://github.com/Artui/django-data-shape/compare/v0.17.1...v0.18.0
1201
1306
  [0.17.1]: https://github.com/Artui/django-data-shape/compare/v0.17.0...v0.17.1
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: django-data-shape
3
- Version: 0.18.1
3
+ Version: 0.20.0
4
4
  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.
5
5
  Project-URL: Homepage, https://github.com/Artui/django-data-shape
6
6
  Project-URL: Repository, https://github.com/Artui/django-data-shape
@@ -52,6 +52,7 @@ from django_data_shape.shape import Shape
52
52
  from django_data_shape.shape_digest import shape_digest
53
53
  from django_data_shape.shape_from_factory import shape_from_factory
54
54
  from django_data_shape.shape_not_empty import ShapeNotEmpty
55
+ from django_data_shape.sql_value import SqlValue
55
56
  from django_data_shape.table import Table
56
57
  from django_data_shape.table_result import TableResult
57
58
  from django_data_shape.template_database import template_database
@@ -98,6 +99,7 @@ __all__ = [
98
99
  "ShapeNotEmpty",
99
100
  "Skew",
100
101
  "SqlKeys",
102
+ "SqlValue",
101
103
  "Table",
102
104
  "TableResult",
103
105
  "UnhashableShape",
@@ -2,6 +2,8 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ from collections.abc import Sequence
6
+
5
7
  from django_data_shape.distributions.distribution import Distribution
6
8
  from django_data_shape.invalid_shape import InvalidShape
7
9
 
@@ -56,7 +58,13 @@ class Paired:
56
58
  derived shape nobody quotes is a shape nobody can check.
57
59
  """
58
60
 
59
- def __init__(self, relation: str, weights: Distribution) -> None:
61
+ def __init__(
62
+ self,
63
+ relation: str,
64
+ weights: Distribution,
65
+ *,
66
+ parents: Sequence[object] | None = None,
67
+ ) -> None:
60
68
  if not isinstance(relation, str) or not relation:
61
69
  raise InvalidShape(
62
70
  f"Paired needs the name of the fan-out it is paired with, got {relation!r}. "
@@ -65,6 +73,7 @@ class Paired:
65
73
  )
66
74
  self._relation = relation
67
75
  self._weights = weights
76
+ self._parents = None if parents is None else tuple(parents)
68
77
 
69
78
  @property
70
79
  def relation(self) -> str:
@@ -74,9 +83,44 @@ class Paired:
74
83
  def weights(self) -> Distribution:
75
84
  return self._weights
76
85
 
86
+ @property
87
+ def parents(self) -> tuple[object, ...] | None:
88
+ """The partner keys this edge may use, or ``None`` for all of them.
89
+
90
+ The same narrowing
91
+ :class:`~django_data_shape.fan_out.FanOut` takes, and it is here for the
92
+ one thing a fan-out's version cannot do: **two through tables over the
93
+ same partner model cannot otherwise be made disjoint.**
94
+
95
+ Every mechanism in this package computes a column from the row index
96
+ alone, so two ``Paired`` declarations over one partner table choose
97
+ independently and overlap by construction. Any rule of the form *these
98
+ two relationships must not overlap* is then violated however the shape
99
+ is written -- a reviewer who is also an author, an approver who is also
100
+ the requester, an auditor auditing their own team. That family is every
101
+ separation-of-duties constraint there is, and it was inexpressible.
102
+
103
+ Narrowing the two sides to disjoint subsets is what makes it
104
+ expressible, and it is also how the domains themselves work: a venue
105
+ keeps a reviewer board, an organisation separates approvers from
106
+ requesters. The declaration says the thing the business already says.
107
+
108
+ Keys are read through the database as a predicate rather than filtered
109
+ afterwards, and a named key matching no row is refused rather than
110
+ silently dropped -- both for the reasons the fan-out's version gives.
111
+ """
112
+ return self._parents
113
+
77
114
  def canonical(self) -> object:
78
- """The fan-out it pairs with and the weights over partners. See ``Canonical``."""
79
- return (self._relation, self._weights)
115
+ """The fan-out it pairs with, the weights, and any narrowing. See ``Canonical``.
116
+
117
+ ``parents`` is part of the digest because it changes which rows exist:
118
+ two declarations differing only in their subset build different
119
+ databases, and a cache key that agreed would serve one for the other.
120
+ """
121
+ return (self._relation, self._weights, self._parents)
80
122
 
81
123
  def __repr__(self) -> str:
82
- return f"Paired({self._relation!r}, {self._weights!r})"
124
+ if self._parents is None:
125
+ return f"Paired({self._relation!r}, {self._weights!r})"
126
+ return f"Paired({self._relation!r}, {self._weights!r}, parents={list(self._parents)!r})"
@@ -2,6 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ import re
5
6
  from collections import Counter
6
7
  from collections.abc import Mapping, Sequence
7
8
  from copy import copy
@@ -14,6 +15,7 @@ from django_data_shape.infer_key_strategy import infer_key_strategy
14
15
  from django_data_shape.invalid_shape import InvalidShape
15
16
  from django_data_shape.keys.key_strategy import KeyStrategy
16
17
  from django_data_shape.keys.sql_keys import SqlKeys
18
+ from django_data_shape.sql_value import SqlValue
17
19
  from django_data_shape.utils import (
18
20
  check_not_inherited,
19
21
  check_statistics_target,
@@ -28,6 +30,12 @@ from django_data_shape.utils import (
28
30
  _PER = "per"
29
31
  _SOURCE = "src"
30
32
 
33
+ # Every pyformat shape psycopg 3 and Django's SQLite wrapper accept: a doubled
34
+ # `%%`, a positional placeholder (psycopg also takes `%b` and `%t`), and a named
35
+ # one. Written as what is *allowed* rather than as what is wrong, because the
36
+ # set of legal placeholders is short and closed and the set of mistakes is not.
37
+ _PLACEHOLDER = re.compile(r"%(?:%|[sbt]|\([^)]*\)[sbt])")
38
+
31
39
 
32
40
  class Projection:
33
41
  """One row per pair, copied along a join, by ``INSERT ... SELECT``.
@@ -179,6 +187,7 @@ class Projection:
179
187
  keys: KeyStrategy | None = None,
180
188
  statistics: Mapping[str, int] | None = None,
181
189
  max_rows: int | None = None,
190
+ values: Mapping[str, SqlValue] | None = None,
182
191
  ) -> None:
183
192
  self._model = model
184
193
  self._per = per
@@ -198,6 +207,8 @@ class Projection:
198
207
  "nothing is already refused."
199
208
  )
200
209
  self._max_rows = max_rows
210
+ self._values = dict(values or {})
211
+ self._expressions: tuple[tuple[str, SqlValue], ...] = ()
201
212
  self._copied: tuple[tuple[str, str, str], ...] = ()
202
213
  self._literals: tuple[tuple[str, object], ...] = ()
203
214
  self._columns: tuple[str, ...] = ()
@@ -208,6 +219,16 @@ class Projection:
208
219
  # runs it first: under multi-table inheritance ``_meta.concrete_fields``
209
220
  # spans two tables and every column decision below would be made about
210
221
  # the wrong one.
222
+ if self._values and sql is not None:
223
+ # `sql=` is the whole SELECT, so there is nowhere for an expression
224
+ # to be put and no join for it to be written over. Two ways of
225
+ # saying one column is the over-determination refused everywhere
226
+ # else in this package.
227
+ raise InvalidShape(
228
+ f"{model.__name__} declares values= and sql= together. `sql=` is the entire "
229
+ "SELECT the insert reads from, so an expression has nowhere to go -- write it "
230
+ "into that statement instead."
231
+ )
211
232
  check_not_inherited(model)
212
233
  pk_field = primary_key_field(model)
213
234
  if sql is None:
@@ -372,6 +393,13 @@ class Projection:
372
393
  key = cast("SqlKeys", self._keys).key_sql(field_stream(seed, self.db_table, ":key"), row)
373
394
  values = [key]
374
395
  values.extend(f"{quote(alias)}.{quote(column)}" for _target, alias, column in self._copied)
396
+ # Between the copied columns and the bound literals, matching the order
397
+ # `_columns` was built in -- the two lists are one statement and a
398
+ # disagreement between them would write every column into the wrong slot.
399
+ values.extend(
400
+ expression.render(quote(_PER), quote(_SOURCE))
401
+ for _target, expression in self._expressions
402
+ )
375
403
  values.extend("%s" for _column, _value in self._literals)
376
404
  per_link, source_link = self._join
377
405
  return (
@@ -430,6 +458,7 @@ class Projection:
430
458
  source_pk = _column(primary_key_field(source))
431
459
 
432
460
  copied: list[tuple[str, str, str]] = []
461
+ expressions: list[tuple[str, SqlValue]] = []
433
462
  literals: list[tuple[str, object]] = []
434
463
  callables: list[str] = []
435
464
  missing: list[str] = []
@@ -444,6 +473,8 @@ class Projection:
444
473
  copied.append((_column(field), _PER, _column(primary_key_field(per))))
445
474
  elif field.is_relation and field.related_model is source:
446
475
  copied.append((_column(field), _SOURCE, source_pk))
476
+ elif field.name in self._values:
477
+ expressions.append((_column(field), self._values[field.name]))
447
478
  elif field.name in available:
448
479
  copied.append((_column(field), _SOURCE, _column(available[field.name])))
449
480
  elif field.has_default() and callable(field.default):
@@ -455,6 +486,21 @@ class Projection:
455
486
  else:
456
487
  missing.append(field.name)
457
488
 
489
+ declared = {field.name for field in self._model._meta.concrete_fields}
490
+ unknown = sorted(set(self._values) - declared)
491
+ if unknown:
492
+ raise InvalidShape(
493
+ f"{self._model.__name__} has no column(s) {', '.join(unknown)}, named in "
494
+ f"values=. Its columns are: {', '.join(sorted(declared))}."
495
+ )
496
+ answered = sorted(name for name in self._values if name in available)
497
+ if answered:
498
+ raise InvalidShape(
499
+ f"{self._model.__name__}.{', '.join(answered)} is named in values= and is also "
500
+ f"a column {source.__name__} carries under the same name, so the declaration "
501
+ "says two things about one column. Rename it, or drop it from values= and let "
502
+ "it be copied."
503
+ )
458
504
  if callables:
459
505
  raise InvalidShape(
460
506
  f"{self._model.__name__}.{', '.join(callables)} has a callable default, which "
@@ -472,10 +518,12 @@ class Projection:
472
518
  )
473
519
 
474
520
  self._copied = tuple(copied)
521
+ self._expressions = tuple(expressions)
475
522
  self._literals = tuple(literals)
476
523
  self._columns = (
477
524
  _column(pk_field),
478
525
  *(column for column, _alias, _source in copied),
526
+ *(column for column, _expression in expressions),
479
527
  *(column for column, _value in literals),
480
528
  )
481
529
 
@@ -502,6 +550,7 @@ class Projection:
502
550
  "what this package would use to write the key column, and here the statement "
503
551
  f"writes it: put {pk_field.name} in columns= and produce it in the select."
504
552
  )
553
+ _refuse_a_lone_percent(self._model, cast("str", self._sql))
505
554
  if columns is None:
506
555
  raise InvalidShape(
507
556
  f"{self._model.__name__} declares sql= without columns=. The select's columns "
@@ -581,6 +630,10 @@ class Projection:
581
630
  self._columns,
582
631
  self._sql,
583
632
  self._params,
633
+ # The expressions decide the values in the columns they fill, so two
634
+ # declarations differing only here build different databases and a
635
+ # key that agreed would serve one for the other.
636
+ tuple((column, expression.canonical()) for column, expression in self._expressions),
584
637
  # In the key although it writes no column, because it decides load
585
638
  # order and load order reaches the data: a raw statement selecting
586
639
  # from a table built before it and after it returns different rows.
@@ -602,6 +655,42 @@ class Projection:
602
655
  )
603
656
 
604
657
 
658
+ def _refuse_a_lone_percent(model: type[Model], sql: str) -> None:
659
+ """Refuse a ``%`` that is neither a placeholder nor doubled, here rather than at build.
660
+
661
+ ``sql=`` is a **parameterised** statement -- the caller writes ``%s`` and
662
+ passes ``params=``, which is the documented interface -- so pyformat is part
663
+ of that contract and a literal ``%`` has to be doubled. That is correct and
664
+ is not what this refusal changes.
665
+
666
+ What it changes is where the mistake surfaces. The statement reaches the
667
+ driver with a parameter sequence, and an empty sequence is still a sequence,
668
+ so an unescaped ``%`` is an incomplete placeholder: the exception comes from
669
+ ``psycopg/cursor.py``, at build time, naming nothing in the shape. A caller
670
+ who passed no parameters at all has no model that explains it, and the
671
+ modulo operator is the reason anyone writes a bare ``%`` in the first place.
672
+
673
+ A valid statement can never contain one, so nothing legal is refused -- the
674
+ check is the whole reason this can be a refusal rather than an escape.
675
+ ``SqlValue`` on the derived path *does* escape, and the two are not
676
+ inconsistent: there the caller supplies no parameters and has no reason to
677
+ know one exists.
678
+ """
679
+ position = 0
680
+ while (found := sql.find("%", position)) != -1:
681
+ placeholder = _PLACEHOLDER.match(sql, found)
682
+ if placeholder is None:
683
+ raise InvalidShape(
684
+ f"{model.__name__} declares sql= containing a lone '%' in "
685
+ f"{sql[max(0, found - 12) : found + 8].strip()!r}. The statement is run with "
686
+ "its parameters, so a '%' that is not a placeholder is read as the start of "
687
+ "one and the driver refuses it far from here. Write '%%' for the modulo "
688
+ "operator. (A derived projection's SqlValue needs no escaping, because there "
689
+ "you supply no parameters and the package escapes for you.)"
690
+ )
691
+ position = placeholder.end()
692
+
693
+
605
694
  def _addressable(model: type[Model]) -> dict[str, Field[Any, Any]]:
606
695
  """Every concrete field under both names a caller might reasonably use.
607
696
 
@@ -5,7 +5,7 @@ from __future__ import annotations
5
5
  import math
6
6
  import numbers
7
7
  from decimal import Decimal
8
- from typing import Any
8
+ from typing import Any, cast
9
9
 
10
10
  from django.db.models import Model
11
11
 
@@ -52,7 +52,9 @@ def resolve_paired(
52
52
  is resolved, so this is the one structural refusal that has to wait for the
53
53
  build.
54
54
  """
55
- keys = _read_partner_keys(partner, connection)
55
+ keys = _read_partner_keys(partner, connection, paired.parents)
56
+ _require_every_named_partner(paired.parents, keys, partner, table, field)
57
+ keys = _in_declared_order(paired.parents, keys)
56
58
  sizes = plan.sizes()
57
59
  if not keys and rows:
58
60
  raise InvalidShape(
@@ -84,23 +86,92 @@ def resolve_paired(
84
86
  )
85
87
 
86
88
 
87
- def _read_partner_keys(partner: type[Model], connection: Any) -> list[int]:
89
+ def _read_partner_keys(
90
+ partner: type[Model], connection: Any, named: tuple[object, ...] | None = None
91
+ ) -> list[int]:
88
92
  """The partner's real keys, queried rather than assumed.
89
93
 
90
94
  The same correction a fan-out carries: a project may have built the partner
91
95
  table with the ORM, so its keys are whatever the sequence handed out and a
92
96
  child pointing at ``1..N`` would point at nothing.
97
+
98
+ ``named`` narrows through the database as a predicate rather than as a
99
+ filter applied afterwards, so an edge table pinned to one half of a partner
100
+ table reads that half instead of every key it is about to ignore. The keys
101
+ go out as parameters, so a value from a caller never reaches the statement
102
+ as text.
93
103
  """
94
104
  pk_column = partner._meta.pk.column
95
105
  quote = connection.ops.quote_name
96
- with connection.cursor() as cursor:
97
- cursor.execute(
106
+ statement = (
107
+ f"SELECT {quote(pk_column)} FROM {quote(partner._meta.db_table)} "
108
+ f"ORDER BY {quote(pk_column)}"
109
+ )
110
+ params: tuple[object, ...] = ()
111
+ if named is not None:
112
+ placeholders = ", ".join(["%s"] * len(named)) or "NULL"
113
+ statement = (
98
114
  f"SELECT {quote(pk_column)} FROM {quote(partner._meta.db_table)} "
99
- f"ORDER BY {quote(pk_column)}"
115
+ f"WHERE {quote(pk_column)} IN ({placeholders}) ORDER BY {quote(pk_column)}"
100
116
  )
117
+ params = tuple(named)
118
+ with connection.cursor() as cursor:
119
+ cursor.execute(statement, params)
101
120
  return [row[0] for row in cursor.fetchall()]
102
121
 
103
122
 
123
+ def _require_every_named_partner(
124
+ named: tuple[object, ...] | None,
125
+ keys: list[int],
126
+ partner: type[Model],
127
+ table: str,
128
+ field: str,
129
+ ) -> None:
130
+ """Every key ``parents=`` named has to be a row, or the narrowing is a lie.
131
+
132
+ The database does the narrowing, so a key matching nothing simply does not
133
+ come back -- and the edges that would have used it go to whatever else was
134
+ named instead, or the table comes out empty if it was the only one. Both are
135
+ silent, and both produce a world the declaration does not describe.
136
+
137
+ The same refusal a fan-out makes, and the likely causes are the same: a key
138
+ from another test, a factory row that was rolled back, or a list built from
139
+ a queryset filtered differently from the one in the reader's head. None of
140
+ them is visible in the shape.
141
+ """
142
+ if named is None:
143
+ return
144
+ missing = [key for key in named if key not in set(keys)]
145
+ if not missing:
146
+ return
147
+ raise InvalidShape(
148
+ f"{table}.{field} names partner key(s) {missing!r} in parents=, and "
149
+ f"{partner.__name__} has no row with them. The narrowing runs in the database, so "
150
+ "a key that matches nothing is not an error there -- the edges that would have used "
151
+ "it go to the other named partners, or this table comes out empty. Load the partner "
152
+ "first, or name keys that exist."
153
+ )
154
+
155
+
156
+ def _in_declared_order(named: tuple[object, ...] | None, keys: list[int]) -> list[int]:
157
+ """Put named partners back in the order the declaration named them.
158
+
159
+ Weights below are assigned by *position*, and keys arrive ordered by primary
160
+ key because that is how they are read -- so without this the popularity of a
161
+ partner would follow the sort order of values nobody wrote down. The fan-out
162
+ carries the same correction for the same reason, and there it was measured:
163
+ one declaration gave the first-named parent 5, 11 or 79 rows across twelve
164
+ builds, because the sort order moved with the keys.
165
+ """
166
+ if named is None:
167
+ return keys
168
+ present = set(keys)
169
+ # cast rather than a narrowing check: `named` holds whatever key type the
170
+ # partner's primary key is, and membership in `present` is what proves each
171
+ # one is a key this table actually read back.
172
+ return [cast("int", key) for key in named if key in present]
173
+
174
+
104
175
  def _weights(paired: Paired, keys: list[int], seed: int, table: str, field: str) -> list[float]:
105
176
  """A weight per partner, scattered across the key range rather than ordered.
106
177
 
@@ -0,0 +1,113 @@
1
+ """A projected column written as an expression the database evaluates."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from django_data_shape.invalid_shape import InvalidShape
6
+
7
+ _PER_PLACEHOLDER = "{per}"
8
+ _SOURCE_PLACEHOLDER = "{source}"
9
+
10
+
11
+ class SqlValue:
12
+ """One projected column's value, as SQL over the join the projection derives.
13
+
14
+ A projection copies a column from the source it names, or takes the model's
15
+ own default, and those are the only two answers it has. A projected table's
16
+ **measure** column is neither: the score on a review, the amount on a
17
+ generated line, the reading on a sample. It belongs to the projected row and
18
+ to nothing the source carries.
19
+
20
+ Leaving it to the model default is legal and is the wrong answer *for this
21
+ package specifically*: one value across every projected row is
22
+ ``n_distinct = 1``, which is the exact shape a planner cannot use. A library
23
+ whose whole purpose is planner realism would then be building a table it had
24
+ made unplannable, and the declaration would look correct.
25
+
26
+ ``sql=`` already answers this and answers it expensively: it replaces the
27
+ whole ``SELECT``, so the join stops being derived from the model graph and
28
+ can drift from it afterwards, the copied columns are written out by hand,
29
+ and the key strategy has to be spelled in SQL. ``values=`` gives up none of
30
+ that and writes one expression for the one column that needs one::
31
+
32
+ Projection(
33
+ ReviewScore,
34
+ per=Review,
35
+ copying=Criterion,
36
+ values={"score": SqlValue("({per}.id * 31 + {source}.id * 17) % 5 + 1")},
37
+ )
38
+
39
+ ``{per}`` and ``{source}`` are substituted with the aliases the derived
40
+ statement uses, quoted for the connection. They are placeholders rather than
41
+ the aliases themselves because the aliases are this package's private
42
+ business: a declaration that spelled them would break the day they changed,
43
+ and a reader could not tell which side was which.
44
+
45
+ **It is SQL rather than a distribution, and that is a decision worth
46
+ stating.** A :class:`~django_data_shape.distributions.distribution.Distribution`
47
+ computes from ``draw(stream, row)``, which is SplitMix64 -- expressible in
48
+ PostgreSQL only through ``numeric`` modular arithmetic and casts across the
49
+ sign boundary, where a single mistake gives one declaration two meanings
50
+ depending on which statement filled the table. That is the divergence
51
+ :class:`~django_data_shape.keys.sql_keys.SqlKeys` exists to refuse, and it
52
+ is not worth buying convenience with. An expression the caller wrote is
53
+ honest about being the caller's.
54
+
55
+ **It is the one part of a shape that is not portable, and it cannot be
56
+ made portable.** Everything else here is a declaration this package
57
+ compiles per backend; an expression is SQL the database evaluates as
58
+ written. ``mod(x, 5)`` returns an integer on PostgreSQL and a REAL on
59
+ SQLite, so one declaration writes ``5`` into one database and ``5.0`` into
60
+ the other -- which is why the example above uses ``%``, integer on both.
61
+ Nothing here can detect that: the expression is opaque until the database
62
+ reads it. Write it for the backend the shape is built on, and cast when it
63
+ has to be both.
64
+
65
+ ``%`` is passed through as the operator, which takes an escape this package
66
+ applies rather than asking for -- unlike ``sql=``, which takes ``params=``
67
+ and so owns its own placeholders; a lone ``%`` is refused there instead. The statement is executed with bound
68
+ parameters, so a literal ``%`` in it is an incomplete placeholder to both
69
+ psycopg and Django's SQLite wrapper, and the declaration fails at execution
70
+ with a paramstyle error naming nothing in the shape. The paramstyle is this
71
+ package's private business for the same reason the join's aliases are: a
72
+ declaration that spelled it would be spelling how the statement happens to
73
+ be run.
74
+
75
+ The expression is inert data, so a shape holding one still digests.
76
+ """
77
+
78
+ def __init__(self, expression: str) -> None:
79
+ if not isinstance(expression, str) or not expression.strip():
80
+ raise InvalidShape(
81
+ f"SqlValue needs a SQL expression, got {expression!r}. An empty one would "
82
+ "produce a statement the database refuses, at a point far from the "
83
+ "declaration that caused it."
84
+ )
85
+ self._expression = expression
86
+
87
+ @property
88
+ def expression(self) -> str:
89
+ return self._expression
90
+
91
+ def render(self, per_alias: str, source_alias: str) -> str:
92
+ """The expression with the join's aliases substituted and ``%`` escaped.
93
+
94
+ The escape is last so it also covers a ``%`` inside a quoted alias,
95
+ and it is unconditional because the statement always carries a
96
+ parameter sequence -- an empty one is still a sequence, and both
97
+ drivers interpolate on anything that is not ``None``.
98
+ """
99
+ return (
100
+ self._expression.replace(_PER_PLACEHOLDER, per_alias)
101
+ .replace(_SOURCE_PLACEHOLDER, source_alias)
102
+ .replace("%", "%%")
103
+ )
104
+
105
+ def canonical(self) -> object:
106
+ """The expression itself, which is what decides the rows. See ``Canonical``."""
107
+ return ("SqlValue", self._expression)
108
+
109
+ def __repr__(self) -> str:
110
+ return f"SqlValue({self._expression!r})"
111
+
112
+
113
+ __all__ = ["SqlValue"]
@@ -2,6 +2,6 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- __version__: str = "0.18.1"
5
+ __version__: str = "0.20.0"
6
6
 
7
7
  __all__ = ["__version__"]