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
dbkit/_core/circuit.py ADDED
@@ -0,0 +1,130 @@
1
+ """Circuit breaker (§16).
2
+
3
+ One breaker per ``database + shard + role``. It is a pure state machine with the clock
4
+ injected (``now`` is a monotonic timestamp passed in), so it is shared by both frontends and
5
+ fully unit-testable without sleeping.
6
+
7
+ States:
8
+
9
+ * ``CLOSED`` — calls flow; failures inside a rolling window are counted.
10
+ * ``OPEN`` — calls are rejected fast for ``open_seconds`` after the threshold is crossed.
11
+ * ``HALF_OPEN`` — a limited number of trial calls are allowed; a success closes the breaker,
12
+ a failure re-opens it.
13
+
14
+ Only *infrastructure* failures should be reported (connection/pool/availability/timeout) — not
15
+ integrity, programming, or permission errors, which are the caller's fault and would trip the
16
+ breaker for no reason (§16).
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import enum
22
+ from collections import deque
23
+
24
+ from .errors import DatabaseError, ErrorCategory
25
+
26
+ # Categories that indicate the *backend* is unhealthy and should count toward opening (§16).
27
+ TRIPPING_CATEGORIES = frozenset(
28
+ {
29
+ ErrorCategory.AVAILABILITY,
30
+ ErrorCategory.CONNECTION,
31
+ ErrorCategory.POOL,
32
+ ErrorCategory.TIMEOUT,
33
+ }
34
+ )
35
+
36
+
37
+ def counts_as_failure(error: DatabaseError) -> bool:
38
+ """Whether an error should count toward opening the breaker."""
39
+ return error.category in TRIPPING_CATEGORIES
40
+
41
+
42
+ class CircuitState(enum.Enum):
43
+ """A :class:`CircuitBreaker`'s current state."""
44
+
45
+ CLOSED = "closed"
46
+ OPEN = "open"
47
+ HALF_OPEN = "half_open"
48
+
49
+
50
+ class CircuitBreaker:
51
+ """A single breaker. All methods take an explicit monotonic ``now``."""
52
+
53
+ def __init__(
54
+ self,
55
+ *,
56
+ failure_threshold: int = 10,
57
+ window_seconds: float = 30.0,
58
+ open_seconds: float = 10.0,
59
+ half_open_max_calls: int = 2,
60
+ ) -> None:
61
+ """A new breaker, starting ``CLOSED``."""
62
+ self.failure_threshold = failure_threshold
63
+ self.window_seconds = window_seconds
64
+ self.open_seconds = open_seconds
65
+ self.half_open_max_calls = half_open_max_calls
66
+ self._state = CircuitState.CLOSED
67
+ self._failures: deque[float] = deque()
68
+ self._opened_at: float = 0.0
69
+ self._half_open_calls = 0
70
+
71
+ # -- introspection ------------------------------------------------------------ #
72
+
73
+ def state(self, now: float) -> CircuitState:
74
+ """Current state, advancing OPEN -> HALF_OPEN if the cooldown has elapsed."""
75
+ if self._state == CircuitState.OPEN and now - self._opened_at >= self.open_seconds:
76
+ self._state = CircuitState.HALF_OPEN
77
+ self._half_open_calls = 0
78
+ return self._state
79
+
80
+ # -- gate --------------------------------------------------------------------- #
81
+
82
+ def allow(self, now: float) -> bool:
83
+ """Whether a call may proceed. In HALF_OPEN, only a limited number of trials pass."""
84
+ state = self.state(now)
85
+ if state == CircuitState.CLOSED:
86
+ return True
87
+ if state == CircuitState.OPEN:
88
+ return False
89
+ # HALF_OPEN: admit up to half_open_max_calls trial calls.
90
+ if self._half_open_calls < self.half_open_max_calls:
91
+ self._half_open_calls += 1
92
+ return True
93
+ return False
94
+
95
+ # -- feedback ----------------------------------------------------------------- #
96
+
97
+ def on_success(self, now: float) -> None:
98
+ """Record a successful call: closes the breaker from HALF_OPEN, else prunes the window."""
99
+ if self._state == CircuitState.HALF_OPEN:
100
+ self._reset()
101
+ elif self._state == CircuitState.CLOSED:
102
+ self._prune(now)
103
+
104
+ def on_failure(self, now: float) -> None:
105
+ """Record a failing call: re-opens from HALF_OPEN, or opens once the threshold is hit."""
106
+ if self._state == CircuitState.HALF_OPEN:
107
+ self._open(now)
108
+ return
109
+ self._failures.append(now)
110
+ self._prune(now)
111
+ if len(self._failures) >= self.failure_threshold:
112
+ self._open(now)
113
+
114
+ # -- internals ---------------------------------------------------------------- #
115
+
116
+ def _prune(self, now: float) -> None:
117
+ cutoff = now - self.window_seconds
118
+ while self._failures and self._failures[0] < cutoff:
119
+ self._failures.popleft()
120
+
121
+ def _open(self, now: float) -> None:
122
+ self._state = CircuitState.OPEN
123
+ self._opened_at = now
124
+ self._failures.clear()
125
+ self._half_open_calls = 0
126
+
127
+ def _reset(self) -> None:
128
+ self._state = CircuitState.CLOSED
129
+ self._failures.clear()
130
+ self._half_open_calls = 0