snake-orm 0.1.0b1__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 (198) hide show
  1. snake_orm-0.1.0b1.dist-info/METADATA +366 -0
  2. snake_orm-0.1.0b1.dist-info/RECORD +198 -0
  3. snake_orm-0.1.0b1.dist-info/WHEEL +4 -0
  4. snake_orm-0.1.0b1.dist-info/entry_points.txt +2 -0
  5. snake_orm-0.1.0b1.dist-info/licenses/LICENSE +21 -0
  6. snakeorm/__init__.py +214 -0
  7. snakeorm/advisor.py +109 -0
  8. snakeorm/cli/__init__.py +3 -0
  9. snakeorm/cli/app.py +992 -0
  10. snakeorm/cli/discovery.py +179 -0
  11. snakeorm/cli/hooks.py +86 -0
  12. snakeorm/compiler/__init__.py +3 -0
  13. snakeorm/compiler/compiler.py +330 -0
  14. snakeorm/connection.py +228 -0
  15. snakeorm/contrib/__init__.py +17 -0
  16. snakeorm/contrib/asgi.py +192 -0
  17. snakeorm/contrib/config.py +264 -0
  18. snakeorm/contrib/deliver.py +256 -0
  19. snakeorm/contrib/django.py +245 -0
  20. snakeorm/contrib/sidecar.py +44 -0
  21. snakeorm/contrib/wsgi.py +176 -0
  22. snakeorm/core/__init__.py +1 -0
  23. snakeorm/core/config.py +173 -0
  24. snakeorm/core/converters.py +172 -0
  25. snakeorm/core/exceptions.py +175 -0
  26. snakeorm/core/placement.py +15 -0
  27. snakeorm/core/sentinels.py +37 -0
  28. snakeorm/core/signals.py +114 -0
  29. snakeorm/debug/__init__.py +42 -0
  30. snakeorm/debug/assets/css/panel.css +616 -0
  31. snakeorm/debug/assets/css/snake_orm_app.css +293 -0
  32. snakeorm/debug/assets/img/icon.svg +5 -0
  33. snakeorm/debug/assets/js/history.js +425 -0
  34. snakeorm/debug/assets/js/language.js +283 -0
  35. snakeorm/debug/assets/js/panel.js +241 -0
  36. snakeorm/debug/assets/js/snake_orm_app.js +82 -0
  37. snakeorm/debug/assets/pages/cli.html +28 -0
  38. snakeorm/debug/assets/pages/config.html +34 -0
  39. snakeorm/debug/assets/pages/database_first.html +29 -0
  40. snakeorm/debug/assets/pages/help.html +21 -0
  41. snakeorm/debug/assets/pages/history.html +27 -0
  42. snakeorm/debug/capture.py +234 -0
  43. snakeorm/debug/channel.py +131 -0
  44. snakeorm/debug/collector.py +144 -0
  45. snakeorm/debug/config.py +149 -0
  46. snakeorm/debug/html.py +578 -0
  47. snakeorm/debug/matrix.py +60 -0
  48. snakeorm/debug/origin.py +42 -0
  49. snakeorm/debug/otel/__init__.py +68 -0
  50. snakeorm/debug/otel/context.py +43 -0
  51. snakeorm/debug/otel/exporter.py +277 -0
  52. snakeorm/debug/otel/payload.py +97 -0
  53. snakeorm/debug/otel/report.py +29 -0
  54. snakeorm/debug/otel/spans.py +393 -0
  55. snakeorm/debug/otel/summary.py +59 -0
  56. snakeorm/debug/record.py +54 -0
  57. snakeorm/debug/report.py +311 -0
  58. snakeorm/debug/testing.py +23 -0
  59. snakeorm/decorators/__init__.py +13 -0
  60. snakeorm/decorators/abstract.py +26 -0
  61. snakeorm/decorators/db_first.py +104 -0
  62. snakeorm/decorators/function.py +28 -0
  63. snakeorm/decorators/model.py +268 -0
  64. snakeorm/decorators/polymorphic.py +140 -0
  65. snakeorm/decorators/result.py +167 -0
  66. snakeorm/decorators/row.py +90 -0
  67. snakeorm/decorators/trigger.py +47 -0
  68. snakeorm/decorators/view.py +149 -0
  69. snakeorm/dialects/__init__.py +6 -0
  70. snakeorm/dialects/base.py +373 -0
  71. snakeorm/dialects/capabilities.py +571 -0
  72. snakeorm/dialects/literals.py +46 -0
  73. snakeorm/dialects/matrix.py +384 -0
  74. snakeorm/dialects/mysql.py +519 -0
  75. snakeorm/dialects/postgres.py +504 -0
  76. snakeorm/dialects/sqlite.py +417 -0
  77. snakeorm/drivers/__init__.py +18 -0
  78. snakeorm/drivers/asyncbase.py +73 -0
  79. snakeorm/drivers/asyncdecorators.py +244 -0
  80. snakeorm/drivers/asyncpool.py +228 -0
  81. snakeorm/drivers/asyncpsycopg.py +124 -0
  82. snakeorm/drivers/asyncpymysql.py +50 -0
  83. snakeorm/drivers/asyncsqlite.py +30 -0
  84. snakeorm/drivers/base.py +76 -0
  85. snakeorm/drivers/failures.py +181 -0
  86. snakeorm/drivers/logging.py +167 -0
  87. snakeorm/drivers/pool.py +352 -0
  88. snakeorm/drivers/psycopg.py +188 -0
  89. snakeorm/drivers/pymysql.py +176 -0
  90. snakeorm/drivers/savepoints.py +46 -0
  91. snakeorm/drivers/sqlite.py +170 -0
  92. snakeorm/drivers/threaded.py +143 -0
  93. snakeorm/drivers/timeout.py +87 -0
  94. snakeorm/dto/__init__.py +55 -0
  95. snakeorm/dto/read.py +231 -0
  96. snakeorm/dto/region.py +326 -0
  97. snakeorm/dto/resolve.py +354 -0
  98. snakeorm/dto/spec.py +201 -0
  99. snakeorm/expressions/__init__.py +88 -0
  100. snakeorm/expressions/conditional.py +178 -0
  101. snakeorm/expressions/expression.py +810 -0
  102. snakeorm/expressions/functions.py +71 -0
  103. snakeorm/expressions/keys.py +299 -0
  104. snakeorm/expressions/paths.py +43 -0
  105. snakeorm/expressions/scalar.py +293 -0
  106. snakeorm/expressions/window.py +248 -0
  107. snakeorm/fields/__init__.py +68 -0
  108. snakeorm/fields/check.py +79 -0
  109. snakeorm/fields/column.py +316 -0
  110. snakeorm/fields/enum.py +64 -0
  111. snakeorm/fields/index.py +46 -0
  112. snakeorm/fields/relationship.py +738 -0
  113. snakeorm/fields/typed.py +736 -0
  114. snakeorm/helpers/__init__.py +1 -0
  115. snakeorm/helpers/annotations.py +21 -0
  116. snakeorm/helpers/inheritance.py +41 -0
  117. snakeorm/helpers/pyliteral.py +52 -0
  118. snakeorm/helpers/pytype.py +50 -0
  119. snakeorm/introspection/__init__.py +13 -0
  120. snakeorm/introspection/base.py +30 -0
  121. snakeorm/introspection/drift.py +78 -0
  122. snakeorm/introspection/models.py +633 -0
  123. snakeorm/introspection/mysql.py +367 -0
  124. snakeorm/introspection/postgres.py +397 -0
  125. snakeorm/introspection/sqlite.py +217 -0
  126. snakeorm/introspection/unsupported.py +94 -0
  127. snakeorm/linker/__init__.py +3 -0
  128. snakeorm/linker/linker.py +521 -0
  129. snakeorm/metadata/__init__.py +41 -0
  130. snakeorm/metadata/check.py +37 -0
  131. snakeorm/metadata/column.py +201 -0
  132. snakeorm/metadata/enum_storage.py +33 -0
  133. snakeorm/metadata/fk_action.py +19 -0
  134. snakeorm/metadata/foreign_key.py +26 -0
  135. snakeorm/metadata/index.py +43 -0
  136. snakeorm/metadata/index_method.py +19 -0
  137. snakeorm/metadata/int_size.py +20 -0
  138. snakeorm/metadata/json_storage.py +21 -0
  139. snakeorm/metadata/polymorphic.py +30 -0
  140. snakeorm/metadata/primary_key.py +23 -0
  141. snakeorm/metadata/relationship.py +60 -0
  142. snakeorm/metadata/relationship_kind.py +43 -0
  143. snakeorm/metadata/routine.py +26 -0
  144. snakeorm/metadata/server_default.py +20 -0
  145. snakeorm/metadata/table.py +97 -0
  146. snakeorm/metadata/table_kind.py +23 -0
  147. snakeorm/metadata/trigger.py +62 -0
  148. snakeorm/metadata/type_params.py +348 -0
  149. snakeorm/migration/__init__.py +88 -0
  150. snakeorm/migration/asyncrunner.py +168 -0
  151. snakeorm/migration/autodetect.py +96 -0
  152. snakeorm/migration/ddl.py +1172 -0
  153. snakeorm/migration/diff.py +701 -0
  154. snakeorm/migration/loader.py +77 -0
  155. snakeorm/migration/operations.py +952 -0
  156. snakeorm/migration/planner.py +78 -0
  157. snakeorm/migration/realize.py +420 -0
  158. snakeorm/migration/renames.py +153 -0
  159. snakeorm/migration/render.py +1095 -0
  160. snakeorm/migration/runner.py +314 -0
  161. snakeorm/migration/squash.py +60 -0
  162. snakeorm/migration/state.py +107 -0
  163. snakeorm/model.py +162 -0
  164. snakeorm/py.typed +0 -0
  165. snakeorm/query/__init__.py +9 -0
  166. snakeorm/query/compound.py +288 -0
  167. snakeorm/query/join_kind.py +19 -0
  168. snakeorm/query/joined.py +143 -0
  169. snakeorm/query/query.py +1001 -0
  170. snakeorm/query/recursive.py +244 -0
  171. snakeorm/registry/__init__.py +5 -0
  172. snakeorm/registry/by_module.py +163 -0
  173. snakeorm/registry/registry.py +166 -0
  174. snakeorm/session/__init__.py +8 -0
  175. snakeorm/session/asyncsession.py +638 -0
  176. snakeorm/session/coercion.py +306 -0
  177. snakeorm/session/factory.py +29 -0
  178. snakeorm/session/guards.py +269 -0
  179. snakeorm/session/isolation.py +23 -0
  180. snakeorm/session/mapper.py +213 -0
  181. snakeorm/session/planning.py +815 -0
  182. snakeorm/session/retry.py +96 -0
  183. snakeorm/session/session.py +871 -0
  184. snakeorm/session/shared.py +355 -0
  185. snakeorm/sql/__init__.py +18 -0
  186. snakeorm/sql/adapt.py +104 -0
  187. snakeorm/sql/aggregate.py +232 -0
  188. snakeorm/sql/condition.py +359 -0
  189. snakeorm/sql/delete.py +46 -0
  190. snakeorm/sql/insert.py +149 -0
  191. snakeorm/sql/joins.py +158 -0
  192. snakeorm/sql/pk_subquery.py +54 -0
  193. snakeorm/sql/refs.py +19 -0
  194. snakeorm/sql/resolver.py +28 -0
  195. snakeorm/sql/select.py +175 -0
  196. snakeorm/sql/update.py +82 -0
  197. snakeorm/sql/value.py +552 -0
  198. snakeorm/times.py +276 -0
