dbkit-sql 0.1.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 (59) hide show
  1. dbkit/__init__.py +77 -0
  2. dbkit/_async/__init__.py +17 -0
  3. dbkit/_async/_compat.py +111 -0
  4. dbkit/_async/connection.py +328 -0
  5. dbkit/_async/database.py +884 -0
  6. dbkit/_async/engine.py +232 -0
  7. dbkit/_async/executor.py +329 -0
  8. dbkit/_async/health.py +53 -0
  9. dbkit/_async/resilience.py +148 -0
  10. dbkit/_async/streaming.py +137 -0
  11. dbkit/_async/transaction.py +264 -0
  12. dbkit/_core/__init__.py +1 -0
  13. dbkit/_core/bulk.py +91 -0
  14. dbkit/_core/circuit.py +130 -0
  15. dbkit/_core/config.py +613 -0
  16. dbkit/_core/errors/__init__.py +74 -0
  17. dbkit/_core/errors/base.py +344 -0
  18. dbkit/_core/errors/classifier.py +138 -0
  19. dbkit/_core/errors/redaction.py +96 -0
  20. dbkit/_core/errors/sqlstate.py +74 -0
  21. dbkit/_core/idempotency_lint.py +57 -0
  22. dbkit/_core/keys.py +29 -0
  23. dbkit/_core/policies.py +105 -0
  24. dbkit/_core/query.py +142 -0
  25. dbkit/_core/result.py +109 -0
  26. dbkit/_core/routing.py +248 -0
  27. dbkit/_pool.py +202 -0
  28. dbkit/_sync/__init__.py +20 -0
  29. dbkit/_sync/_compat.py +82 -0
  30. dbkit/_sync/connection.py +331 -0
  31. dbkit/_sync/database.py +887 -0
  32. dbkit/_sync/engine.py +235 -0
  33. dbkit/_sync/executor.py +332 -0
  34. dbkit/_sync/health.py +56 -0
  35. dbkit/_sync/resilience.py +151 -0
  36. dbkit/_sync/streaming.py +140 -0
  37. dbkit/_sync/transaction.py +267 -0
  38. dbkit/cli/__init__.py +1 -0
  39. dbkit/cli/main.py +256 -0
  40. dbkit/errors.py +6 -0
  41. dbkit/integrations/__init__.py +21 -0
  42. dbkit/integrations/batch.py +81 -0
  43. dbkit/integrations/inbox.py +153 -0
  44. dbkit/observability/__init__.py +21 -0
  45. dbkit/observability/logging.py +154 -0
  46. dbkit/observability/metrics.py +110 -0
  47. dbkit/observability/otel_metrics.py +69 -0
  48. dbkit/observability/prometheus.py +78 -0
  49. dbkit/observability/tracing.py +128 -0
  50. dbkit/postgres/__init__.py +1 -0
  51. dbkit/postgres/copy.py +77 -0
  52. dbkit/postgres/pipeline.py +48 -0
  53. dbkit/postgres/unnest.py +73 -0
  54. dbkit/testing/__init__.py +1 -0
  55. dbkit_sql-0.1.0.dist-info/METADATA +555 -0
  56. dbkit_sql-0.1.0.dist-info/RECORD +59 -0
  57. dbkit_sql-0.1.0.dist-info/WHEEL +4 -0
  58. dbkit_sql-0.1.0.dist-info/entry_points.txt +2 -0
  59. dbkit_sql-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,331 @@
