pyoq-sql 1.0.0__py3-none-any.whl

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 (264) hide show
  1. pyoq/__init__.py +7 -0
  2. pyoq/__main__.py +5 -0
  3. pyoq/_native.pyi +5 -0
  4. pyoq/cli/__init__.py +5 -0
  5. pyoq/cli/commands.py +270 -0
  6. pyoq/cli/defaults.py +98 -0
  7. pyoq/cli/services.py +97 -0
  8. pyoq/config/__init__.py +19 -0
  9. pyoq/config/loader.py +204 -0
  10. pyoq/config/models.py +243 -0
  11. pyoq/descriptors.py +165 -0
  12. pyoq/diagnostics/__init__.py +68 -0
  13. pyoq/diagnostics/budget.py +136 -0
  14. pyoq/diagnostics/events.py +137 -0
  15. pyoq/diagnostics/fingerprint.py +267 -0
  16. pyoq/diagnostics/instrumented.py +237 -0
  17. pyoq/diagnostics/metrics.py +61 -0
  18. pyoq/diagnostics/observation.py +227 -0
  19. pyoq/diagnostics/scoped.py +103 -0
  20. pyoq/django/__init__.py +15 -0
  21. pyoq/django/apps.py +17 -0
  22. pyoq/django/execution.py +317 -0
  23. pyoq/django/generation.py +59 -0
  24. pyoq/django/management/__init__.py +0 -0
  25. pyoq/django/management/commands/__init__.py +0 -0
  26. pyoq/django/management/commands/makemigrations.py +53 -0
  27. pyoq/django/management/commands/pyoq_codegen.py +75 -0
  28. pyoq/django/parameters.py +101 -0
  29. pyoq/django/schema.py +379 -0
  30. pyoq/django/settings.py +87 -0
  31. pyoq/django/timeouts.py +105 -0
  32. pyoq/dsl/__init__.py +64 -0
  33. pyoq/dsl/aio/__init__.py +31 -0
  34. pyoq/dsl/aio/context.py +295 -0
  35. pyoq/dsl/aio/queries.py +335 -0
  36. pyoq/dsl/aio/writes.py +368 -0
  37. pyoq/dsl/context.py +326 -0
  38. pyoq/dsl/entry.py +37 -0
  39. pyoq/dsl/labels.py +36 -0
  40. pyoq/dsl/queries.py +339 -0
  41. pyoq/dsl/result.py +164 -0
  42. pyoq/dsl/writes.py +360 -0
  43. pyoq/errors.py +317 -0
  44. pyoq/fastapi/__init__.py +32 -0
  45. pyoq/fastapi/dependencies.py +167 -0
  46. pyoq/fastapi/lifespan.py +119 -0
  47. pyoq/fetching/__init__.py +55 -0
  48. pyoq/fetching/collections.py +136 -0
  49. pyoq/fetching/execution.py +587 -0
  50. pyoq/fetching/joined.py +79 -0
  51. pyoq/fetching/nesting.py +183 -0
  52. pyoq/fetching/plans.py +541 -0
  53. pyoq/fetching/select_in.py +149 -0
  54. pyoq/fetching/tables.py +110 -0
  55. pyoq/generation/__init__.py +54 -0
  56. pyoq/generation/cleanup.py +44 -0
  57. pyoq/generation/contracts.py +248 -0
  58. pyoq/generation/drift.py +169 -0
  59. pyoq/generation/lock.py +33 -0
  60. pyoq/generation/manifest.py +114 -0
  61. pyoq/generation/model.py +1001 -0
  62. pyoq/generation/pipeline.py +119 -0
  63. pyoq/generation/rendering/__init__.py +5 -0
  64. pyoq/generation/rendering/domains.py +51 -0
  65. pyoq/generation/rendering/enums.py +29 -0
  66. pyoq/generation/rendering/exports.py +70 -0
  67. pyoq/generation/rendering/imports.py +63 -0
  68. pyoq/generation/rendering/package.py +56 -0
  69. pyoq/generation/rendering/relations.py +133 -0
  70. pyoq/generation/rendering/routines.py +396 -0
  71. pyoq/generation/rendering/rows.py +79 -0
  72. pyoq/generation/rendering/source.py +121 -0
  73. pyoq/generation/rendering/tables.py +300 -0
  74. pyoq/generation/rendering/writes.py +514 -0
  75. pyoq/generation/validation.py +27 -0
  76. pyoq/generation/writer.py +184 -0
  77. pyoq/hydration/__init__.py +24 -0
  78. pyoq/hydration/engine.py +155 -0
  79. pyoq/hydration/identity.py +194 -0
  80. pyoq/hydration/plan.py +116 -0
  81. pyoq/migrations/__init__.py +9 -0
  82. pyoq/migrations/alembic.py +106 -0
  83. pyoq/migrations/hooks.py +75 -0
  84. pyoq/naming.py +261 -0
  85. pyoq/policies/__init__.py +47 -0
  86. pyoq/policies/bypass.py +122 -0
  87. pyoq/policies/governed.py +430 -0
  88. pyoq/policies/model.py +242 -0
  89. pyoq/policies/rewriting.py +263 -0
  90. pyoq/py.typed +1 -0
  91. pyoq/query/__init__.py +312 -0
  92. pyoq/query/aggregates.py +172 -0
  93. pyoq/query/arrays.py +65 -0
  94. pyoq/query/binding.py +52 -0
  95. pyoq/query/capabilities.py +317 -0
  96. pyoq/query/casts.py +73 -0
  97. pyoq/query/choices.py +185 -0
  98. pyoq/query/decoding.py +360 -0
  99. pyoq/query/documents.py +56 -0
  100. pyoq/query/execution/__init__.py +63 -0
  101. pyoq/query/execution/aio/__init__.py +31 -0
  102. pyoq/query/execution/aio/operations.py +228 -0
  103. pyoq/query/execution/aio/pooling.py +233 -0
  104. pyoq/query/execution/aio/streaming.py +161 -0
  105. pyoq/query/execution/aio/transactions.py +105 -0
  106. pyoq/query/execution/batch.py +96 -0
  107. pyoq/query/execution/binding_style.py +30 -0
  108. pyoq/query/execution/compilation.py +48 -0
  109. pyoq/query/execution/context.py +61 -0
  110. pyoq/query/execution/control.py +50 -0
  111. pyoq/query/execution/operations.py +224 -0
  112. pyoq/query/execution/planning.py +107 -0
  113. pyoq/query/execution/pooling.py +279 -0
  114. pyoq/query/execution/results.py +36 -0
  115. pyoq/query/execution/streaming.py +178 -0
  116. pyoq/query/execution/transactions.py +95 -0
  117. pyoq/query/expressions.py +1200 -0
  118. pyoq/query/fields.py +60 -0
  119. pyoq/query/mysql/__init__.py +59 -0
  120. pyoq/query/mysql/aio/__init__.py +38 -0
  121. pyoq/query/mysql/aio/commands.py +389 -0
  122. pyoq/query/mysql/aio/driver.py +196 -0
  123. pyoq/query/mysql/aio/executor.py +123 -0
  124. pyoq/query/mysql/aio/factory.py +26 -0
  125. pyoq/query/mysql/aio/operations.py +38 -0
  126. pyoq/query/mysql/aio/pool.py +53 -0
  127. pyoq/query/mysql/aio/transactions.py +313 -0
  128. pyoq/query/mysql/commands.py +354 -0
  129. pyoq/query/mysql/compiler.py +134 -0
  130. pyoq/query/mysql/context.py +20 -0
  131. pyoq/query/mysql/executor.py +126 -0
  132. pyoq/query/mysql/expressions.py +244 -0
  133. pyoq/query/mysql/factory.py +46 -0
  134. pyoq/query/mysql/health.py +66 -0
  135. pyoq/query/mysql/identifiers.py +9 -0
  136. pyoq/query/mysql/model.py +79 -0
  137. pyoq/query/mysql/operations.py +43 -0
  138. pyoq/query/mysql/parameters.py +69 -0
  139. pyoq/query/mysql/planning.py +20 -0
  140. pyoq/query/mysql/pool.py +67 -0
  141. pyoq/query/mysql/transactions.py +331 -0
  142. pyoq/query/mysql/writes.py +73 -0
  143. pyoq/query/nodes.py +750 -0
  144. pyoq/query/postgres/__init__.py +48 -0
  145. pyoq/query/postgres/aio/__init__.py +25 -0
  146. pyoq/query/postgres/aio/bulk.py +56 -0
  147. pyoq/query/postgres/aio/commands.py +264 -0
  148. pyoq/query/postgres/aio/executor.py +152 -0
  149. pyoq/query/postgres/aio/factory.py +26 -0
  150. pyoq/query/postgres/aio/operations.py +26 -0
  151. pyoq/query/postgres/aio/pool.py +40 -0
  152. pyoq/query/postgres/aio/transactions.py +295 -0
  153. pyoq/query/postgres/bulk.py +62 -0
  154. pyoq/query/postgres/commands.py +238 -0
  155. pyoq/query/postgres/compiler.py +114 -0
  156. pyoq/query/postgres/context.py +20 -0
  157. pyoq/query/postgres/executor.py +147 -0
  158. pyoq/query/postgres/expressions.py +311 -0
  159. pyoq/query/postgres/factory.py +24 -0
  160. pyoq/query/postgres/health.py +24 -0
  161. pyoq/query/postgres/identifiers.py +9 -0
  162. pyoq/query/postgres/model.py +81 -0
  163. pyoq/query/postgres/operations.py +25 -0
  164. pyoq/query/postgres/parameters.py +71 -0
  165. pyoq/query/postgres/planning.py +20 -0
  166. pyoq/query/postgres/pool.py +52 -0
  167. pyoq/query/postgres/transactions.py +295 -0
  168. pyoq/query/postgres/writes.py +37 -0
  169. pyoq/query/projections.py +105 -0
  170. pyoq/query/raw.py +90 -0
  171. pyoq/query/recursion.py +265 -0
  172. pyoq/query/rendering/__init__.py +1 -0
  173. pyoq/query/rendering/expressions.py +913 -0
  174. pyoq/query/rendering/identifiers.py +40 -0
  175. pyoq/query/rendering/projections.py +63 -0
  176. pyoq/query/rendering/queries.py +334 -0
  177. pyoq/query/rendering/sources.py +66 -0
  178. pyoq/query/rendering/writes.py +176 -0
  179. pyoq/query/results.py +459 -0
  180. pyoq/query/routines.py +196 -0
  181. pyoq/query/rows.py +156 -0
  182. pyoq/query/select.py +793 -0
  183. pyoq/query/select_nodes.py +277 -0
  184. pyoq/query/sources.py +236 -0
  185. pyoq/query/sqlite/__init__.py +43 -0
  186. pyoq/query/sqlite/commands.py +201 -0
  187. pyoq/query/sqlite/compiler.py +139 -0
  188. pyoq/query/sqlite/context.py +20 -0
  189. pyoq/query/sqlite/executor.py +119 -0
  190. pyoq/query/sqlite/expressions.py +224 -0
  191. pyoq/query/sqlite/factory.py +32 -0
  192. pyoq/query/sqlite/health.py +28 -0
  193. pyoq/query/sqlite/identifiers.py +9 -0
  194. pyoq/query/sqlite/model.py +73 -0
  195. pyoq/query/sqlite/operations.py +36 -0
  196. pyoq/query/sqlite/parameters.py +50 -0
  197. pyoq/query/sqlite/planning.py +20 -0
  198. pyoq/query/sqlite/pool.py +50 -0
  199. pyoq/query/sqlite/streaming.py +13 -0
  200. pyoq/query/sqlite/transactions.py +274 -0
  201. pyoq/query/sqlite/writes.py +35 -0
  202. pyoq/query/statements.py +27 -0
  203. pyoq/query/values.py +23 -0
  204. pyoq/query/vendor.py +162 -0
  205. pyoq/query/windows.py +424 -0
  206. pyoq/query/write_nodes.py +174 -0
  207. pyoq/query/writes.py +628 -0
  208. pyoq/relations/__init__.py +66 -0
  209. pyoq/relations/batching.py +219 -0
  210. pyoq/relations/derivation.py +111 -0
  211. pyoq/relations/fetching.py +355 -0
  212. pyoq/relations/graph.py +245 -0
  213. pyoq/relations/loading.py +74 -0
  214. pyoq/relations/model.py +75 -0
  215. pyoq/relations/planning.py +206 -0
  216. pyoq/runtime/__init__.py +9 -0
  217. pyoq/runtime/kernels.py +25 -0
  218. pyoq/runtime/python.py +43 -0
  219. pyoq/runtime/selection.py +73 -0
  220. pyoq/sanic/__init__.py +32 -0
  221. pyoq/sanic/scope.py +197 -0
  222. pyoq/sanic/workers.py +129 -0
  223. pyoq/schema/__init__.py +108 -0
  224. pyoq/schema/codec.py +711 -0
  225. pyoq/schema/models.py +604 -0
  226. pyoq/schema/mysql/__init__.py +16 -0
  227. pyoq/schema/mysql/connection.py +72 -0
  228. pyoq/schema/mysql/dsn.py +72 -0
  229. pyoq/schema/mysql/records.py +354 -0
  230. pyoq/schema/mysql/reflection.py +309 -0
  231. pyoq/schema/mysql/source.py +30 -0
  232. pyoq/schema/mysql/sql.py +128 -0
  233. pyoq/schema/mysql/types.py +105 -0
  234. pyoq/schema/postgres/__init__.py +13 -0
  235. pyoq/schema/postgres/connection.py +62 -0
  236. pyoq/schema/postgres/records.py +384 -0
  237. pyoq/schema/postgres/reflection.py +466 -0
  238. pyoq/schema/postgres/source.py +30 -0
  239. pyoq/schema/postgres/sql.py +246 -0
  240. pyoq/schema/postgres/types.py +98 -0
  241. pyoq/schema/registry.py +45 -0
  242. pyoq/schema/source.py +15 -0
  243. pyoq/schema/sqlite/__init__.py +6 -0
  244. pyoq/schema/sqlite/connection.py +54 -0
  245. pyoq/schema/sqlite/records.py +167 -0
  246. pyoq/schema/sqlite/reflection.py +393 -0
  247. pyoq/schema/sqlite/source.py +30 -0
  248. pyoq/schema/sqlite/sql.py +254 -0
  249. pyoq/schema/sqlite/types.py +74 -0
  250. pyoq/serving/__init__.py +19 -0
  251. pyoq/serving/databases.py +107 -0
  252. pyoq/snapshots/__init__.py +20 -0
  253. pyoq/snapshots/drift.py +312 -0
  254. pyoq/snapshots/files.py +96 -0
  255. pyoq/snapshots/routing.py +40 -0
  256. pyoq/snapshots/source.py +33 -0
  257. pyoq/tracing/__init__.py +5 -0
  258. pyoq/tracing/spans.py +89 -0
  259. pyoq/unset.py +14 -0
  260. pyoq_sql-1.0.0.dist-info/METADATA +3034 -0
  261. pyoq_sql-1.0.0.dist-info/RECORD +264 -0
  262. pyoq_sql-1.0.0.dist-info/WHEEL +4 -0
  263. pyoq_sql-1.0.0.dist-info/entry_points.txt +3 -0
  264. pyoq_sql-1.0.0.dist-info/licenses/LICENSE +373 -0