@@ -0,0 +1,736 @@
1
+ """Field specifiers BY TYPE FAMILY: `snake_int`, `snake_str`, `snake_decimal`, `snake_json`.
2
+
3
+ Each one carries ONLY the SQL parameters of its family, plus the type-agnostic ones (key,
4
+ uniqueness, index, name, comment, defaults). That way the checker stops offering `max_length=` on a
5
+ `SnakeColumn[int]` or `json_storage=` on a `SnakeColumn[datetime]`: the illegal state cannot be
6
+ written, which is the thesis of the project, instead of merely shouting at compile time.
7
+
8
+ It is not a new pattern: `snake_enum` and `snake_auto` already were this. These four finish it.
9
+ `snake_column()` stays for the types WITHOUT parameters (`bool`, `date`, `UUID`, `bytes`,
10
+ `timedelta`...), now without a single type-specific knob.
11
+
12
+ The three overloads per specifier repeat the signature. It is the SAME duplication as the one in
13
+ `field_specifiers`: PEP 681 and `@overload` demand literal signatures, so the language imposes it.
14
+ What can be done is keep it from drifting, and `test/fields/test_typed_specifiers.py` takes care
15
+ of that.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ from collections.abc import Callable
21
+ from datetime import datetime, time
22
+ from decimal import Decimal
23
+ from typing import Any, Literal, overload
24
+
25
+ from snakeorm.fields.column import MISSING, SnakeColumn
26
+ from snakeorm.metadata import (
27
+ SnakeDateTimeParams,
28
+ SnakeDecimalParams,
29
+ SnakeFloatParams,
30
+ SnakeIntParams,
31
+ SnakeIntSize,
32
+ SnakeJsonParams,
33
+ SnakeJsonStorage,
34
+ SnakeServerDefault,
35
+ SnakeStrParams,
36
+ SnakeTimeParams,
37
+ )
38
+
39
+
40
+ @overload
41
+ def snake_int(
42
+ *,
43
+ server_default: SnakeServerDefault,
44
+ server_default_sql: str | None = ...,
45
+ size: SnakeIntSize = ...,
46
+ default: int | None = ...,
47
+ default_factory: Callable[[], int] | None = ...,
48
+ primary_key: bool = ...,
49
+ unique: bool = ...,
50
+ index: bool = ...,
51
+ name: str | None = ...,
52
+ db_comment: str | None = ...,
53
+ init: Literal[False] = False,
54
+ ) -> Any: ...
55
+ @overload
56
+ def snake_int(
57
+ *,
58
+ server_default_sql: str,
59
+ server_default: SnakeServerDefault | None = ...,
60
+ size: SnakeIntSize = ...,
61
+ default: int | None = ...,
62
+ default_factory: Callable[[], int] | None = ...,
63
+ primary_key: bool = ...,
64
+ unique: bool = ...,
65
+ index: bool = ...,
66
+ name: str | None = ...,
67
+ db_comment: str | None = ...,
68
+ init: Literal[False] = False,
69
+ ) -> Any: ...
70
+ @overload
71
+ def snake_int(
72
+ *,
73
+ size: SnakeIntSize = ...,
74
+ default: int | None = ...,
75
+ default_factory: Callable[[], int] | None = ...,
76
+ primary_key: bool = ...,
77
+ unique: bool = ...,
78
+ index: bool = ...,
79
+ name: str | None = ...,
80
+ db_comment: str | None = ...,
81
+ ) -> Any: ...
82
+ def snake_int(
83
+ *,
84
+ size: SnakeIntSize = SnakeIntSize.BIGINT,
85
+ default: object = MISSING,
86
+ default_factory: Callable[[], int] | None = None,
87
+ primary_key: bool = False,
88
+ unique: bool = False,
89
+ index: bool = False,
90
+ name: str | None = None,
91
+ db_comment: str | None = None,
92
+ server_default: SnakeServerDefault | None = None,
93
+ server_default_sql: str | None = None,
94
+ init: Literal[False] = False,
95
+ ) -> Any:
96
+ """Declare an integer column, choosing its WIDTH in the database.
97
+
98
+ stock: SnakeColumn[int] = snake_int(size=SnakeIntSize.SMALLINT)
99
+
100
+ `size` is the only parameter specific to this family: it picks SMALLINT/INTEGER/BIGINT. The
101
+ default is `BIGINT`, the widest of the supported engines, so that Python's unbounded `int`
102
+ means the same thing in Postgres and in SQLite. For an autoincrementing PK use `snake_auto()`,
103
+ which on top of that excludes the column from the constructor.
104
+ """
105
+ del init # typing signal only; the runtime excludes via `server_default`
106
+ return SnakeColumn(
107
+ type_params=SnakeIntParams(size=size),
108
+ declared_by="snake_int",
109
+ default=default,
110
+ default_factory=default_factory,
111
+ primary_key=primary_key,
112
+ unique=unique,
113
+ index=index,
114
+ name=name,
115
+ db_comment=db_comment,
116
+ server_default=server_default,
117
+ server_default_sql=server_default_sql,
118
+ )
119
+
120
+
121
+ @overload
122
+ def snake_str(
123
+ *,
124
+ server_default: SnakeServerDefault,
125
+ server_default_sql: str | None = ...,
126
+ max_length: int | None = ...,
127
+ fixed: bool = ...,
128
+ default: str | None = ...,
129
+ default_factory: Callable[[], str] | None = ...,
130
+ primary_key: bool = ...,
131
+ unique: bool = ...,
132
+ index: bool = ...,
133
+ name: str | None = ...,
134
+ db_comment: str | None = ...,
135
+ init: Literal[False] = False,
136
+ ) -> Any: ...
137
+ @overload
138
+ def snake_str(
139
+ *,
140
+ server_default_sql: str,
141
+ server_default: SnakeServerDefault | None = ...,
142
+ max_length: int | None = ...,
143
+ fixed: bool = ...,
144
+ default: str | None = ...,
145
+ default_factory: Callable[[], str] | None = ...,
146
+ primary_key: bool = ...,
147
+ unique: bool = ...,
148
+ index: bool = ...,
149
+ name: str | None = ...,
150
+ db_comment: str | None = ...,
151
+ init: Literal[False] = False,
152
+ ) -> Any: ...
153
+ @overload
154
+ def snake_str(
155
+ *,
156
+ max_length: int | None = ...,
157
+ fixed: bool = ...,
158
+ default: str | None = ...,
159
+ default_factory: Callable[[], str] | None = ...,
160
+ primary_key: bool = ...,
161
+ unique: bool = ...,
162
+ index: bool = ...,
163
+ name: str | None = ...,
164
+ db_comment: str | None = ...,
165
+ ) -> Any: ...
166
+ def snake_str(
167
+ *,
168
+ max_length: int | None = None,
169
+ fixed: bool = False,
170
+ default: object = MISSING,
171
+ default_factory: Callable[[], str] | None = None,
172
+ primary_key: bool = False,
173
+ unique: bool = False,
174
+ index: bool = False,
175
+ name: str | None = None,
176
+ db_comment: str | None = None,
177
+ server_default: SnakeServerDefault | None = None,
178
+ server_default_sql: str | None = None,
179
+ init: Literal[False] = False,
180
+ ) -> Any:
181
+ """Declare a text column, optionally with a maximum length.
182
+
183
+ name: SnakeColumn[str] = snake_str(max_length=50)
184
+
185
+ Without `max_length` the column is TEXT. With it Postgres emits `VARCHAR(n)`, which is not
186
+ faster than TEXT: it STATES a domain rule and the database enforces it. SQLite ignores it.
187
+
188
+ With `fixed=True` the column is `CHAR(n)`, of FIXED length. It is not a stricter VARCHAR: it
189
+ pads with spaces up to `n` and compares ignoring that padding, which is exactly what someone
190
+ storing country codes or a hash of known length wants. It demands `max_length`: a CHAR without
191
+ a length is CHAR(1) in SQL, and guessing that 1 would be deciding for whoever did not decide.
192
+ """
193
+ del init # typing signal only; the runtime excludes via `server_default`
194
+ return SnakeColumn(
195
+ type_params=SnakeStrParams(max_length=max_length, fixed=fixed),
196
+ declared_by="snake_str",
197
+ default=default,
198
+ default_factory=default_factory,
199
+ primary_key=primary_key,
200
+ unique=unique,
201
+ index=index,
202
+ name=name,
203
+ db_comment=db_comment,
204
+ server_default=server_default,
205
+ server_default_sql=server_default_sql,
206
+ )
207
+
208
+
209
+ @overload
210
+ def snake_decimal(
211
+ *,
212
+ server_default: SnakeServerDefault,
213
+ precision: int,
214
+ scale: int | None = ...,
215
+ server_default_sql: str | None = ...,
216
+ default: Decimal | None = ...,
217
+ default_factory: Callable[[], Decimal] | None = ...,
218
+ primary_key: bool = ...,
219
+ unique: bool = ...,
220
+ index: bool = ...,
221
+ name: str | None = ...,
222
+ db_comment: str | None = ...,
223
+ init: Literal[False] = False,
224
+ ) -> Any: ...
225
+ @overload
226
+ def snake_decimal(
227
+ *,
228
+ server_default_sql: str,
229
+ precision: int,
230
+ scale: int | None = ...,
231
+ server_default: SnakeServerDefault | None = ...,
232
+ default: Decimal | None = ...,
233
+ default_factory: Callable[[], Decimal] | None = ...,
234
+ primary_key: bool = ...,
235
+ unique: bool = ...,
236
+ index: bool = ...,
237
+ name: str | None = ...,
238
+ db_comment: str | None = ...,
239
+ init: Literal[False] = False,
240
+ ) -> Any: ...
241
+ @overload
242
+ def snake_decimal(
243
+ *,
244
+ precision: int,
245
+ scale: int | None = ...,
246
+ default: Decimal | None = ...,
247
+ default_factory: Callable[[], Decimal] | None = ...,
248
+ primary_key: bool = ...,
249
+ unique: bool = ...,
250
+ index: bool = ...,
251
+ name: str | None = ...,
252
+ db_comment: str | None = ...,
253
+ ) -> Any: ...
254
+ def snake_decimal(
255
+ *,
256
+ precision: int,
257
+ scale: int | None = None,
258
+ default: object = MISSING,
259
+ default_factory: Callable[[], Decimal] | None = None,
260
+ primary_key: bool = False,
261
+ unique: bool = False,
262
+ index: bool = False,
263
+ name: str | None = None,
264
+ db_comment: str | None = None,
265
+ server_default: SnakeServerDefault | None = None,
266
+ server_default_sql: str | None = None,
267
+ init: Literal[False] = False,
268
+ ) -> Any:
269
+ """Declare a NUMERIC column with its precision and scale.
270
+
271
+ price: SnakeColumn[Decimal] = snake_decimal(precision=12, scale=2)
272
+
273
+ `precision` is MANDATORY, and on purpose: a `NUMERIC` without precision accepts any number of
274
+ digits, so the rounding of money stops being declared and starts depending on whatever comes
275
+ in. Whoever wants that behaviour asks for it explicitly with `snake_column()`.
276
+ """
277
+ del init # typing signal only; the runtime excludes via `server_default`
278
+ return SnakeColumn(
279
+ type_params=SnakeDecimalParams(precision=precision, scale=scale),
280
+ declared_by="snake_decimal",
281
+ default=default,
282
+ default_factory=default_factory,
283
+ primary_key=primary_key,
284
+ unique=unique,
285
+ index=index,
286
+ name=name,
287
+ db_comment=db_comment,
288
+ server_default=server_default,
289
+ server_default_sql=server_default_sql,
290
+ )
291
+
292
+
293
+ @overload
294
+ def snake_json(
295
+ *,
296
+ server_default: SnakeServerDefault,
297
+ server_default_sql: str | None = ...,
298
+ storage: SnakeJsonStorage = ...,
299
+ default_factory: Callable[[], dict[str, Any]] | None = ...,
300
+ primary_key: bool = ...,
301
+ unique: bool = ...,
302
+ index: bool = ...,
303
+ name: str | None = ...,
304
+ db_comment: str | None = ...,
305
+ init: Literal[False] = False,
306
+ ) -> Any: ...
307
+ @overload
308
+ def snake_json(
309
+ *,
310
+ server_default_sql: str,
311
+ server_default: SnakeServerDefault | None = ...,
312
+ storage: SnakeJsonStorage = ...,
313
+ default_factory: Callable[[], dict[str, Any]] | None = ...,
314
+ primary_key: bool = ...,
315
+ unique: bool = ...,
316
+ index: bool = ...,
317
+ name: str | None = ...,
318
+ db_comment: str | None = ...,
319
+ init: Literal[False] = False,
320
+ ) -> Any: ...
321
+ @overload
322
+ def snake_json(
323
+ *,
324
+ storage: SnakeJsonStorage = ...,
325
+ default_factory: Callable[[], dict[str, Any]] | None = ...,
326
+ primary_key: bool = ...,
327
+ unique: bool = ...,
328
+ index: bool = ...,
329
+ name: str | None = ...,
330
+ db_comment: str | None = ...,
331
+ ) -> Any: ...
332
+ def snake_json(
333
+ *,
334
+ storage: SnakeJsonStorage = SnakeJsonStorage.JSONB,
335
+ default_factory: Callable[[], dict[str, Any]] | None = None,
336
+ primary_key: bool = False,
337
+ unique: bool = False,
338
+ index: bool = False,
339
+ name: str | None = None,
340
+ db_comment: str | None = None,
341
+ server_default: SnakeServerDefault | None = None,
342
+ server_default_sql: str | None = None,
343
+ init: Literal[False] = False,
344
+ ) -> Any:
345
+ """Declare a JSON column, choosing how the engine backs it.
346
+
347
+ meta: SnakeColumn[dict[str, object]] = snake_json(storage=SnakeJsonStorage.JSON)
348
+
349
+ `JSONB` (the default) normalises and indexes; `JSON` preserves the exact text that came in.
350
+ SQLite collapses both to TEXT.
351
+
352
+ There is no `default`: a mutable literal shared between instances is the classic Python
353
+ defaults bug, and in the DDL a `DEFAULT '{}'` is rarely what you want. For an initial value use
354
+ `default_factory=dict`, which builds a fresh one per instance and never touches the DDL.
355
+ """
356
+ del init # typing signal only; the runtime excludes via `server_default`
357
+ return SnakeColumn(
358
+ type_params=SnakeJsonParams(storage=storage),
359
+ declared_by="snake_json",
360
+ default_factory=default_factory,
361
+ primary_key=primary_key,
362
+ unique=unique,
363
+ index=index,
364
+ name=name,
365
+ db_comment=db_comment,
366
+ server_default=server_default,
367
+ server_default_sql=server_default_sql,
368
+ )
369
+
370
+
371
+ def _date_column(
372
+ *,
373
+ declared_by: str,
374
+ tz: bool,
375
+ precision: int | None,
376
+ default_factory: Callable[[], datetime] | None,
377
+ primary_key: bool,
378
+ unique: bool,
379
+ index: bool,
380
+ name: str | None,
381
+ db_comment: str | None,
382
+ server_default: SnakeServerDefault | None,
383
+ server_default_sql: str | None,
384
+ ) -> Any:
385
+ """Common body of the two date declarators. The only thing that changes is `tz`."""
386
+ return SnakeColumn(
387
+ type_params=SnakeDateTimeParams(tz=tz, precision=precision),
388
+ declared_by=declared_by,
389
+ default_factory=default_factory,
390
+ primary_key=primary_key,
391
+ unique=unique,
392
+ index=index,
393
+ name=name,
394
+ db_comment=db_comment,
395
+ server_default=server_default,
396
+ server_default_sql=server_default_sql,
397
+ )
398
+
399
+
400
+ @overload
401
+ def snake_datetimetz(
402
+ *,
403
+ server_default: SnakeServerDefault,
404
+ server_default_sql: str | None = ...,
405
+ precision: int | None = ...,
406
+ default_factory: Callable[[], datetime] | None = ...,
407
+ primary_key: bool = ...,
408
+ unique: bool = ...,
409
+ index: bool = ...,
410
+ name: str | None = ...,
411
+ db_comment: str | None = ...,
412
+ init: Literal[False] = False,
413
+ ) -> Any: ...
414
+ @overload
415
+ def snake_datetimetz(
416
+ *,
417
+ server_default_sql: str,
418
+ server_default: SnakeServerDefault | None = ...,
419
+ precision: int | None = ...,
420
+ default_factory: Callable[[], datetime] | None = ...,
421
+ primary_key: bool = ...,
422
+ unique: bool = ...,
423
+ index: bool = ...,
424
+ name: str | None = ...,
425
+ db_comment: str | None = ...,
426
+ init: Literal[False] = False,
427
+ ) -> Any: ...
428
+ @overload
429
+ def snake_datetimetz(
430
+ *,
431
+ precision: int | None = ...,
432
+ default_factory: Callable[[], datetime] | None = ...,
433
+ primary_key: bool = ...,
434
+ unique: bool = ...,
435
+ index: bool = ...,
436
+ name: str | None = ...,
437
+ db_comment: str | None = ...,
438
+ ) -> Any: ...
439
+ def snake_datetimetz(
440
+ *,
441
+ precision: int | None = None,
442
+ default_factory: Callable[[], datetime] | None = None,
443
+ primary_key: bool = False,
444
+ unique: bool = False,
445
+ index: bool = False,
446
+ name: str | None = None,
447
+ db_comment: str | None = None,
448
+ server_default: SnakeServerDefault | None = None,
449
+ server_default_sql: str | None = None,
450
+ init: Literal[False] = False,
451
+ ) -> Any:
452
+ """Declare a `TIMESTAMPTZ` column: it stores an INSTANT, with a zone.
453
+
454
+ occurred_at: SnakeColumn[SnakeUtc] = snake_datetimetz()
455
+
456
+ The annotation has to be `SnakeUtc`, and the compiler demands it. Each one covers what the
457
+ other cannot: the declarator says which COLUMN gets created, whereas `SnakeUtc` says which
458
+ VALUE is admitted and the checker enforces that before anything runs. The guard ties the two
459
+ together, so the redundancy cannot lie. Same treatment as `snake_enum(Status)`.
460
+
461
+ `TIMESTAMPTZ` stores the moment, NOT the offset it was written with: that is why it only
462
+ admits UTC, and to get there you have `SnakeUtc.parse()`, `.from_zone()`, `.of()` and
463
+ `.now()`.
464
+
465
+ `precision` is the fractional-second digits: `0` whole seconds, `3` milliseconds, `6` the
466
+ Postgres default (exactly the resolution of Python's `datetime`). SQLite ignores it.
467
+
468
+ There is no literal `default`: a fixed date in the DDL is almost never what you want. For
469
+ "now" use `server_default=SnakeServerDefault.NOW` or `default_factory=SnakeUtc.now`."""
470
+ del init # typing signal only; the runtime excludes via `server_default`
471
+ return _date_column(
472
+ declared_by="snake_datetimetz",
473
+ tz=True,
474
+ precision=precision,
475
+ default_factory=default_factory,
476
+ primary_key=primary_key,
477
+ unique=unique,
478
+ index=index,
479
+ name=name,
480
+ db_comment=db_comment,
481
+ server_default=server_default,
482
+ server_default_sql=server_default_sql,
483
+ )
484
+
485
+
486
+ @overload
487
+ def snake_datetime(
488
+ *,
489
+ server_default: SnakeServerDefault,
490
+ server_default_sql: str | None = ...,
491
+ precision: int | None = ...,
492
+ default_factory: Callable[[], datetime] | None = ...,
493
+ primary_key: bool = ...,
494
+ unique: bool = ...,
495
+ index: bool = ...,
496
+ name: str | None = ...,
497
+ db_comment: str | None = ...,
498
+ init: Literal[False] = False,
499
+ ) -> Any: ...
500
+ @overload
501
+ def snake_datetime(
502
+ *,
503
+ server_default_sql: str,
504
+ server_default: SnakeServerDefault | None = ...,
505
+ precision: int | None = ...,
506
+ default_factory: Callable[[], datetime] | None = ...,
507
+ primary_key: bool = ...,
508
+ unique: bool = ...,
509
+ index: bool = ...,
510
+ name: str | None = ...,
511
+ db_comment: str | None = ...,
512
+ init: Literal[False] = False,
513
+ ) -> Any: ...
514
+ @overload
515
+ def snake_datetime(
516
+ *,
517
+ precision: int | None = ...,
518
+ default_factory: Callable[[], datetime] | None = ...,
519
+ primary_key: bool = ...,
520
+ unique: bool = ...,
521
+ index: bool = ...,
522
+ name: str | None = ...,
523
+ db_comment: str | None = ...,
524
+ ) -> Any: ...
525
+ def snake_datetime(
526
+ *,
527
+ precision: int | None = None,
528
+ default_factory: Callable[[], datetime] | None = None,
529
+ primary_key: bool = False,
530
+ unique: bool = False,
531
+ index: bool = False,
532
+ name: str | None = None,
533
+ db_comment: str | None = None,
534
+ server_default: SnakeServerDefault | None = None,
535
+ server_default_sql: str | None = None,
536
+ init: Literal[False] = False,
537
+ ) -> Any:
538
+ """Declare a `TIMESTAMP` column: it stores a WALL-CLOCK TIME, without a zone.
539
+
540
+ opens_at: SnakeColumn[datetime] = snake_datetime()
541
+
542
+ A wall-clock time identifies no instant until somebody says which zone it belongs to: it is
543
+ what you want for opening hours or a local holiday, and what you do NOT want for a
544
+ `created_at`. That is what `snake_datetimetz()` is for.
545
+
546
+ The annotation has to be plain `datetime`, and the compiler demands it: a `SnakeUtc` here
547
+ would lose its `tzinfo` on save, silently.
548
+
549
+ `precision` is the fractional-second digits. SQLite ignores it.
550
+
551
+ There is no literal `default`: a fixed date in the DDL is almost never what you want."""
552
+ del init # typing signal only; the runtime excludes via `server_default`
553
+ return _date_column(
554
+ declared_by="snake_datetime",
555
+ tz=False,
556
+ precision=precision,
557
+ default_factory=default_factory,
558
+ primary_key=primary_key,
559
+ unique=unique,
560
+ index=index,
561
+ name=name,
562
+ db_comment=db_comment,
563
+ server_default=server_default,
564
+ server_default_sql=server_default_sql,
565
+ )
566
+
567
+
568
+ @overload
569
+ def snake_float(
570
+ *,
571
+ server_default: SnakeServerDefault,
572
+ server_default_sql: str | None = ...,
573
+ size: int = ...,
574
+ default: float | None = ...,
575
+ default_factory: Callable[[], float] | None = ...,
576
+ primary_key: bool = ...,
577
+ unique: bool = ...,
578
+ index: bool = ...,
579
+ name: str | None = ...,
580
+ db_comment: str | None = ...,
581
+ init: Literal[False] = False,
582
+ ) -> Any: ...
583
+ @overload
584
+ def snake_float(
585
+ *,
586
+ server_default_sql: str,
587
+ server_default: SnakeServerDefault | None = ...,
588
+ size: int = ...,
589
+ default: float | None = ...,
590
+ default_factory: Callable[[], float] | None = ...,
591
+ primary_key: bool = ...,
592
+ unique: bool = ...,
593
+ index: bool = ...,
594
+ name: str | None = ...,
595
+ db_comment: str | None = ...,
596
+ init: Literal[False] = False,
597
+ ) -> Any: ...
598
+ @overload
599
+ def snake_float(
600
+ *,
601
+ size: int = ...,
602
+ default: float | None = ...,
603
+ default_factory: Callable[[], float] | None = ...,
604
+ primary_key: bool = ...,
605
+ unique: bool = ...,
606
+ index: bool = ...,
607
+ name: str | None = ...,
608
+ db_comment: str | None = ...,
609
+ ) -> Any: ...
610
+ def snake_float(
611
+ *,
612
+ size: int = 8,
613
+ default: object = MISSING,
614
+ default_factory: Callable[[], float] | None = None,
615
+ primary_key: bool = False,
616
+ unique: bool = False,
617
+ index: bool = False,
618
+ name: str | None = None,
619
+ db_comment: str | None = None,
620
+ server_default: SnakeServerDefault | None = None,
621
+ server_default_sql: str | None = None,
622
+ init: Literal[False] = False,
623
+ ) -> Any:
624
+ """Declare a floating-point column, optionally 4 bytes instead of 8.
625
+
626
+ price: SnakeColumn[float] = snake_float(size=4)
627
+
628
+ The default is 8 —double precision, which is what a Python `float` IS— and it does not change:
629
+ lowering it would make an already written model silently lose precision on upgrade. With
630
+ `size=4` the column takes half the space, which on a table of millions of rows is the
631
+ difference you are after.
632
+
633
+ SQLite emits `REAL` for both: it has a single floating-point class, and its degraded capability
634
+ says so, instead of faking a precision the engine does not deliver.
635
+ """
636
+ del init # typing signal only; the runtime excludes via `server_default`
637
+ return SnakeColumn(
638
+ type_params=SnakeFloatParams(size=size),
639
+ declared_by="snake_float",
640
+ default=default,
641
+ default_factory=default_factory,
642
+ primary_key=primary_key,
643
+ unique=unique,
644
+ index=index,
645
+ name=name,
646
+ db_comment=db_comment,
647
+ server_default=server_default,
648
+ server_default_sql=server_default_sql,
649
+ )
650
+
651
+
652
+ def _time_column(with_timezone: bool, kwargs: dict[str, object]) -> Any:
653
+ """The shared body of the two time declarators. Just one, so they cannot diverge.
654
+
655
+ Drift between two sibling declarators already happened on this branch with the dates: the body
656
+ got copied, one of them was touched and the other stayed behind.
657
+ """
658
+ return SnakeColumn(
659
+ type_params=SnakeTimeParams(with_timezone=with_timezone),
660
+ **kwargs, # type: ignore[arg-type]
661
+ )
662
+
663
+
664
+ def snake_time(
665
+ *,
666
+ default: object = MISSING,
667
+ default_factory: Callable[[], time] | None = None,
668
+ primary_key: bool = False,
669
+ unique: bool = False,
670
+ index: bool = False,
671
+ name: str | None = None,
672
+ db_comment: str | None = None,
673
+ server_default: SnakeServerDefault | None = None,
674
+ server_default_sql: str | None = None,
675
+ ) -> Any:
676
+ """Declare a time of day WITHOUT a zone (`TIME`).
677
+
678
+ opens_at: SnakeColumn[time] = snake_time()
679
+
680
+ It is the time on a wall clock: nine o'clock is nine o'clock wherever it gets read. If what
681
+ you are storing is a moment of the day tied to an offset, use `snake_timetz()`.
682
+ """
683
+ return _time_column(
684
+ False,
685
+ {
686
+ "default": default,
687
+ "default_factory": default_factory,
688
+ "primary_key": primary_key,
689
+ "unique": unique,
690
+ "index": index,
691
+ "name": name,
692
+ "db_comment": db_comment,
693
+ "server_default": server_default,
694
+ "server_default_sql": server_default_sql,
695
+ },
696
+ )
697
+
698
+
699
+ def snake_timetz(
700
+ *,
701
+ default: object = MISSING,
702
+ default_factory: Callable[[], time] | None = None,
703
+ primary_key: bool = False,
704
+ unique: bool = False,
705
+ index: bool = False,
706
+ name: str | None = None,
707
+ db_comment: str | None = None,
708
+ server_default: SnakeServerDefault | None = None,
709
+ server_default_sql: str | None = None,
710
+ ) -> Any:
711
+ """Declare a time of day WITH a zone (`TIMETZ`).
712
+
713
+ opens_at: SnakeColumn[time] = snake_timetz()
714
+
715
+ Two declarators and not a knob, same as with the dates: the column SAYS which type it creates,
716
+ instead of it depending on whether the first value that arrived carried an offset. A plain
717
+ `TIME` throws the zone away, and an opening hour seen from somewhere else stops meaning the
718
+ same thing.
719
+
720
+ Where the engine has no `TIMETZ` (MySQL, SQLite) the column falls back to TEXT and keeps the
721
+ offset inside the ISO text — which is more than a native `TIME` would keep.
722
+ """
723
+ return _time_column(
724
+ True,
725
+ {
726
+ "default": default,
727
+ "default_factory": default_factory,
728
+ "primary_key": primary_key,
729
+ "unique": unique,
730
+ "index": index,
731
+ "name": name,
732
+ "db_comment": db_comment,
733
+ "server_default": server_default,
734
+ "server_default_sql": server_default_sql,
735
+ },
736
+ )