django-data-shape 0.15.0__tar.gz → 0.16.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 (167) hide show
  1. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/CHANGELOG.md +34 -1
  2. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/PKG-INFO +1 -1
  3. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/resolve_fan_out.py +46 -0
  4. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/shape_from_factory.py +28 -4
  5. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/version.py +1 -1
  6. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/docs/index.md +12 -0
  7. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/docs/relations.md +10 -0
  8. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/pyproject.toml +1 -1
  9. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_build_graph.py +42 -1
  10. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_resolve_fan_out.py +57 -0
  11. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_shape_from_factory.py +54 -0
  12. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/.github/CODEOWNERS +0 -0
  13. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/.github/SECURITY.md +0 -0
  14. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/.github/dependabot.yml +0 -0
  15. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/.github/workflows/release.yml +0 -0
  16. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/.github/workflows/tests.yml +0 -0
  17. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/.github/workflows/upstream-drift.yml +0 -0
  18. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/.gitignore +0 -0
  19. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/.pre-commit-config.yaml +0 -0
  20. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/CLAUDE.md +0 -0
  21. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/LICENSE +0 -0
  22. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/Makefile +0 -0
  23. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/README.md +0 -0
  24. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/__init__.py +0 -0
  25. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/apply_statistics_targets.py +0 -0
  26. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/build.py +0 -0
  27. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/build_result.py +0 -0
  28. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/canonical.py +0 -0
  29. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/check_constraints.py +0 -0
  30. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/check_invariants.py +0 -0
  31. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/children_per_parent.py +0 -0
  32. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/clone_database.py +0 -0
  33. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/derivation_queried_database.py +0 -0
  34. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/derivations/__init__.py +0 -0
  35. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/derivations/after.py +0 -0
  36. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/derivations/aligned.py +0 -0
  37. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/derivations/derivation.py +0 -0
  38. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/derivations/derived.py +0 -0
  39. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/derivations/given.py +0 -0
  40. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/derivations/per_parent.py +0 -0
  41. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/derivations/scope.py +0 -0
  42. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/distributions/__init__.py +0 -0
  43. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/distributions/ascending.py +0 -0
  44. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/distributions/bounded.py +0 -0
  45. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/distributions/categorical.py +0 -0
  46. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/distributions/constant.py +0 -0
  47. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/distributions/distinct.py +0 -0
  48. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/distributions/distribution.py +0 -0
  49. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/distributions/sequential.py +0 -0
  50. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/distributions/skew.py +0 -0
  51. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/distributions/uniform.py +0 -0
  52. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/distributions/zipf.py +0 -0
  53. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/drop_database.py +0 -0
  54. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/fan_out.py +0 -0
  55. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/fan_out_plan.py +0 -0
  56. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/fan_out_sizes.py +0 -0
  57. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/fixtures/__init__.py +0 -0
  58. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/fixtures/scale_fixture.py +0 -0
  59. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/fixtures/shape_fixture.py +0 -0
  60. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/fixtures/skip_unless_postgres.py +0 -0
  61. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/generate_rows.py +0 -0
  62. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/infer_key_strategy.py +0 -0
  63. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/invalid_shape.py +0 -0
  64. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/invariant.py +0 -0
  65. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/invariant_violated.py +0 -0
  66. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/keys/__init__.py +0 -0
  67. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/keys/disjoint.py +0 -0
  68. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/keys/key_function.py +0 -0
  69. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/keys/key_strategy.py +0 -0
  70. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/keys/md5_keys.py +0 -0
  71. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/keys/sequential_keys.py +0 -0
  72. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/keys/sql_keys.py +0 -0
  73. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/keys/uuid_keys.py +0 -0
  74. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/order_derivations.py +0 -0
  75. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/order_tables.py +0 -0
  76. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/paired.py +0 -0
  77. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/paired_plan.py +0 -0
  78. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/projection.py +0 -0
  79. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/py.typed +0 -0
  80. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/refuse_queries.py +0 -0
  81. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/require_clone_strategy.py +0 -0
  82. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/require_postgres.py +0 -0
  83. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/resolve_paired.py +0 -0
  84. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/scale_protocol.py +0 -0
  85. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/scaled_shape.py +0 -0
  86. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/scaled_world.py +0 -0
  87. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/shape.py +0 -0
  88. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/shape_digest.py +0 -0
  89. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/shape_not_empty.py +0 -0
  90. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/table.py +0 -0
  91. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/table_result.py +0 -0
  92. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/template_database.py +0 -0
  93. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/unhashable_shape.py +0 -0
  94. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/unsupported_backend.py +0 -0
  95. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/utils.py +0 -0
  96. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/django_data_shape/world_changed.py +0 -0
  97. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/docs/derivations.md +0 -0
  98. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/docs/invariants.md +0 -0
  99. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/docs/keys.md +0 -0
  100. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/docs/projections.md +0 -0
  101. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/docs/pytest.md +0 -0
  102. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/docs/reference.md +0 -0
  103. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/docs/statistics.md +0 -0
  104. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/mkdocs.yml +0 -0
  105. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/scripts/check-changelog +0 -0
  106. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/scripts/release-publish.sh +0 -0
  107. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/__init__.py +0 -0
  108. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/conftest.py +0 -0
  109. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/conftest_settings.py +0 -0
  110. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/derivations/__init__.py +0 -0
  111. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/derivations/test_after.py +0 -0
  112. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/derivations/test_aligned.py +0 -0
  113. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/derivations/test_derived.py +0 -0
  114. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/derivations/test_given.py +0 -0
  115. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/derivations/test_per_parent.py +0 -0
  116. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/distributions/__init__.py +0 -0
  117. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/distributions/test_constant.py +0 -0
  118. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/distributions/test_sequential.py +0 -0
  119. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/distributions/test_skew.py +0 -0
  120. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/distributions/test_uniform.py +0 -0
  121. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/distributions/test_zipf.py +0 -0
  122. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/keys/__init__.py +0 -0
  123. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/keys/test_key_function.py +0 -0
  124. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/keys/test_md5_keys.py +0 -0
  125. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/keys/test_sequential_keys.py +0 -0
  126. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/keys/test_uuid_keys.py +0 -0
  127. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/scale_protocol_consumers.py +0 -0
  128. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/scale_protocol_impostors.py +0 -0
  129. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_apply_statistics_targets.py +0 -0
  130. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_build.py +0 -0
  131. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_build_derivations.py +0 -0
  132. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_build_invariants.py +0 -0
  133. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_build_keys.py +0 -0
  134. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_build_m2m.py +0 -0
  135. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_build_portable.py +0 -0
  136. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_build_projection.py +0 -0
  137. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_check_constraints.py +0 -0
  138. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_children_per_parent.py +0 -0
  139. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_documentation.py +0 -0
  140. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_fan_out.py +0 -0
  141. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_fan_out_sizes.py +0 -0
  142. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_fixtures.py +0 -0
  143. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_generate_rows.py +0 -0
  144. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_infer_key_strategy.py +0 -0
  145. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_invariant.py +0 -0
  146. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_order_derivations.py +0 -0
  147. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_order_tables.py +0 -0
  148. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_paired.py +0 -0
  149. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_paired_plan.py +0 -0
  150. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_projection.py +0 -0
  151. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_reference_documents_the_public_surface.py +0 -0
  152. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_refuse_queries.py +0 -0
  153. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_require_clone_strategy.py +0 -0
  154. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_require_postgres.py +0 -0
  155. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_resolve_paired.py +0 -0
  156. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_scale_protocol.py +0 -0
  157. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_scaled_shape.py +0 -0
  158. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_scaled_world.py +0 -0
  159. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_shape.py +0 -0
  160. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_shape_digest.py +0 -0
  161. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_table.py +0 -0
  162. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_template_database.py +0 -0
  163. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_utils.py +0 -0
  164. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/test_version.py +0 -0
  165. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/testapp/__init__.py +0 -0
  166. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/tests/testapp/models.py +0 -0
  167. {django_data_shape-0.15.0 → django_data_shape-0.16.0}/uv.lock +0 -0