pyoq/fetching/plans.py ADDED
@@ -0,0 +1,541 @@
1
+ """What a resolved fetch plan asks a database for, before anything runs.
2
+
3
+ A plan says which relations are fetched and how. This turns one level of it
4
+ into the statement that answers it: the table's own columns, every to-one
5
+ relation joined into the same row, every nested collection returned beside it,
6
+ and a note of the relations still owed a statement of their own.
7
+
8
+ The root and a select-in batch are the same statement with a different reason
9
+ to exist, so they are built by the same code. One reads a whole table or a
10
+ caller's condition; the other reads the rows a batch of parent keys points at.
11
+
12
+ Nothing here reaches a database. Building a statement and running it are
13
+ separate, so a statement can be read, compiled and asserted on its own.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from dataclasses import dataclass, field, replace
19
+ from typing import TYPE_CHECKING
20
+
21
+ from pyoq.descriptors import TableDescriptor
22
+ from pyoq.errors import FetchPlanError
23
+ from pyoq.fetching.joined import join_condition
24
+ from pyoq.fetching.nesting import collection_for
25
+ from pyoq.fetching.select_in import key_condition
26
+ from pyoq.fetching.tables import TableBinding, TableNames
27
+ from pyoq.query import select, table_source
28
+ from pyoq.query.expressions import ComputedExpression
29
+ from pyoq.query.nodes import CollectionNode, FieldNode, ScalarFamily
30
+ from pyoq.query.results import family_for_kind
31
+ from pyoq.relations.fetching import FetchStrategy
32
+
33
+ if TYPE_CHECKING:
34
+ from collections.abc import Sequence
35
+
36
+ from pyoq.query.expressions import Condition
37
+ from pyoq.query.projections import OrderTerm
38
+ from pyoq.query.select import SelectQuery
39
+ from pyoq.query.sources import Source
40
+ from pyoq.relations.fetching import FetchJoin, FetchOrder
41
+ from pyoq.relations.graph import RelationGraph
42
+ from pyoq.relations.model import TypedRelation
43
+ from pyoq.relations.planning import ResolvedFetch, ResolvedFetchPlan
44
+ from pyoq.schema.models import Identifier, ObjectReference
45
+
46
+ Values = tuple[object, ...]
47
+ Positions = tuple[int, ...]
48
+
49
+
50
+ @dataclass(frozen=True, slots=True)
51
+ class FetchColumn:
52
+ """One column a fetch reads, and what kind of value it holds.
53
+
54
+ Carries what a key predicate asks of a column, so a column read from a
55
+ schema is matched the same way a generated descriptor is. It belongs to
56
+ one appearance of a table rather than to the table, because a statement
57
+ may read that table more than once.
58
+ """
59
+
60
+ binding: TableBinding
61
+ name: Identifier
62
+ scalar_family: ScalarFamily
63
+
64
+ @property
65
+ def node(self) -> FieldNode:
66
+ return self.binding.field(self.name, self.scalar_family)
67
+
68
+ @property
69
+ def expression(self) -> ComputedExpression[object]:
70
+ return ComputedExpression[object](self.node, self.scalar_family)
71
+
72
+
73
+ @dataclass(frozen=True, slots=True)
74
+ class JoinedRelation:
75
+ """A to-one relation this statement brings back in the same row."""
76
+
77
+ fetch: ResolvedFetch
78
+ key_positions: Positions
79
+ """Where the joined table's own key sits, which is what says it matched.
80
+
81
+ A row that matched nothing reads as nulls across the join. The key decides
82
+ that rather than the whole row, because a key column of a matched row is
83
+ never null: a null one could not have satisfied the condition.
84
+ """
85
+
86
+ block: RelationBlock
87
+ """Where its values sit, and everything fetched through them in turn."""
88
+
89
+
90
+ @dataclass(frozen=True, slots=True)
91
+ class NestedJoin:
92
+ """A table a collection reads alongside its own rows, as it comes back.
93
+
94
+ A collection arrives as one value, so what a join added arrives inside it
95
+ rather than beside it. These say where in that value it sits.
96
+ """
97
+
98
+ relation: TypedRelation
99
+ keys: tuple[str, ...]
100
+ """What the joined table's columns are keyed by, in its own column order."""
101
+
102
+ key_positions: Positions
103
+ """Which of those are the joined table's own key, and so say it matched.
104
+
105
+ A left join that matched nothing reads as nulls across every column it
106
+ would have added. The key decides that rather than the whole row, because
107
+ a key column of a matched row is never null.
108
+ """
109
+
110
+
111
+ @dataclass(frozen=True, slots=True)
112
+ class NestedRelation:
113
+ """A collection this statement returns beside its parent, as one value."""
114
+
115
+ fetch: ResolvedFetch
116
+ position: int
117
+ keys: tuple[str, ...]
118
+ """What each row of the collection is keyed by, in column order."""
119
+
120
+ joined: tuple[NestedJoin, ...] = ()
121
+
122
+
123
+ @dataclass(frozen=True, slots=True)
124
+ class DeferredRelation:
125
+ """A relation still owed a statement, and what its parents are keyed on."""
126
+
127
+ fetch: ResolvedFetch
128
+ key_positions: Positions
129
+
130
+
131
+ @dataclass(frozen=True, slots=True)
132
+ class RelationBlock:
133
+ """Where one table's values sit in a row, and what hangs off them.
134
+
135
+ A block describes itself the same way at every depth, so a relation
136
+ reached through a join carries its own relations exactly as the root does
137
+ and nothing has to special-case how far down it is.
138
+ """
139
+
140
+ table: ObjectReference
141
+ """Which table these values came out of, which a row keeps to be read as."""
142
+
143
+ positions: Positions
144
+ joined: tuple[JoinedRelation, ...] = ()
145
+ nested: tuple[NestedRelation, ...] = ()
146
+ deferred: tuple[DeferredRelation, ...] = ()
147
+
148
+
149
+ @dataclass(frozen=True, slots=True)
150
+ class FetchStatement:
151
+ """One level of a plan, as the statement that answers it."""
152
+
153
+ query: SelectQuery[Values]
154
+ table: ObjectReference
155
+ block: RelationBlock
156
+ columns: tuple[FetchColumn, ...] = field(default_factory=tuple)
157
+
158
+
159
+ def _reserved(graph: RelationGraph) -> frozenset[str]:
160
+ """Everything the schema already calls something, tables and columns alike.
161
+
162
+ Read from the whole graph rather than from the tables this statement
163
+ happens to reach, because a name is chosen before the walk has found every
164
+ table, and a name that turns out to collide later is no better than one
165
+ that collided from the start.
166
+ """
167
+ return frozenset(
168
+ name
169
+ for table in graph.tables
170
+ for name in (
171
+ table.name.value,
172
+ *(column.name.value for column in graph.table(table).columns),
173
+ )
174
+ )
175
+
176
+
177
+ def columns_of(
178
+ graph: RelationGraph,
179
+ table: ObjectReference | TableBinding,
180
+ /,
181
+ ) -> tuple[FetchColumn, ...]:
182
+ """Every column a table has, in the order the table declares them."""
183
+ binding = table if isinstance(table, TableBinding) else TableBinding(table)
184
+ described = graph.table(binding.table)
185
+ return tuple(
186
+ FetchColumn(binding, column.name, family_for_kind(column.data_type.kind))
187
+ for column in described.columns
188
+ )
189
+
190
+
191
+ def root_statement(
192
+ plan: ResolvedFetchPlan,
193
+ graph: RelationGraph,
194
+ /,
195
+ *,
196
+ where: Condition | None = None,
197
+ ) -> FetchStatement:
198
+ """The statement answering a plan's root and everything it carries along."""
199
+ root = graph.resolve(plan.root)
200
+ return _statement(root, plan.fetches, graph, where=where)
201
+
202
+
203
+ def batch_statement(
204
+ fetch: ResolvedFetch,
205
+ graph: RelationGraph,
206
+ keys: Sequence[Values],
207
+ /,
208
+ ) -> FetchStatement:
209
+ """The statement bringing back the rows a batch of parent keys points at."""
210
+ table = graph.resolve(fetch.table)
211
+ columns = columns_of(graph, table)
212
+ matched = _matched(columns, fetch.relation.target.columns, table)
213
+ return _statement(
214
+ table,
215
+ fetch.nested,
216
+ graph,
217
+ where=key_condition(matched, keys),
218
+ order_by=fetch.order_by,
219
+ )
220
+
221
+
222
+ def _statement(
223
+ table: ObjectReference,
224
+ fetches: tuple[ResolvedFetch, ...],
225
+ graph: RelationGraph,
226
+ *,
227
+ where: Condition | None = None,
228
+ order_by: tuple[FetchOrder, ...] = (),
229
+ ) -> FetchStatement:
230
+ """One statement, and a name for every appearance of a table it reads.
231
+
232
+ The table the statement starts from keeps its own name. Everything else it
233
+ reads is given one, because a statement may reach one table twice or reach
234
+ the table it started from, and a column qualified by a table name would
235
+ then say which of them nothing.
236
+ """
237
+ root = TableBinding(table)
238
+ names = TableNames(_reserved(graph))
239
+ columns = columns_of(graph, root)
240
+ selected = [column.expression for column in columns]
241
+ sources: list[tuple[Source[object], Condition]] = []
242
+ block = _block(fetches, graph, root, columns, selected, sources, names)
243
+ query = _from(select(*selected), root, tuple(sources))
244
+ if where is not None:
245
+ query = query.where(where)
246
+ return FetchStatement(
247
+ query=_ordered(query, columns, table, order_by),
248
+ table=table,
249
+ block=block,
250
+ columns=columns,
251
+ )
252
+
253
+
254
+ def _block(
255
+ fetches: tuple[ResolvedFetch, ...],
256
+ graph: RelationGraph,
257
+ binding: TableBinding,
258
+ columns: tuple[FetchColumn, ...],
259
+ selected: list[ComputedExpression[object]],
260
+ sources: list[tuple[Source[object], Condition]],
261
+ names: TableNames,
262
+ *,
263
+ positions: Positions | None = None,
264
+ ) -> RelationBlock:
265
+ """One table's place in the row, and everything reached from it."""
266
+ return RelationBlock(
267
+ table=binding.table,
268
+ positions=tuple(range(len(columns))) if positions is None else positions,
269
+ joined=_joined_relations(fetches, graph, binding, selected, sources, names),
270
+ nested=_nested_relations(fetches, graph, binding, selected, names),
271
+ deferred=_deferred_relations(fetches, columns),
272
+ )
273
+
274
+
275
+ def _joined_relations(
276
+ fetches: tuple[ResolvedFetch, ...],
277
+ graph: RelationGraph,
278
+ parent: TableBinding,
279
+ selected: list[ComputedExpression[object]],
280
+ sources: list[tuple[Source[object], Condition]],
281
+ names: TableNames,
282
+ ) -> tuple[JoinedRelation, ...]:
283
+ """Every to-one relation this statement reads in the same row.
284
+
285
+ A joined table's own relations are read from the same row too, so this
286
+ recurses: a chain of to-one relations is one query however long it is.
287
+ """
288
+ relations: list[JoinedRelation] = []
289
+ for fetch in _with_strategy(fetches, FetchStrategy.JOINED):
290
+ binding = names.next(graph.resolve(fetch.table))
291
+ columns = columns_of(graph, binding)
292
+ start = len(selected)
293
+ selected.extend(column.expression for column in columns)
294
+ positions = tuple(range(start, len(selected)))
295
+ sources.append((_source(binding), _condition(fetch.relation, parent, binding)))
296
+ relations.append(
297
+ JoinedRelation(
298
+ fetch,
299
+ tuple(
300
+ start + index
301
+ for index in _positions_of(columns, fetch.relation.target.columns)
302
+ ),
303
+ _block(
304
+ fetch.nested,
305
+ graph,
306
+ binding,
307
+ columns,
308
+ selected,
309
+ sources,
310
+ names,
311
+ positions=positions,
312
+ ),
313
+ )
314
+ )
315
+ return tuple(relations)
316
+
317
+
318
+ def _nested_relations(
319
+ fetches: tuple[ResolvedFetch, ...],
320
+ graph: RelationGraph,
321
+ parent: TableBinding,
322
+ selected: list[ComputedExpression[object]],
323
+ names: TableNames,
324
+ ) -> tuple[NestedRelation, ...]:
325
+ """Every collection this statement returns beside its parent.
326
+
327
+ A collection carries every column of its table rather than a chosen few,
328
+ so a row of one reads back exactly like a row fetched any other way and
329
+ nothing above has to know which way it arrived. A table it joins carries
330
+ every column for the same reason: what comes back is a row of that table,
331
+ and half a row would read back as something else.
332
+ """
333
+ relations: list[NestedRelation] = []
334
+ for fetch in _with_strategy(fetches, FetchStrategy.NESTED):
335
+ columns = columns_of(graph, graph.resolve(fetch.table))
336
+ whole = replace(fetch, joins=tuple(_whole(join, graph) for join in fetch.joins))
337
+ node = collection_for(
338
+ whole,
339
+ tuple(column.name for column in columns),
340
+ parent=parent,
341
+ names=names,
342
+ )
343
+ relations.append(
344
+ NestedRelation(
345
+ fetch,
346
+ len(selected),
347
+ tuple(column.name.value for column in columns),
348
+ _nested_joins(whole, graph, node, len(columns)),
349
+ ),
350
+ )
351
+ selected.append(ComputedExpression[object](node, ScalarFamily.JSON))
352
+ return tuple(relations)
353
+
354
+
355
+ def _whole(join: FetchJoin, graph: RelationGraph) -> FetchJoin:
356
+ """The same join, carrying every column of the table it reaches.
357
+
358
+ A plan says which relation to read alongside the collection. What comes
359
+ back is a row of that table, so it is read whole, the same way a row
360
+ reached any other way is.
361
+ """
362
+ columns = columns_of(graph, graph.resolve(join.relation.target.table))
363
+ return replace(join, carrying=tuple(column.name for column in columns))
364
+
365
+
366
+ def _nested_joins(
367
+ fetch: ResolvedFetch,
368
+ graph: RelationGraph,
369
+ node: CollectionNode,
370
+ base: int,
371
+ ) -> tuple[NestedJoin, ...]:
372
+ """Where each joined table's columns sit inside the value that comes back.
373
+
374
+ The node put the collection's own columns first and each join's after, so
375
+ the keys are read back off it in that order rather than rebuilt here.
376
+ """
377
+ joins: list[NestedJoin] = []
378
+ taken = base
379
+ for join in fetch.joins:
380
+ columns = columns_of(graph, graph.resolve(join.relation.target.table))
381
+ held = tuple(entry.key for entry in node.entries[taken : taken + len(columns)])
382
+ joins.append(
383
+ NestedJoin(
384
+ join.relation,
385
+ held,
386
+ _positions_of(columns, join.relation.target.columns),
387
+ )
388
+ )
389
+ taken += len(columns)
390
+ return tuple(joins)
391
+
392
+
393
+ def _deferred_relations(
394
+ fetches: tuple[ResolvedFetch, ...],
395
+ columns: tuple[FetchColumn, ...],
396
+ ) -> tuple[DeferredRelation, ...]:
397
+ """Every relation owed a statement, and where its parents' key sits."""
398
+ return tuple(
399
+ DeferredRelation(fetch, _positions_of(columns, fetch.relation.source.columns))
400
+ for fetch in _with_strategy(fetches, FetchStrategy.SELECT_IN)
401
+ )
402
+
403
+
404
+ def _with_strategy(
405
+ fetches: tuple[ResolvedFetch, ...],
406
+ strategy: FetchStrategy,
407
+ ) -> tuple[ResolvedFetch, ...]:
408
+ return tuple(fetch for fetch in fetches if fetch.strategy is strategy)
409
+
410
+
411
+ def _from(
412
+ query: SelectQuery[Values],
413
+ binding: TableBinding,
414
+ sources: tuple[tuple[Source[object], Condition], ...],
415
+ ) -> SelectQuery[Values]:
416
+ """Read the table, then every one of its rows may point at.
417
+
418
+ Every join is a left join. A to-one relation may resolve to nothing, and
419
+ an inner join would drop the parent row along with it, which is a row the
420
+ caller asked for going missing rather than a relation reading as absent.
421
+ """
422
+ joined = query.from_(_source(binding))
423
+ for source, condition in sources:
424
+ joined = joined.left_join(source).on(condition)
425
+ return joined
426
+
427
+
428
+ def _ordered(
429
+ query: SelectQuery[Values],
430
+ columns: tuple[FetchColumn, ...],
431
+ table: ObjectReference,
432
+ order_by: tuple[FetchOrder, ...],
433
+ ) -> SelectQuery[Values]:
434
+ """Order the rows the way the fetch asked, so they arrive in that order.
435
+
436
+ A limit is deliberately not written here. It bounds each parent's own
437
+ collection, and one statement answers many parents at once, so a limit
438
+ over the statement would keep the first few rows overall and starve every
439
+ parent after them. It is applied where the rows are grouped instead.
440
+ """
441
+ terms = tuple(_order_term(columns, table, term) for term in order_by)
442
+ return query.order_by(*terms) if terms else query
443
+
444
+
445
+ def _order_term(
446
+ columns: tuple[FetchColumn, ...],
447
+ table: ObjectReference,
448
+ term: FetchOrder,
449
+ ) -> OrderTerm:
450
+ """One term of the order, which has to name a column to be written.
451
+
452
+ A term ordered by an expression carries the name a plan reports it under
453
+ rather than the expression itself, so nothing here can write one out. The
454
+ caller is told, the same way building a collection tells them.
455
+ """
456
+ if term.column is None:
457
+ message = (
458
+ f"the rows of {table.name.value!r} are ordered by {term.name!r}, "
459
+ "which is an expression rather than a column, so this cannot "
460
+ "build it"
461
+ )
462
+ raise FetchPlanError(message)
463
+ named = {column.name: column for column in columns}
464
+ column = named.get(term.column)
465
+ if column is None:
466
+ message = (
467
+ f"{table.name.value!r} is ordered by {term.column.value!r}, "
468
+ "which it has not got"
469
+ )
470
+ raise FetchPlanError(message)
471
+ return column.expression.desc() if term.descending else column.expression.asc()
472
+
473
+
474
+ def _condition(
475
+ relation: TypedRelation,
476
+ source: TableBinding,
477
+ target: TableBinding,
478
+ ) -> Condition:
479
+ """What ties one appearance of a relation to the other, column by column."""
480
+ return join_condition(
481
+ tuple(_field(source, name) for name in relation.source.columns),
482
+ tuple(_field(target, name) for name in relation.target.columns),
483
+ )
484
+
485
+
486
+ def _positions_of(
487
+ columns: tuple[FetchColumn, ...],
488
+ named: Sequence[Identifier],
489
+ ) -> Positions:
490
+ order = {column.name: index for index, column in enumerate(columns)}
491
+ return tuple(order[name] for name in named if name in order)
492
+
493
+
494
+ def _matched(
495
+ columns: tuple[FetchColumn, ...],
496
+ named: Sequence[Identifier],
497
+ table: ObjectReference,
498
+ ) -> tuple[FetchColumn, ...]:
499
+ order = {column.name: column for column in columns}
500
+ missing = tuple(name.value for name in named if name not in order)
501
+ if missing:
502
+ message = (
503
+ f"{table.name.value!r} is keyed on {', '.join(missing)}, "
504
+ "which it has not got"
505
+ )
506
+ raise FetchPlanError(message)
507
+ return tuple(order[name] for name in named)
508
+
509
+
510
+ def _source(binding: TableBinding) -> Source[object]:
511
+ table = binding.table
512
+ return table_source(
513
+ TableDescriptor[object, object, object](
514
+ table.name.value,
515
+ _named(table.schema),
516
+ _named(table.catalog),
517
+ ),
518
+ alias=binding.alias,
519
+ )
520
+
521
+
522
+ def _field(binding: TableBinding, column: Identifier) -> FieldNode:
523
+ return binding.field(column, ScalarFamily.OTHER)
524
+
525
+
526
+ def _named(value: Identifier | None) -> str | None:
527
+ return None if value is None else value.value
528
+
529
+
530
+ __all__ = (
531
+ "DeferredRelation",
532
+ "FetchColumn",
533
+ "FetchStatement",
534
+ "JoinedRelation",
535
+ "NestedJoin",
536
+ "NestedRelation",
537
+ "RelationBlock",
538
+ "batch_statement",
539
+ "columns_of",
540
+ "root_statement",
541
+ )
@@ -0,0 +1,149 @@
1
+ """Asking for many parents' children in one statement instead of many.
2
+
3
+ An N+1 access asks once per parent. Select-in asks once per batch of parents,
4
+ which turns a query count that grows with the result into one that grows with
5
+ the dialect's parameter limit.
6
+
7
+ The predicate is built from expression nodes rather than through the typed
8
+ query API. Keys come back from a database as values whose types the caller has
9
+ already checked, so routing them through a typed column would fight the column's
10
+ own type without adding any protection to the query the caller wrote.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from collections.abc import Sequence
16
+ from typing import Protocol
17
+
18
+ from pyoq.errors import QueryValidationError
19
+ from pyoq.query.expressions import Condition
20
+ from pyoq.query.nodes import (
21
+ BinaryNode,
22
+ BinaryOperator,
23
+ BoundValueNode,
24
+ ExpressionNode,
25
+ ScalarFamily,
26
+ VariadicNode,
27
+ VariadicOperator,
28
+ )
29
+ from pyoq.relations.batching import KeyBatch, plan_key_batches
30
+ from pyoq.relations.model import TypedRelation
31
+
32
+
33
+ class KeyColumn(Protocol):
34
+ """A column a key is matched against.
35
+
36
+ Only what a predicate needs is asked for, so a generated column descriptor
37
+ satisfies this whatever value type it carries.
38
+ """
39
+
40
+ @property
41
+ def node(self) -> ExpressionNode: ...
42
+
43
+ @property
44
+ def scalar_family(self) -> ScalarFamily: ...
45
+
46
+
47
+ def key_condition(
48
+ columns: Sequence[KeyColumn],
49
+ keys: Sequence[tuple[object, ...]],
50
+ /,
51
+ ) -> Condition:
52
+ """Match rows whose key columns hold any one of these keys.
53
+
54
+ A key of one column is a membership test. A key of several is a choice
55
+ between equalities, which every dialect renders, rather than a row value,
56
+ which they do not all render alike.
57
+ """
58
+ _require_columns(columns)
59
+ _require_keys(columns, keys)
60
+ if len(columns) == 1:
61
+ return _membership(columns[0], keys)
62
+ return _any_of(tuple(_matches(columns, key) for key in keys))
63
+
64
+
65
+ def select_in_conditions(
66
+ relation: TypedRelation,
67
+ columns: Sequence[KeyColumn],
68
+ keys: Sequence[tuple[object, ...]],
69
+ /,
70
+ *,
71
+ maximum_parameters: int,
72
+ ) -> tuple[Condition, ...]:
73
+ """One condition per statement this fetch will take."""
74
+ return batch_conditions(
75
+ columns,
76
+ plan_key_batches(relation, keys, maximum_parameters=maximum_parameters),
77
+ )
78
+
79
+
80
+ def batch_conditions(
81
+ columns: Sequence[KeyColumn],
82
+ batches: Sequence[KeyBatch],
83
+ /,
84
+ ) -> tuple[Condition, ...]:
85
+ """Turn batches already planned into the conditions that fetch them."""
86
+ return tuple(key_condition(columns, batch.keys) for batch in batches)
87
+
88
+
89
+ def _membership(
90
+ column: KeyColumn,
91
+ keys: Sequence[tuple[object, ...]],
92
+ ) -> Condition:
93
+ values = tuple(_value(column, key[0]) for key in keys)
94
+ return Condition(
95
+ VariadicNode(VariadicOperator.IN, (column.node, *values)),
96
+ )
97
+
98
+
99
+ def _matches(
100
+ columns: Sequence[KeyColumn],
101
+ key: tuple[object, ...],
102
+ ) -> ExpressionNode:
103
+ equalities = tuple(
104
+ BinaryNode(BinaryOperator.EQUAL, column.node, _value(column, value))
105
+ for column, value in zip(columns, key, strict=True)
106
+ )
107
+ return _combined(VariadicOperator.AND, equalities)
108
+
109
+
110
+ def _any_of(matches: tuple[ExpressionNode, ...]) -> Condition:
111
+ return Condition(_combined(VariadicOperator.OR, matches))
112
+
113
+
114
+ def _combined(
115
+ operator: VariadicOperator,
116
+ operands: tuple[ExpressionNode, ...],
117
+ ) -> ExpressionNode:
118
+ if len(operands) == 1:
119
+ return operands[0]
120
+ return VariadicNode(operator, operands)
121
+
122
+
123
+ def _value(column: KeyColumn, value: object) -> BoundValueNode:
124
+ return BoundValueNode(value, column.scalar_family)
125
+
126
+
127
+ def _require_columns(columns: Sequence[KeyColumn]) -> None:
128
+ if not columns:
129
+ message = "a key condition needs at least one column"
130
+ raise QueryValidationError(message)
131
+
132
+
133
+ def _require_keys(
134
+ columns: Sequence[KeyColumn],
135
+ keys: Sequence[tuple[object, ...]],
136
+ ) -> None:
137
+ if not keys:
138
+ message = "a key condition needs at least one key"
139
+ raise QueryValidationError(message)
140
+ width = len(columns)
141
+ if any(len(key) != width for key in keys):
142
+ message = f"every key must hold {width} values, one for each column"
143
+ raise QueryValidationError(message)
144
+ if any(value is None for key in keys for value in key):
145
+ message = "a key holding null matches no row and cannot be asked about"
146
+ raise QueryValidationError(message)
147
+
148
+
149
+ __all__ = ("KeyColumn", "batch_conditions", "key_condition", "select_in_conditions")