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.
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/CHANGELOG.md +106 -1
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/PKG-INFO +1 -1
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/__init__.py +2 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/paired.py +48 -4
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/projection.py +89 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/resolve_paired.py +77 -6
- django_data_shape-0.20.0/django_data_shape/sql_value.py +113 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/version.py +1 -1
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/projections.md +77 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/reference.md +2 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/relations.md +53 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/pyproject.toml +1 -1
- django_data_shape-0.20.0/tests/test_paired_parents.py +147 -0
- django_data_shape-0.20.0/tests/test_projection_sql_percent.py +98 -0
- django_data_shape-0.20.0/tests/test_projection_values.py +153 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.github/CODEOWNERS +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.github/SECURITY.md +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.github/dependabot.yml +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.github/workflows/release.yml +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.github/workflows/tests.yml +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.github/workflows/upstream-drift.yml +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.gitignore +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/.pre-commit-config.yaml +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/CLAUDE.md +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/LICENSE +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/Makefile +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/README.md +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/apply_statistics_targets.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/build.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/build_result.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/canonical.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/check_constraints.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/check_invariants.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/children_per_parent.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/clone_database.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivation_queried_database.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/__init__.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/after.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/aligned.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/copied.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/derivation.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/derived.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/given.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/offset.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/per_parent.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/product.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/derivations/scope.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/__init__.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/ascending.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/bounded.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/categorical.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/constant.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/distinct.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/distribution.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/sequential.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/skew.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/uniform.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/distributions/zipf.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/drop_database.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fan_out.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fan_out_plan.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fan_out_sizes.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fixtures/__init__.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fixtures/scale_fixture.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fixtures/shape_fixture.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/fixtures/skip_unless_postgres.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/generate_rows.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/infer_key_strategy.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/invalid_shape.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/invariant.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/invariant_violated.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/__init__.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/disjoint.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/key_function.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/key_strategy.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/md5_keys.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/sequential_keys.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/sql_keys.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/keys/uuid_keys.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/order_derivations.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/order_tables.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/paired_plan.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/py.typed +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/refuse_queries.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/require_clone_strategy.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/require_postgres.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/resolve_fan_out.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/scale_protocol.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/scaled_shape.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/scaled_world.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/shape.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/shape_digest.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/shape_from_factory.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/shape_not_empty.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/table.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/table_result.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/template_database.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/unhashable_shape.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/unsupported_backend.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/utils.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/django_data_shape/world_changed.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/derivations.md +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/index.md +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/invariants.md +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/keys.md +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/pytest.md +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/docs/statistics.md +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/mkdocs.yml +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/scripts/check-changelog +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/scripts/release-publish.sh +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/__init__.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/conftest.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/conftest_settings.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/__init__.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_after.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_after_units.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_aligned.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_canonical_arithmetic.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_derived.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_given.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/derivations/test_per_parent.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/distributions/__init__.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/distributions/test_constant.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/distributions/test_sequential.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/distributions/test_skew.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/distributions/test_uniform.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/distributions/test_zipf.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/keys/__init__.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/keys/test_key_function.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/keys/test_md5_keys.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/keys/test_sequential_keys.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/keys/test_uuid_keys.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/scale_protocol_consumers.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/scale_protocol_impostors.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_apply_statistics_targets.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_derivations.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_graph.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_invariants.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_keys.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_m2m.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_portable.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_build_projection.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_check_constraints.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_children_per_parent.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_documentation.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_fan_out.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_fan_out_sizes.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_fixtures.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_generate_rows.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_infer_key_strategy.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_invariant.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_order_derivations.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_order_tables.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_paired.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_paired_plan.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_projection.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_projection_ceiling.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_reference_documents_the_public_surface.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_refuse_queries.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_require_clone_strategy.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_require_postgres.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_resolve_fan_out.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_resolve_paired.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_scale_protocol.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_scaled_projection_ceiling.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_scaled_shape.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_scaled_world.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_scaled_world_over_a_session_world.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_scaled_world_restores_sequences.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_shape.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_shape_digest.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_shape_from_factory.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_table.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_template_database.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_utils.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/test_version.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/testapp/__init__.py +0 -0
- {django_data_shape-0.18.1 → django_data_shape-0.20.0}/tests/testapp/models.py +0 -0
- {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.
|
|
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.
|
|
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__(
|
|
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
|
|
79
|
-
|
|
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
|
-
|
|
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(
|
|
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
|
-
|
|
97
|
-
|
|
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"]
|