@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.16.0] — 2026-09-04
11
+
12
+ ### Fixed
13
+ - **A `FanOut(parents=[...])` partition no longer depends on what the keys are.**
14
+ Keys are read back ordered by primary key and the sizes are assigned by
15
+ position, so the weights followed the *sort order of the values* rather than
16
+ the declaration. With integer keys that is merely surprising; with the UUID
17
+ primary keys a factory row has on a modern schema it means **the same shape
18
+ builds differently every run** -- measured, one declaration gave the
19
+ first-named parent 5, 11 or 79 rows across twelve builds. That is the promise
20
+ the package rests on, and the same reason `UuidKeys` derives rather than
21
+ draws, so a narrowing that broke it was a defect and not a preference. Named
22
+ parents are put back in the order they were named before anything is weighed.
23
+ - **Reversing the list is now a different declaration**, which is what a
24
+ reader writing one would expect and was the symptom reported.
25
+ - **Weights are still scattered across positions**, so the reasoning that
26
+ argued for scattering survives: a caller's *order* decides which key lands
27
+ where, and nothing correlates a parent's key with its child count.
28
+ - Worth knowing for anyone testing near this: a test written over
29
+ **integer** parents passes against the broken behaviour, because the
30
+ database's sort order matches insertion order there. Only UUID parents show
31
+ it.
32
+ - **`shape_from_factory` takes `defaults=`, and names a factory that cannot be
33
+ called.** Most factories in a real codebase take arguments and need them; a
34
+ `TeamFactory` wanting a `permission_role`, called with nothing, left a
35
+ required column empty and failed as a raw `IntegrityError` naming a
36
+ constraint. That said nothing about what the caller ran, which is the one
37
+ thing every other refusal here avoids. Anything the factory raises is now
38
+ named with the call number, because "it failed" and "it failed after three"
39
+ are different bugs.
40
+
41
+
10
42
  ## [0.15.0] — 2026-09-04