1
+ # This file is GENERATED from ../_async/connection.py by tools/run_unasync.py.
2
+ # Do not edit by hand. Run `make unasync` after changing the async source.
3
+
4
+ """Low-level execution primitives and the explicit connection scope (§11.1-11.2).
5
+
6
+ The primitives take an already-acquired SQLAlchemy connection and run one statement. Cardinality
7
+ (exactly-one / at-most-one / scalar) is enforced by SQLAlchemy's own native ``Result.one()`` /
8
+ ``.one_or_none()`` / ``.scalar_one()`` / ``.scalars().all()`` — not reimplemented here — with
9
+ ``NoResultFound`` / ``MultipleResultsFound`` translated to :class:`DatabaseResultError`. Higher
10
+ layers (the facade, the connection scope, the transaction scope) reuse these primitives so
11
+ mapping, timeouts, and error classification live in exactly one place.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import contextlib
17
+ from collections.abc import Mapping, Sequence
18
+ from typing import Any
19
+
20
+ from sqlalchemy import RowMapping, text
21
+ from sqlalchemy.engine import CursorResult
22
+ from sqlalchemy.exc import MultipleResultsFound, NoResultFound
23
+ from sqlalchemy import Connection
24
+
25
+ from .._core import result as result_mod
26
+ from .._core.errors import DatabaseResultError, classify
27
+ from .._core.query import Query, Statement, coerce_statement
28
+ from ._compat import IS_ASYNC, pipeline_scope, timeout_scope
29
+
30
+
31
+ def apply_statement_timeout_sql(seconds: float | None) -> str | None:
32
+ """Return a ``SET LOCAL statement_timeout`` statement for PostgreSQL, or ``None``.
33
+
34
+ The value is our own integer (milliseconds), never caller input, so inlining it is safe.
35
+ """
36
+ if seconds is None or seconds <= 0:
37
+ return None
38
+ ms = max(int(seconds * 1000), 1)
39
+ return f"SET LOCAL statement_timeout = {ms}"
40
+
41
+
42
+ def _maybe_set_timeout(
43
+ conn: Connection, seconds: float | None, *, is_postgres: bool
44
+ ) -> None:
45
+ # The async frontend bounds a single statement with a real client-side deadline
46
+ # (``asyncio.timeout``), which cancels the driver — so the extra server-side
47
+ # ``SET statement_timeout`` round trip is pure overhead and is skipped. The sync frontend
48
+ # has no client-side timeout primitive, so it relies on the server-side setting (§12.1).
49
+ if IS_ASYNC or not is_postgres:
50
+ return
51
+ stmt = apply_statement_timeout_sql(seconds)
52
+ if stmt is not None:
53
+ conn.execute(text(stmt))
54
+
55
+
56
+ def run_fetch(
57
+ conn: Connection,
58
+ statement: Statement,
59
+ params: Mapping[str, Any] | None,
60
+ *,
61
+ timeout: float | None,
62
+ is_postgres: bool,
63
+ ) -> list[RowMapping]:
64
+ """Execute a read and return every row mapping, no cardinality constraint."""
65
+ with timeout_scope(timeout):
66
+ _maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
67
+ cursor = conn.execute(statement, params or {})
68
+ return list(cursor.mappings().all())
69
+
70
+
71
+ def run_fetch_one(
72
+ conn: Connection,
73
+ statement: Statement,
74
+ params: Mapping[str, Any] | None,
75
+ *,
76
+ timeout: float | None,
77
+ is_postgres: bool,
78
+ ) -> RowMapping:
79
+ """Execute a read expecting exactly one row (``Result.one()``, §8.1)."""
80
+ with timeout_scope(timeout):
81
+ _maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
82
+ cursor = conn.execute(statement, params or {})
83
+ return cursor.mappings().one()
84
+
85
+
86
+ def run_fetch_optional(
87
+ conn: Connection,
88
+ statement: Statement,
89
+ params: Mapping[str, Any] | None,
90
+ *,
91
+ timeout: float | None,
92
+ is_postgres: bool,
93
+ ) -> RowMapping | None:
94
+ """Execute a read expecting zero or one row (``Result.one_or_none()``, §8.1)."""
95
+ with timeout_scope(timeout):
96
+ _maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
97
+ cursor = conn.execute(statement, params or {})
98
+ return cursor.mappings().one_or_none()
99
+
100
+
101
+ def run_fetch_value(
102
+ conn: Connection,
103
+ statement: Statement,
104
+ params: Mapping[str, Any] | None,
105
+ *,
106
+ timeout: float | None,
107
+ is_postgres: bool,
108
+ ) -> Any:
109
+ """Execute a read expecting exactly one row and take its first column
110
+ (``Result.scalar_one()``, §8.1)."""
111
+ with timeout_scope(timeout):
112
+ _maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
113
+ cursor = conn.execute(statement, params or {})
114
+ return cursor.scalar_one()
115
+
116
+
117
+ def run_fetch_values(
118
+ conn: Connection,
119
+ statement: Statement,
120
+ params: Mapping[str, Any] | None,
121
+ *,
122
+ timeout: float | None,
123
+ is_postgres: bool,
124
+ ) -> list[Any]:
125
+ """Execute a read and take the first column of every row (``Result.scalars().all()``)."""
126
+ with timeout_scope(timeout):
127
+ _maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
128
+ cursor = conn.execute(statement, params or {})
129
+ return list(cursor.scalars().all())
130
+
131
+
132
+ def run_execute(
133
+ conn: Connection,
134
+ statement: Statement,
135
+ params: Mapping[str, Any] | Sequence[Mapping[str, Any]] | None,
136
+ *,
137
+ timeout: float | None,
138
+ is_postgres: bool,
139
+ ) -> CursorResult[Any]:
140
+ """Execute a write/DDL statement and return the cursor result (for rowcount/returning)."""
141
+ with timeout_scope(timeout):
142
+ _maybe_set_timeout(conn, timeout, is_postgres=is_postgres)
143
+ return conn.execute(statement, params or {})
144
+
145
+
146
+ class ConnectionScope:
147
+ """A held connection exposing the fetch/execute family (§11.2).
148
+
149
+ Obtained via ``with db.connection(target) as conn:``. All operations run on the same
150
+ physical connection; use this when several statements must share connection state.
151
+ """
152
+
153
+ def __init__(
154
+ self,
155
+ conn: Connection,
156
+ *,
157
+ is_postgres: bool,
158
+ default_timeout: float | None,
159
+ database: str,
160
+ shard_id: str,
161
+ role: str,
162
+ ) -> None:
163
+ """Wrap an already-acquired connection; not constructed directly by applications."""
164
+ self._conn = conn
165
+ self._is_postgres = is_postgres
166
+ self._default_timeout = default_timeout
167
+ self._database = database
168
+ self._shard_id = shard_id
169
+ self._role = role
170
+
171
+ @property
172
+ def raw(self) -> Connection:
173
+ """The underlying SQLAlchemy connection — an explicit "you now own error handling"
174
+ escape hatch (§7.3).
175
+
176
+ Anything executed via ``.raw`` bypasses dbkit entirely: no error classification (you'll
177
+ see raw driver/SQLAlchemy exceptions, not :class:`~dbkit.errors.DatabaseError`
178
+ subclasses — an ``except DatabaseError`` handler will not catch them), no metrics, no
179
+ tracing, and no retry/circuit-breaker/commit-unknown handling. Use it only for the two
180
+ things dbkit doesn't itself implement (:meth:`pipeline`, :meth:`~dbkit.Database.
181
+ copy_records`'s underlying driver connection) or a genuine one-off that needs raw driver
182
+ access — not as a routine way to run queries.
183
+ """
184
+ return self._conn
185
+
186
+ def pipeline(self) -> contextlib.AbstractContextManager[None]:
187
+ """Enter psycopg pipeline mode (§7.3): statements issued in this block are sent to the
188
+ server without waiting for each response before the next — one round trip for several
189
+ dependent-but-batchable statements (e.g. a business write plus its inbox record, §28).
190
+
191
+ Usage::
192
+
193
+ with db.transaction(target=t) as tx, tx.pipeline():
194
+ tx.execute(INSERT_ORDER, params)
195
+ tx.execute(INSERT_INBOX, params)
196
+
197
+ PostgreSQL + psycopg only; raises :class:`DatabaseUnsupportedOperationError` otherwise.
198
+ Ordinary ``tx.execute(...)`` calls work unchanged inside the block — SQLAlchemy's
199
+ cursor execution transparently syncs the pipeline whenever a result is fetched.
200
+ """
201
+ return pipeline_scope(self._conn)
202
+
203
+ def _resolve(
204
+ self, query: object, params: Mapping[str, Any] | None
205
+ ) -> tuple[Statement, Query | None, float | None, str]:
206
+ statement = coerce_statement(query)
207
+ q = query if isinstance(query, Query) else None
208
+ timeout = q.timeout if (q and q.timeout is not None) else self._default_timeout
209
+ name = q.name if q else "adhoc"
210
+ return statement, q, timeout, name
211
+
212
+ def fetch_all(
213
+ self, query: object, params: Mapping[str, Any] | None = None, *, map_to: Any = None
214
+ ) -> list[Any]:
215
+ """Run a read and return every row, mapped to ``map_to`` (no cardinality check)."""
216
+ statement, _q, timeout, name = self._resolve(query, params)
217
+ try:
218
+ rows = run_fetch(
219
+ self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
220
+ )
221
+ except Exception as exc:
222
+ raise classify(
223
+ exc, query_name=name, database_name=self._database, role=self._role
224
+ ) from exc
225
+ return result_mod.map_rows(rows, map_to)
226
+
227
+ def fetch_one(
228
+ self, query: object, params: Mapping[str, Any] | None = None, *, map_to: Any = None
229
+ ) -> Any:
230
+ """Run a read expecting exactly one row; raises :class:`DatabaseResultError` otherwise."""
231
+ statement, _q, timeout, name = self._resolve(query, params)
232
+ try:
233
+ row = run_fetch_one(
234
+ self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
235
+ )
236
+ except NoResultFound as exc:
237
+ raise DatabaseResultError(
238
+ f"query {name!r} returned no rows, expected exactly one",
239
+ query_name=name,
240
+ database_name=self._database,
241
+ role=self._role,
242
+ ) from exc
243
+ except MultipleResultsFound as exc:
244
+ raise DatabaseResultError(
245
+ f"query {name!r} returned more than one row, expected exactly one",
246
+ query_name=name,
247
+ database_name=self._database,
248
+ role=self._role,
249
+ ) from exc
250
+ except Exception as exc:
251
+ raise classify(
252
+ exc, query_name=name, database_name=self._database, role=self._role
253
+ ) from exc
254
+ return result_mod.build_mapper(map_to)(row)
255
+
256
+ def fetch_optional(
257
+ self, query: object, params: Mapping[str, Any] | None = None, *, map_to: Any = None
258
+ ) -> Any | None:
259
+ """Run a read expecting zero or one row; ``None`` if empty, else the mapped row."""
260
+ statement, _q, timeout, name = self._resolve(query, params)
261
+ try:
262
+ row = run_fetch_optional(
263
+ self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
264
+ )
265
+ except MultipleResultsFound as exc:
266
+ raise DatabaseResultError(
267
+ f"query {name!r} returned more than one row, expected at most one",
268
+ query_name=name,
269
+ database_name=self._database,
270
+ role=self._role,
271
+ ) from exc
272
+ except Exception as exc:
273
+ raise classify(
274
+ exc, query_name=name, database_name=self._database, role=self._role
275
+ ) from exc
276
+ if row is None:
277
+ return None
278
+ return result_mod.build_mapper(map_to)(row)
279
+
280
+ def fetch_value(self, query: object, params: Mapping[str, Any] | None = None) -> Any:
281
+ """Run a read expecting exactly one row and return its first column."""
282
+ statement, _q, timeout, name = self._resolve(query, params)
283
+ try:
284
+ return run_fetch_value(
285
+ self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
286
+ )
287
+ except NoResultFound as exc:
288
+ raise DatabaseResultError(
289
+ f"query {name!r} returned no rows, expected a single scalar value",
290
+ query_name=name,
291
+ database_name=self._database,
292
+ role=self._role,
293
+ ) from exc
294
+ except MultipleResultsFound as exc:
295
+ raise DatabaseResultError(
296
+ f"query {name!r} returned more than one row, expected a single scalar value",
297
+ query_name=name,
298
+ database_name=self._database,
299
+ role=self._role,
300
+ ) from exc
301
+ except Exception as exc:
302
+ raise classify(
303
+ exc, query_name=name, database_name=self._database, role=self._role
304
+ ) from exc
305
+
306
+ def fetch_values(
307
+ self, query: object, params: Mapping[str, Any] | None = None
308
+ ) -> list[Any]:
309
+ """Run a read and return the first column of every row."""
310
+ statement, _q, timeout, name = self._resolve(query, params)
311
+ try:
312
+ return run_fetch_values(
313
+ self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
314
+ )
315
+ except Exception as exc:
316
+ raise classify(
317
+ exc, query_name=name, database_name=self._database, role=self._role
318
+ ) from exc
319
+
320
+ def execute(self, query: object, params: Mapping[str, Any] | None = None) -> int:
321
+ """Run a write/DDL statement and return the affected row count."""
322
+ statement, _q, timeout, name = self._resolve(query, params)
323
+ try:
324
+ cursor = run_execute(
325
+ self._conn, statement, params, timeout=timeout, is_postgres=self._is_postgres
326
+ )
327
+ return cursor.rowcount
328
+ except Exception as exc:
329
+ raise classify(
330
+ exc, query_name=name, database_name=self._database, role=self._role
331
+ ) from exc