bucli 0.6.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.
- bucli/__init__.py +52 -0
- bucli/_version.py +1 -0
- bucli/client.py +274 -0
- bucli/constants.py +92 -0
- bucli/contrib/__init__.py +1 -0
- bucli/contrib/django/__init__.py +6 -0
- bucli/contrib/django/access.py +99 -0
- bucli/contrib/django/admin.py +19 -0
- bucli/contrib/django/apps.py +8 -0
- bucli/contrib/django/conf.py +140 -0
- bucli/contrib/django/exceptions.py +17 -0
- bucli/contrib/django/management/__init__.py +0 -0
- bucli/contrib/django/management/commands/__init__.py +0 -0
- bucli/contrib/django/management/commands/bucli_flush_usage.py +18 -0
- bucli/contrib/django/management/commands/bucli_sync.py +66 -0
- bucli/contrib/django/metering.py +137 -0
- bucli/contrib/django/migrations/0001_initial.py +102 -0
- bucli/contrib/django/migrations/0002_billingaccount_bucli_updated_at.py +15 -0
- bucli/contrib/django/migrations/0003_pendingusage.py +40 -0
- bucli/contrib/django/migrations/__init__.py +0 -0
- bucli/contrib/django/models.py +122 -0
- bucli/contrib/django/services.py +617 -0
- bucli/contrib/django/signals.py +22 -0
- bucli/contrib/django/urls.py +11 -0
- bucli/contrib/django/views.py +50 -0
- bucli/contrib/django/webhooks.py +236 -0
- bucli/errors.py +193 -0
- bucli/keys.py +18 -0
- bucli/metering.py +331 -0
- bucli/objects.py +168 -0
- bucli/py.typed +0 -0
- bucli/resources.py +1002 -0
- bucli/webhook.py +136 -0
- bucli-0.6.0.dist-info/METADATA +541 -0
- bucli-0.6.0.dist-info/RECORD +37 -0
- bucli-0.6.0.dist-info/WHEEL +4 -0
- bucli-0.6.0.dist-info/licenses/LICENSE +21 -0
bucli/metering.py
ADDED
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
"""Reserving metered units without letting Bucli stop your business (spec §2.6).
|
|
2
|
+
|
|
3
|
+
``UsageGuard.reserve`` asks Bucli for a unit right before the irreversible
|
|
4
|
+
act (sending a document). What happens when Bucli does not answer is the
|
|
5
|
+
meter's ``on_unavailable``:
|
|
6
|
+
|
|
7
|
+
- ``allow``: if Bucli does not answer within ``timeout`` (2 s by default) —
|
|
8
|
+
a connection error, a timeout, a 5xx — the unit is let through, queued
|
|
9
|
+
locally with its ``idempotency_key`` and reported later
|
|
10
|
+
(``POST /v1/usage`` with ``occurred_at``) by ``flush()``. Bucli records it
|
|
11
|
+
even beyond the quota (``overage``) and never refuses it.
|
|
12
|
+
- ``deny``: the error is raised; nothing is queued.
|
|
13
|
+
|
|
14
|
+
A refusal of Bucli (``402 quota_exhausted``, ``402 entitlement_access_denied``)
|
|
15
|
+
is an answer, never «unavailable»: it is returned as ``allowed=False``.
|
|
16
|
+
|
|
17
|
+
Each answer of Bucli carries the customer's ``remaining`` (allowance +
|
|
18
|
+
grants; ``-1`` unlimited) and the guard keeps it (``store``), so a customer
|
|
19
|
+
already at zero is refused locally — no call — until ``cache_seconds`` pass
|
|
20
|
+
or ``forget()`` is called (a grant bought, a new plan: on ``grant.created``
|
|
21
|
+
or ``entitlements.updated``).
|
|
22
|
+
|
|
23
|
+
``store`` is where the queue and the balances live: ``MemoryUsageStore`` (one
|
|
24
|
+
process; tests), or ``bucli.contrib.django.metering.DatabaseUsageStore``
|
|
25
|
+
(the database: survives a restart, shared by every worker).
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
from __future__ import annotations
|
|
29
|
+
|
|
30
|
+
import datetime
|
|
31
|
+
import logging
|
|
32
|
+
import threading
|
|
33
|
+
import time
|
|
34
|
+
from dataclasses import dataclass, field
|
|
35
|
+
from typing import TYPE_CHECKING, Any, Protocol
|
|
36
|
+
|
|
37
|
+
from bucli.constants import UNLIMITED
|
|
38
|
+
from bucli.errors import APIConnectionError, APIError, BillingError, BucliError, RateLimitError
|
|
39
|
+
|
|
40
|
+
if TYPE_CHECKING:
|
|
41
|
+
from bucli.client import Bucli
|
|
42
|
+
from bucli.objects import BucliObject
|
|
43
|
+
|
|
44
|
+
logger = logging.getLogger("bucli.metering")
|
|
45
|
+
|
|
46
|
+
ALLOW = "allow"
|
|
47
|
+
DENY = "deny"
|
|
48
|
+
#: Codes of Bucli that refuse a unit (an answer, not an outage).
|
|
49
|
+
REFUSALS = ("quota_exhausted", "entitlement_access_denied")
|
|
50
|
+
#: A conflict that only means «the same request is still running»: wait, as for an outage.
|
|
51
|
+
IN_FLIGHT_CODES = ("idempotency_key_in_use",)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@dataclass
|
|
55
|
+
class Reservation:
|
|
56
|
+
"""What ``UsageGuard.reserve`` decided.
|
|
57
|
+
|
|
58
|
+
``allowed``: go ahead. ``record``: Bucli's ``usage_record`` (``None`` when
|
|
59
|
+
decided without Bucli). ``offline``: let through while Bucli did not
|
|
60
|
+
answer (queued). ``refusal``: Bucli's code when refused (or
|
|
61
|
+
``"quota_exhausted"`` when refused locally). ``remaining``: what the
|
|
62
|
+
customer has left, if known (``-1`` unlimited)."""
|
|
63
|
+
|
|
64
|
+
allowed: bool
|
|
65
|
+
record: BucliObject | None = None
|
|
66
|
+
offline: bool = False
|
|
67
|
+
refusal: str | None = None
|
|
68
|
+
remaining: int | None = None
|
|
69
|
+
error: BucliError | None = None
|
|
70
|
+
|
|
71
|
+
@property
|
|
72
|
+
def usage_id(self) -> str | None:
|
|
73
|
+
return getattr(self.record, "id", None) if self.record is not None else None
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
@dataclass
|
|
77
|
+
class PendingUnit:
|
|
78
|
+
"""A unit let through while Bucli did not answer, waiting to be reported."""
|
|
79
|
+
|
|
80
|
+
meter: str
|
|
81
|
+
customer: str
|
|
82
|
+
idempotency_key: str
|
|
83
|
+
quantity: int
|
|
84
|
+
occurred_at: datetime.datetime
|
|
85
|
+
billable: bool = True
|
|
86
|
+
metadata: dict[str, Any] = field(default_factory=dict)
|
|
87
|
+
attempts: int = 0
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
class UsageStore(Protocol):
|
|
91
|
+
def enqueue(self, unit: PendingUnit) -> None: ...
|
|
92
|
+
|
|
93
|
+
def pending(self, limit: int) -> list[PendingUnit]: ...
|
|
94
|
+
|
|
95
|
+
def done(self, unit: PendingUnit) -> None: ...
|
|
96
|
+
|
|
97
|
+
def failed(self, unit: PendingUnit, error: str) -> None: ...
|
|
98
|
+
|
|
99
|
+
def remember(self, meter: str, customer: str, remaining: int | None) -> None: ...
|
|
100
|
+
|
|
101
|
+
def remaining(self, meter: str, customer: str, max_age: float) -> int | None: ...
|
|
102
|
+
|
|
103
|
+
def forget(self, meter: str | None, customer: str) -> None: ...
|
|
104
|
+
|
|
105
|
+
def discard(self, meter: str, customer: str, idempotency_key: str) -> bool: ...
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
#: A queued unit Bucli refused this many times is left out of the flush
|
|
109
|
+
#: (kept, for a person to look at): a refusal is not an outage.
|
|
110
|
+
MAX_REPORT_ATTEMPTS = 20
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
class MemoryUsageStore:
|
|
114
|
+
"""The queue and the balances in this process (tests, scripts)."""
|
|
115
|
+
|
|
116
|
+
def __init__(self, max_attempts: int = MAX_REPORT_ATTEMPTS) -> None:
|
|
117
|
+
self.max_attempts = max_attempts
|
|
118
|
+
self._lock = threading.Lock()
|
|
119
|
+
self._queue: dict[tuple[str, str, str], PendingUnit] = {}
|
|
120
|
+
self._balances: dict[tuple[str, str], tuple[int, float]] = {}
|
|
121
|
+
|
|
122
|
+
def enqueue(self, unit: PendingUnit) -> None:
|
|
123
|
+
with self._lock:
|
|
124
|
+
self._queue.setdefault((unit.meter, unit.customer, unit.idempotency_key), unit)
|
|
125
|
+
|
|
126
|
+
def pending(self, limit: int) -> list[PendingUnit]:
|
|
127
|
+
with self._lock:
|
|
128
|
+
return [unit for unit in self._queue.values() if unit.attempts < self.max_attempts][:limit]
|
|
129
|
+
|
|
130
|
+
def done(self, unit: PendingUnit) -> None:
|
|
131
|
+
with self._lock:
|
|
132
|
+
self._queue.pop((unit.meter, unit.customer, unit.idempotency_key), None)
|
|
133
|
+
|
|
134
|
+
def failed(self, unit: PendingUnit, error: str) -> None:
|
|
135
|
+
with self._lock:
|
|
136
|
+
unit.attempts += 1
|
|
137
|
+
|
|
138
|
+
def remember(self, meter: str, customer: str, remaining: int | None) -> None:
|
|
139
|
+
with self._lock:
|
|
140
|
+
if remaining is None:
|
|
141
|
+
self._balances.pop((meter, customer), None)
|
|
142
|
+
else:
|
|
143
|
+
self._balances[(meter, customer)] = (remaining, time.monotonic())
|
|
144
|
+
|
|
145
|
+
def remaining(self, meter: str, customer: str, max_age: float) -> int | None:
|
|
146
|
+
with self._lock:
|
|
147
|
+
found = self._balances.get((meter, customer))
|
|
148
|
+
if found is None or time.monotonic() - found[1] > max_age:
|
|
149
|
+
return None
|
|
150
|
+
return found[0]
|
|
151
|
+
|
|
152
|
+
def forget(self, meter: str | None, customer: str) -> None:
|
|
153
|
+
with self._lock:
|
|
154
|
+
for key in [key for key in self._balances if key[1] == customer and meter in (None, key[0])]:
|
|
155
|
+
self._balances.pop(key, None)
|
|
156
|
+
|
|
157
|
+
def discard(self, meter: str, customer: str, idempotency_key: str) -> bool:
|
|
158
|
+
with self._lock:
|
|
159
|
+
return self._queue.pop((meter, customer, idempotency_key), None) is not None
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def _unavailable(error: BucliError) -> bool:
|
|
163
|
+
"""Bucli did not answer (or answered that it cannot now): never the
|
|
164
|
+
unit's fault, so it never spends a report attempt."""
|
|
165
|
+
if isinstance(error, APIConnectionError | RateLimitError):
|
|
166
|
+
return True
|
|
167
|
+
if getattr(error, "code", None) in IN_FLIGHT_CODES:
|
|
168
|
+
return True
|
|
169
|
+
return isinstance(error, APIError) and (error.http_status or 500) >= 500
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def aware(moment: datetime.datetime) -> datetime.datetime:
|
|
173
|
+
"""A moment with its zone (a naive one is taken as UTC)."""
|
|
174
|
+
return (
|
|
175
|
+
moment if moment.tzinfo is not None and moment.utcoffset() is not None else moment.replace(tzinfo=datetime.UTC)
|
|
176
|
+
)
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
def _remaining_of_refusal(error: BucliError) -> int | None:
|
|
180
|
+
"""What a ``402 quota_exhausted`` says is left (cupo + grants), if it says."""
|
|
181
|
+
payload = (error.json_body or {}).get("error") if isinstance(error.json_body, dict) else None
|
|
182
|
+
if not isinstance(payload, dict):
|
|
183
|
+
return None
|
|
184
|
+
allowance, used, grants = payload.get("allowance"), payload.get("used"), payload.get("grants_remaining")
|
|
185
|
+
if not all(isinstance(value, int) for value in (allowance, used, grants)) or allowance == UNLIMITED:
|
|
186
|
+
return None
|
|
187
|
+
return max(allowance - used, 0) + grants
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
class UsageGuard:
|
|
191
|
+
"""``UsageGuard(client, on_unavailable="allow", store=...)``; one per meter
|
|
192
|
+
policy. ``on_unavailable`` may also be a dict ``{meter_key: "allow"|"deny"}``
|
|
193
|
+
(default ``deny`` for a meter not named)."""
|
|
194
|
+
|
|
195
|
+
def __init__(
|
|
196
|
+
self,
|
|
197
|
+
client: Bucli,
|
|
198
|
+
*,
|
|
199
|
+
on_unavailable: str | dict[str, str] = DENY,
|
|
200
|
+
store: UsageStore | None = None,
|
|
201
|
+
timeout: float = 2.0,
|
|
202
|
+
cache_seconds: float = 300.0,
|
|
203
|
+
deny_when_exhausted: bool = True,
|
|
204
|
+
clock: Any = None,
|
|
205
|
+
) -> None:
|
|
206
|
+
self.client = client
|
|
207
|
+
self.on_unavailable = on_unavailable
|
|
208
|
+
self.store = store or MemoryUsageStore()
|
|
209
|
+
self.timeout = timeout
|
|
210
|
+
self.cache_seconds = cache_seconds
|
|
211
|
+
self.deny_when_exhausted = deny_when_exhausted
|
|
212
|
+
self._now = clock or (lambda: datetime.datetime.now(datetime.UTC))
|
|
213
|
+
|
|
214
|
+
def policy(self, meter: str) -> str:
|
|
215
|
+
if isinstance(self.on_unavailable, dict):
|
|
216
|
+
return self.on_unavailable.get(meter, DENY)
|
|
217
|
+
return self.on_unavailable
|
|
218
|
+
|
|
219
|
+
def reserve(
|
|
220
|
+
self,
|
|
221
|
+
meter: str,
|
|
222
|
+
*,
|
|
223
|
+
customer: str,
|
|
224
|
+
idempotency_key: str,
|
|
225
|
+
quantity: int = 1,
|
|
226
|
+
billable: bool = True,
|
|
227
|
+
metadata: dict[str, Any] | None = None,
|
|
228
|
+
) -> Reservation:
|
|
229
|
+
"""Take ``quantity`` units of ``meter`` for ``customer``, or say why not."""
|
|
230
|
+
if billable and self.deny_when_exhausted:
|
|
231
|
+
cached = self.store.remaining(meter, customer, self.cache_seconds)
|
|
232
|
+
if cached is not None and cached != UNLIMITED and cached < quantity:
|
|
233
|
+
return Reservation(allowed=False, refusal="quota_exhausted", remaining=cached)
|
|
234
|
+
try:
|
|
235
|
+
record = self.client.meters.reserve(
|
|
236
|
+
meter,
|
|
237
|
+
customer=customer,
|
|
238
|
+
idempotency_key=idempotency_key,
|
|
239
|
+
quantity=quantity,
|
|
240
|
+
billable=billable,
|
|
241
|
+
metadata=metadata,
|
|
242
|
+
timeout=self.timeout,
|
|
243
|
+
max_retries=0,
|
|
244
|
+
)
|
|
245
|
+
except BillingError as error:
|
|
246
|
+
if error.code in REFUSALS:
|
|
247
|
+
left = _remaining_of_refusal(error) if error.code == "quota_exhausted" else None
|
|
248
|
+
self.store.remember(meter, customer, left)
|
|
249
|
+
return Reservation(allowed=False, refusal=error.code, remaining=left, error=error)
|
|
250
|
+
raise
|
|
251
|
+
except BucliError as error:
|
|
252
|
+
if not _unavailable(error) or self.policy(meter) != ALLOW:
|
|
253
|
+
raise
|
|
254
|
+
self.store.enqueue(
|
|
255
|
+
PendingUnit(
|
|
256
|
+
meter=meter,
|
|
257
|
+
customer=customer,
|
|
258
|
+
idempotency_key=idempotency_key,
|
|
259
|
+
quantity=quantity,
|
|
260
|
+
occurred_at=aware(self._now()),
|
|
261
|
+
billable=billable,
|
|
262
|
+
metadata=dict(metadata or {}),
|
|
263
|
+
)
|
|
264
|
+
)
|
|
265
|
+
return Reservation(allowed=True, offline=True, error=error)
|
|
266
|
+
remaining = getattr(record, "remaining", None)
|
|
267
|
+
self.store.remember(meter, customer, remaining)
|
|
268
|
+
return Reservation(allowed=True, record=record, remaining=remaining)
|
|
269
|
+
|
|
270
|
+
def release(self, usage_id: str) -> BucliObject:
|
|
271
|
+
"""Give a unit back (``POST /v1/usage/{id}/release``); the cached
|
|
272
|
+
balance of its customer is dropped."""
|
|
273
|
+
record = self.client.usage.release(usage_id)
|
|
274
|
+
meter, customer = getattr(record, "meter", None), getattr(record, "customer", None)
|
|
275
|
+
if isinstance(meter, str) and isinstance(customer, str):
|
|
276
|
+
self.store.forget(meter, customer)
|
|
277
|
+
return record
|
|
278
|
+
|
|
279
|
+
def discard(self, meter: str, *, customer: str, idempotency_key: str) -> bool:
|
|
280
|
+
"""Drop a unit let through offline that never happened after all (the
|
|
281
|
+
document was not sent): it is not reported. Whether it was queued."""
|
|
282
|
+
return self.store.discard(meter, customer, idempotency_key)
|
|
283
|
+
|
|
284
|
+
def forget(self, customer: str, meter: str | None = None) -> None:
|
|
285
|
+
"""Drop the cached balance (a grant bought, a plan changed)."""
|
|
286
|
+
self.store.forget(meter, customer)
|
|
287
|
+
|
|
288
|
+
def flush(self, limit: int = 200) -> dict[str, int]:
|
|
289
|
+
"""Report the queued units to Bucli. Returns ``{"reported", "failed"}``;
|
|
290
|
+
what fails stays queued for the next flush."""
|
|
291
|
+
reported = failed = 0
|
|
292
|
+
for unit in self.store.pending(limit):
|
|
293
|
+
try:
|
|
294
|
+
self.client.usage.report(
|
|
295
|
+
meter=unit.meter,
|
|
296
|
+
customer=unit.customer,
|
|
297
|
+
idempotency_key=unit.idempotency_key,
|
|
298
|
+
quantity=unit.quantity,
|
|
299
|
+
occurred_at=aware(unit.occurred_at),
|
|
300
|
+
billable=unit.billable,
|
|
301
|
+
metadata=unit.metadata or None,
|
|
302
|
+
)
|
|
303
|
+
except BucliError as error:
|
|
304
|
+
failed += 1
|
|
305
|
+
if _unavailable(error):
|
|
306
|
+
break # still down: nothing is the units' fault; they wait for the next flush
|
|
307
|
+
self._refused(unit, f"{type(error).__name__}: {error.code or error}")
|
|
308
|
+
continue
|
|
309
|
+
except (TypeError, ValueError) as error: # a unit that cannot be sent: never block the rest
|
|
310
|
+
failed += 1
|
|
311
|
+
self._refused(unit, f"{type(error).__name__}: {error}")
|
|
312
|
+
continue
|
|
313
|
+
self.store.done(unit)
|
|
314
|
+
self.store.forget(unit.meter, unit.customer)
|
|
315
|
+
reported += 1
|
|
316
|
+
return {"reported": reported, "failed": failed}
|
|
317
|
+
|
|
318
|
+
def _refused(self, unit: PendingUnit, error: str) -> None:
|
|
319
|
+
"""Bucli refused a report (not an outage): one attempt spent; past the
|
|
320
|
+
cap the unit stays stored but out of the flush, and it is logged."""
|
|
321
|
+
self.store.failed(unit, error)
|
|
322
|
+
if unit.attempts >= getattr(self.store, "max_attempts", MAX_REPORT_ATTEMPTS):
|
|
323
|
+
logger.error(
|
|
324
|
+
"Bucli refused the report of a metered unit too many times (%s, %s, %s): %s",
|
|
325
|
+
unit.meter,
|
|
326
|
+
unit.customer,
|
|
327
|
+
unit.idempotency_key,
|
|
328
|
+
error,
|
|
329
|
+
)
|
|
330
|
+
else:
|
|
331
|
+
logger.warning("Bucli refused the report of a metered unit (%s): %s", unit.idempotency_key, error)
|
bucli/objects.py
ADDED
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
"""API objects: plain dicts that also read by attribute (``sub.status``).
|
|
2
|
+
|
|
3
|
+
``BucliObject`` IS the dict the API answered (``json.dumps(obj)`` works,
|
|
4
|
+
``obj["status"]`` works); nested objects and lists are converted on the way
|
|
5
|
+
in. A key that clashes with a dict method must be read with brackets — the
|
|
6
|
+
one that matters is a subscription's ``sub["items"]`` (``sub.items`` is
|
|
7
|
+
``dict.items``).
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from collections.abc import Iterator
|
|
13
|
+
from typing import TYPE_CHECKING, Any
|
|
14
|
+
from urllib.parse import parse_qsl, urlsplit
|
|
15
|
+
|
|
16
|
+
if TYPE_CHECKING:
|
|
17
|
+
from bucli.client import Bucli
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class LastResponse:
|
|
21
|
+
"""What the HTTP answer said besides its body."""
|
|
22
|
+
|
|
23
|
+
__slots__ = ("headers", "http_status", "idempotency_key", "request_id")
|
|
24
|
+
|
|
25
|
+
def __init__(self, http_status: int, headers: dict[str, str], idempotency_key: str | None = None) -> None:
|
|
26
|
+
self.http_status = http_status
|
|
27
|
+
self.headers = headers
|
|
28
|
+
self.request_id = headers.get("Request-Id")
|
|
29
|
+
self.idempotency_key = idempotency_key
|
|
30
|
+
|
|
31
|
+
@property
|
|
32
|
+
def replayed(self) -> bool:
|
|
33
|
+
"""``True`` when Bucli answered a stored response for the same ``Idempotency-Key``."""
|
|
34
|
+
return self.headers.get("Idempotent-Replayed", "").lower() == "true"
|
|
35
|
+
|
|
36
|
+
def __repr__(self) -> str:
|
|
37
|
+
return f"LastResponse(http_status={self.http_status}, request_id={self.request_id!r})"
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class BucliObject(dict):
|
|
41
|
+
"""An object of the API (``customer``, ``subscription``…)."""
|
|
42
|
+
|
|
43
|
+
def __init__(self, *args: Any, **kwargs: Any) -> None:
|
|
44
|
+
super().__init__(*args, **kwargs)
|
|
45
|
+
object.__setattr__(self, "_client", None)
|
|
46
|
+
object.__setattr__(self, "last_response", None)
|
|
47
|
+
|
|
48
|
+
# -- attribute access -----------------------------------------------------
|
|
49
|
+
|
|
50
|
+
def __getattr__(self, name: str) -> Any:
|
|
51
|
+
if name.startswith("__"):
|
|
52
|
+
raise AttributeError(name)
|
|
53
|
+
try:
|
|
54
|
+
return self[name]
|
|
55
|
+
except KeyError:
|
|
56
|
+
raise AttributeError(f"{type(self).__name__} no tiene el campo {name!r}") from None
|
|
57
|
+
|
|
58
|
+
def __setattr__(self, name: str, value: Any) -> None:
|
|
59
|
+
if name.startswith("_") or name == "last_response":
|
|
60
|
+
object.__setattr__(self, name, value)
|
|
61
|
+
else:
|
|
62
|
+
self[name] = value
|
|
63
|
+
|
|
64
|
+
def __delattr__(self, name: str) -> None:
|
|
65
|
+
try:
|
|
66
|
+
del self[name]
|
|
67
|
+
except KeyError:
|
|
68
|
+
raise AttributeError(name) from None
|
|
69
|
+
|
|
70
|
+
def __repr__(self) -> str:
|
|
71
|
+
ident = self.get("id")
|
|
72
|
+
kind = self.get("object", type(self).__name__)
|
|
73
|
+
head = f"<{kind} {ident}>" if ident else f"<{kind}>"
|
|
74
|
+
return f"{head} {dict.__repr__(self)}"
|
|
75
|
+
|
|
76
|
+
def __reduce__(self) -> Any:
|
|
77
|
+
return (type(self), (dict(self),))
|
|
78
|
+
|
|
79
|
+
# -- conversion -------------------------------------------------------------
|
|
80
|
+
|
|
81
|
+
@classmethod
|
|
82
|
+
def construct_from(cls, value: Any, client: Bucli | None = None) -> Any:
|
|
83
|
+
"""Converts the JSON the API answered (dicts become objects, lists stay lists)."""
|
|
84
|
+
return convert(value, client)
|
|
85
|
+
|
|
86
|
+
def to_dict(self) -> dict[str, Any]:
|
|
87
|
+
"""A deep copy made only of plain ``dict``/``list`` (for storing or serializing)."""
|
|
88
|
+
return _plain(self)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
class ListObject(BucliObject):
|
|
92
|
+
"""``{"object": "list", "data": [...], "has_more": bool, "url": "/v1/..."}``."""
|
|
93
|
+
|
|
94
|
+
def __init__(self, *args: Any, **kwargs: Any) -> None:
|
|
95
|
+
super().__init__(*args, **kwargs)
|
|
96
|
+
object.__setattr__(self, "_path", None)
|
|
97
|
+
object.__setattr__(self, "_params", {})
|
|
98
|
+
|
|
99
|
+
@property
|
|
100
|
+
def data(self) -> list[Any]:
|
|
101
|
+
return self.get("data") or []
|
|
102
|
+
|
|
103
|
+
@property
|
|
104
|
+
def has_more(self) -> bool:
|
|
105
|
+
return bool(self.get("has_more"))
|
|
106
|
+
|
|
107
|
+
def is_empty(self) -> bool:
|
|
108
|
+
return not self.data
|
|
109
|
+
|
|
110
|
+
def _source(self) -> tuple[str, dict[str, Any]]:
|
|
111
|
+
if self._path:
|
|
112
|
+
return self._path, dict(self._params)
|
|
113
|
+
parts = urlsplit(self.get("url") or "")
|
|
114
|
+
path = parts.path
|
|
115
|
+
if path.startswith("/v1/"):
|
|
116
|
+
path = path[len("/v1") :]
|
|
117
|
+
return path, dict(parse_qsl(parts.query))
|
|
118
|
+
|
|
119
|
+
def next_page(self) -> ListObject:
|
|
120
|
+
"""The page after this one (``starting_after`` = the last id)."""
|
|
121
|
+
path, params = self._source()
|
|
122
|
+
params.pop("ending_before", None)
|
|
123
|
+
params["starting_after"] = self.data[-1]["id"]
|
|
124
|
+
return self._client._get_list(path, params)
|
|
125
|
+
|
|
126
|
+
def previous_page(self) -> ListObject:
|
|
127
|
+
"""The page before this one (``ending_before`` = the first id)."""
|
|
128
|
+
path, params = self._source()
|
|
129
|
+
params.pop("starting_after", None)
|
|
130
|
+
params["ending_before"] = self.data[0]["id"]
|
|
131
|
+
return self._client._get_list(path, params)
|
|
132
|
+
|
|
133
|
+
def auto_paging_iter(self) -> Iterator[Any]:
|
|
134
|
+
"""Every object from this page on, fetching the next pages as needed.
|
|
135
|
+
|
|
136
|
+
A page fetched with ``ending_before`` walks backwards (towards newer
|
|
137
|
+
objects), as Stripe's does."""
|
|
138
|
+
if self._client is None:
|
|
139
|
+
yield from self.data
|
|
140
|
+
return
|
|
141
|
+
_, params = self._source()
|
|
142
|
+
backwards = "ending_before" in params and "starting_after" not in params
|
|
143
|
+
page: ListObject = self
|
|
144
|
+
while True:
|
|
145
|
+
items = list(reversed(page.data)) if backwards else page.data
|
|
146
|
+
yield from items
|
|
147
|
+
if not page.has_more or not page.data:
|
|
148
|
+
return
|
|
149
|
+
page = page.previous_page() if backwards else page.next_page()
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def convert(value: Any, client: Bucli | None = None) -> Any:
|
|
153
|
+
if isinstance(value, dict) and not isinstance(value, BucliObject):
|
|
154
|
+
cls = ListObject if value.get("object") == "list" else BucliObject
|
|
155
|
+
obj = cls({key: convert(item, client) for key, item in value.items()})
|
|
156
|
+
object.__setattr__(obj, "_client", client)
|
|
157
|
+
return obj
|
|
158
|
+
if isinstance(value, list):
|
|
159
|
+
return [convert(item, client) for item in value]
|
|
160
|
+
return value
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def _plain(value: Any) -> Any:
|
|
164
|
+
if isinstance(value, dict):
|
|
165
|
+
return {key: _plain(item) for key, item in value.items()}
|
|
166
|
+
if isinstance(value, list):
|
|
167
|
+
return [_plain(item) for item in value]
|
|
168
|
+
return value
|
bucli/py.typed
ADDED
|
File without changes
|