11
43
 
12
44
  ### Added
@@ -1018,7 +1050,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1018
1050
  into `COPY FROM STDIN`, which psycopg 2 cannot do without materialising them
1019
1051
  first.
1020
1052
 
1021
- [Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.15.0...HEAD
1053
+ [Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.16.0...HEAD
1054
+ [0.16.0]: https://github.com/Artui/django-data-shape/compare/v0.15.0...v0.16.0
1022
1055
  [0.15.0]: https://github.com/Artui/django-data-shape/compare/v0.14.0...v0.15.0
1023
1056
  [0.14.0]: https://github.com/Artui/django-data-shape/compare/v0.13.0...v0.14.0
1024
1057
  [0.13.0]: https://github.com/Artui/django-data-shape/compare/v0.12.0...v0.13.0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: django-data-shape
3
- Version: 0.15.0
3
+ Version: 0.16.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
@@ -45,6 +45,7 @@ def resolve_fan_out(
45
45
  """
46
46
  keys, parent_values = _read_parents(parent, parent_fields, connection, fan_out.parents)
47
47
  _require_every_named_parent(fan_out.parents, keys, parent, table, field)
48
+ keys, parent_values = _in_declared_order(fan_out.parents, keys, parent_values)
48
49
 
49
50
  if not keys and rows:
50
51
  raise InvalidShape(
@@ -71,6 +72,51 @@ def resolve_fan_out(
71
72
  )
72
73
 
73
74
 
75
+ def _in_declared_order(
76
+ named: tuple[object, ...] | None,
77
+ keys: list[int],
78
+ parent_values: dict[str, list[object]],
79
+ ) -> tuple[list[int], dict[str, list[object]]]:
80
+ """Put named parents back in the order the declaration named them.
81
+
82
+ **The partition has to be a function of the declaration, and this is what
83
+ makes it one.** Keys arrive ordered by primary key because that is how they
84
+ are read, and the sizes below are assigned by *position* -- so without this
85
+ the weights followed the sort order of values nobody wrote down. With
86
+ integer keys that is merely surprising; with the UUID keys a factory row has
87
+ on a modern schema it means **the same shape builds differently every run**.
88
+ Measured before this existed: one declaration gave the first-named parent 5,
89
+ 11 or 79 rows across twelve builds, because the sort order moved with the
90
+ keys.
91
+
92
+ That is the promise the whole package rests on -- two builds of one shape
93
+ agree, which is why ``UuidKeys`` derives rather than draws -- so a narrowing
94
+ that broke it was a defect rather than a preference.
95
+
96
+ **The weights are still scattered across positions**, and the reasoning for
97
+ that survives unchanged: it is a caller's *order* that decides which key
98
+ lands where, not their key values, so nothing here correlates a parent's key
99
+ with its child count. What it does mean is that reversing the list is a
100
+ different declaration, which is what a reader writing one would expect.
101
+
102
+ Parent values move with their keys, or a derivation would read the right
103
+ column off the wrong row.
104
+ """
105
+ if named is None:
106
+ return keys, parent_values
107
+ # `dict[object, int]` rather than the `list[int]` this module annotates its
108
+ # keys with, because that annotation is not true: a primary key is whatever
109
+ # the model declares, and the UUID case is exactly the one this function
110
+ # exists for. Widening it everywhere is a change of its own; narrowing here
111
+ # would be a lie that type-checks.
112
+ position: dict[object, int] = {key: index for index, key in enumerate(keys)}
113
+ order = [position[key] for key in named]
114
+ return (
115
+ [keys[index] for index in order],
116
+ {name: [values[index] for index in order] for name, values in parent_values.items()},
117
+ )
118
+
119
+
74
120
  def _require_every_named_parent(
75
121
  named: tuple[object, ...] | None,
76
122
  keys: list[int],
@@ -3,7 +3,7 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  from collections import Counter
6
- from collections.abc import Callable
6
+ from collections.abc import Callable, Mapping
7
7
  from typing import Any
8
8
 
9
9
  from django.apps import apps
@@ -16,9 +16,10 @@ _MANY_VALUES = 12
16
16
 
17
17
 
18
18
  def shape_from_factory(
19
- factory: Callable[[], Model],
19
+ factory: Callable[..., Model],
20
20
  *,
21
21
  samples: int = 200,
22
+ defaults: Mapping[str, object] | None = None,
22
23
  using: str = DEFAULT_DB_ALIAS,
23
24
  ) -> str:
24
25
  """Run a factory, measure what it made, and return a declaration **as source**.
@@ -46,6 +47,14 @@ def shape_from_factory(
46
47
  source, so it is detected by watching which other tables grew and by how
47
48
  much.
48
49
 
50
+ ``defaults`` is passed to every call, because **most factories in a mature
51
+ codebase need arguments**. A ``TeamFactory`` wanting a ``permission_role``,
52
+ called with nothing, leaves a required column empty and fails as a raw
53
+ ``IntegrityError`` naming a constraint -- which says nothing about what the
54
+ caller did. Anything the factory raises is caught and named here instead,
55
+ with the call number, because "it failed" and "it failed after three" are
56
+ different bugs.
57
+
49
58
  Nothing is left behind: the calls run inside a transaction that is rolled
50
59
  back, so this can be pointed at a development database without writing to it.
51
60
 
@@ -62,9 +71,24 @@ def shape_from_factory(
62
71
  )
63
72
  before = _counts(using)
64
73
  made: list[Model] = []
74
+ arguments = dict(defaults or {})
65
75
  with transaction.atomic(using=using):
66
- for _ in range(samples):
67
- row = factory()
76
+ for index in range(samples):
77
+ try:
78
+ row = factory(**arguments)
79
+ except Exception as error:
80
+ # Re-raised rather than propagated, because the failure a caller
81
+ # sees otherwise is a database constraint naming a column, which
82
+ # describes neither what they ran nor what to do about it. The
83
+ # driver's own words are kept: unlike a refusal about a
84
+ # declaration, the column their factory left empty is the whole
85
+ # of the information, and nothing here retains a generated value.
86
+ raise InvalidShape(
87
+ f"the factory could not be called on call {index + 1} of {samples}: "
88
+ f"{type(error).__name__}: {error}. Most factories in a real codebase take "
89
+ "arguments and need them -- pass them with defaults={...}, which is handed "
90
+ "to every call."
91
+ ) from error
68
92
  if not isinstance(row, Model):
69
93
  raise InvalidShape(
70
94
  f"shape_from_factory expects the factory to return a model instance, got "
@@ -2,6 +2,6 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- __version__: str = "0.15.0"
5
+ __version__: str = "0.16.0"
6
6
 
7
7
  __all__ = ["__version__"]
@@ -185,6 +185,18 @@ from django_data_shape import shape_from_factory
185
185
  print(shape_from_factory(ProjectFactory, samples=200))
186
186
  ```
187
187
 
188
+ **Most factories in a real codebase take arguments and need them.** `defaults=`
189
+ is handed to every call:
190
+
191
+ ```python
192
+ print(shape_from_factory(TeamFactory, samples=200, defaults={"permission_role": role}))
193
+ ```
194
+
195
+ Called without them, a factory leaves a required column empty and the database
196
+ answers with a constraint name. That failure is caught and named here instead,
197
+ with the call number — because "it failed" and "it failed after three" are
198
+ different bugs.
199
+
188
200
  It runs the factory, measures what the calls wrote, rolls the transaction back
189
201
  and returns **source**. Not a `Shape` — text, for you to read, edit and check
190
202
  in.
@@ -73,6 +73,16 @@ Table(Session, rows=50, company=FanOut(Constant(1), parents=[tenant.pk]), label=
73
73
 
74
74
  Real keys, read out of the parent table like any other fan-out — a key that
75
75
  matches no row is refused by name rather than quietly taking a smaller share.
76
+
77
+ **The order you name them in is part of the declaration.** Keys come back from
78
+ the database sorted by primary key, and the weights are assigned by position, so
79
+ they are put back into the order you wrote before anything is weighed. Without
80
+ that the partition followed the *values* of the keys: with the UUID primary keys
81
+ a factory row has, one declaration gave the first-named parent 5, 11 or 79 rows
82
+ across twelve builds. Two builds of one shape have to agree, which is the same
83
+ reason `UuidKeys` derives rather than draws. Reversing the list is therefore a
84
+ different declaration, and weights are still scattered across positions — so
85
+ nothing correlates a parent's key with its child count.
76
86
  A **list of keys, never a queryset**: a declaration needs no connection, and
77
87
  evaluating a queryset here would give it one. Build the list yourself, which is
78
88
  the query you were going to run anyway.
@@ -170,7 +170,7 @@ skip-magic-trailing-comma = false
170
170
  root = ["./django_data_shape"]
171
171
 
172
172
  [tool.bumpversion]
173
- current_version = "0.15.0"
173
+ current_version = "0.16.0"
174
174
  allow_dirty = false
175
175
  commit = false
176
176
  tag = false
@@ -2,6 +2,8 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ from collections import Counter
6
+
5
7
  import pytest
6
8
  from django.db import connection
7
9
 
@@ -15,7 +17,7 @@ from django_data_shape import (
15
17
  Zipf,
16
18
  )
17
19
  from django_data_shape import build as build_shape
18
- from tests.testapp.models import Company, OptionalChild, Session
20
+ from tests.testapp.models import Company, OptionalChild, Session, Tenant, TenantRecord
19
21
 
20
22
  pytestmark = [
21
23
  pytest.mark.django_db(transaction=True),
@@ -206,6 +208,45 @@ def test_every_row_can_be_pinned_to_one_pre_existing_parent() -> None:
206
208
  assert set(Session.objects.values_list("company_id", flat=True)) == {ours.pk}
207
209
 
208
210
 
211
+ def test_a_narrowed_shape_builds_the_same_over_parents_whose_keys_differ() -> None:
212
+ """The promise this package rests on, checked where it was being broken.
213
+
214
+ Parents named with ``parents=`` are usually rows somebody's factory made,
215
+ which on a modern schema means UUID primary keys -- different every run. The
216
+ keys are read back ordered by primary key and the sizes were assigned by
217
+ position in that order, so the partition followed values nobody declared.
218
+ Measured before the fix: the first-named parent got 5, 11 or 79 rows across
219
+ twelve builds of one declaration.
220
+ """
221
+ # UUID parents on purpose, and this is the whole test. With integer keys the
222
+ # database's sort order matches insertion order, so the defect cannot bite
223
+ # and a test written over them passes against the broken tree -- proving
224
+ # nothing. A factory row on a modern schema has a UUID, which sorts
225
+ # differently every run, which is where the harm was.
226
+ shapes = []
227
+ for _ in range(6):
228
+ TenantRecord.objects.all().delete()
229
+ Tenant.objects.all().delete()
230
+ tenants = [Tenant.objects.create(name=f"t{index}") for index in range(4)]
231
+ named = [tenant.pk for tenant in tenants]
232
+ build_shape(
233
+ Shape(
234
+ Table(
235
+ TenantRecord,
236
+ rows=100,
237
+ tenant=FanOut(Zipf(), parents=named),
238
+ label=Constant("s"),
239
+ ),
240
+ seed=5,
241
+ )
242
+ )
243
+ counts = Counter(TenantRecord.objects.values_list("tenant_id", flat=True))
244
+ # Keyed by the caller's position, which is what the declaration names.
245
+ shapes.append([counts[key] for key in named])
246
+
247
+ assert len(set(map(tuple, shapes))) == 1, shapes
248
+
249
+
209
250
  def test_pinning_leaves_the_other_parents_alone_rather_than_childless() -> None:
210
251
  """childless= is a share of the parents named, not of the table.
211
252
 
@@ -284,3 +284,60 @@ def test_a_boolean_size_is_refused_rather_than_counted_as_one() -> None:
284
284
  # different column.
285
285
  with pytest.raises(InvalidShape, match="True"):
286
286
  _resolve(list(range(4)), rows=40, fan_out=FanOut(Constant(True)))
287
+
288
+
289
+ def test_a_narrowed_partition_does_not_depend_on_what_the_keys_are() -> None:
290
+ """The central promise, which ``parents=`` was breaking.
291
+
292
+ Keys come back from the database ordered by primary key, and the weights
293
+ were assigned by position in *that* order -- so with UUID parents, which is
294
+ what a factory row on a modern schema has, the partition was a function of
295
+ values nobody declared. Measured before the fix: one declaration gave the
296
+ first-named parent 5, 11 or 79 rows across twelve runs, because the sort
297
+ order moved. Two builds of one shape have to agree, and that is the reason
298
+ ``UuidKeys`` derives rather than draws.
299
+ """
300
+ named = [900, 100, 500]
301
+ # The database hands these back sorted; the declaration says otherwise.
302
+ plan = resolve_paired_keys(named, sorted(named))
303
+
304
+ assert plan == named
305
+
306
+
307
+ def test_reversing_the_named_parents_reverses_the_partition() -> None:
308
+ # The symptom that was reported: reversing the list produced an identical
309
+ # partition, because the list order reached nothing.
310
+ forward = _resolve_named([10, 20, 30])
311
+ backward = _resolve_named([30, 20, 10])
312
+
313
+ assert forward != backward
314
+ assert sorted(forward.values()) == sorted(backward.values())
315
+ # The same key gets a different share, because it sits at a different
316
+ # position in what the caller wrote.
317
+ assert forward[10] == backward[30]
318
+
319
+
320
+ def _resolve_named(named: list[int]) -> dict[int, int]:
321
+ plan = resolve_fan_out(
322
+ FanOut(Zipf(1.2), parents=named),
323
+ Company,
324
+ 60,
325
+ seed=5,
326
+ table="testapp_session",
327
+ field="company",
328
+ connection=_Connection(sorted(named)),
329
+ )
330
+ return dict(zip(plan.parent_keys(), plan.sizes(), strict=True))
331
+
332
+
333
+ def resolve_paired_keys(named: list[int], returned: list[int]) -> list[object]:
334
+ plan = resolve_fan_out(
335
+ FanOut(Constant(1), parents=named),
336
+ Company,
337
+ len(named),
338
+ seed=1,
339
+ table="t",
340
+ field="company",
341
+ connection=_Connection(returned),
342
+ )
343
+ return list(plan.parent_keys())
@@ -192,3 +192,57 @@ def test_a_factory_that_varies_everything_gets_a_declaration_and_no_findings() -
192
192
 
193
193
  assert "What your factory does not vary" not in report
194
194
  assert "Table(Session, rows=..." in report
195
+
196
+
197
+ def test_a_factory_needing_arguments_is_told_so_rather_than_failing_in_the_database() -> None:
198
+ """A mature codebase's factories take arguments, and most need them.
199
+
200
+ Called with none, they leave a required column empty and the failure arrives
201
+ as a raw `IntegrityError` naming a constraint -- which says nothing about
202
+ what the caller did or what to do instead, and is the one thing every other
203
+ refusal in this package avoids.
204
+ """
205
+
206
+ def needs_a_parent(company=None) -> Session:
207
+ return Session.objects.create(company=company, label="s")
208
+
209
+ with pytest.raises(InvalidShape) as raised:
210
+ shape_from_factory(needs_a_parent, samples=5)
211
+
212
+ message = str(raised.value)
213
+ assert "could not be called" in message
214
+ assert "defaults=" in message
215
+ # The driver's own words are quoted here on purpose: unlike a refusal about
216
+ # a declaration, the caller needs to see which column their factory left
217
+ # empty, and nothing here retains a value this package generated.
218
+ assert "IntegrityError" in message
219
+
220
+
221
+ def test_defaults_are_passed_to_every_call() -> None:
222
+ company = Company.objects.create(name="acme")
223
+
224
+ def needs_a_parent(company=None) -> Session:
225
+ return Session.objects.create(company=company, label="s")
226
+
227
+ report = shape_from_factory(needs_a_parent, samples=6, defaults={"company": company})
228
+
229
+ assert "Table(Session, rows=..." in report
230
+ assert "every row pointed at the same parent" in report
231
+
232
+
233
+ def test_a_factory_that_fails_for_its_own_reasons_says_which_call_it_was() -> None:
234
+ # Not every failure is a missing argument. A factory that works and then
235
+ # stops -- a unique constraint met on the fourth call, say -- needs the call
236
+ # number, because "it failed" and "it failed after three" are different bugs.
237
+ calls = {"n": 0}
238
+
239
+ def eventually_fails() -> Session:
240
+ calls["n"] += 1
241
+ if calls["n"] > 3:
242
+ raise RuntimeError("no more room")
243
+ return Session.objects.create(company=Company.objects.create(name="c"), label="s")
244
+
245
+ with pytest.raises(InvalidShape) as raised:
246
+ shape_from_factory(eventually_fails, samples=10)
247
+
248
+ assert "call 4 of 10" in str(raised.value)