spec2py-runtime 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.
- spec2py_runtime/__init__.py +151 -0
- spec2py_runtime/_auth.py +180 -0
- spec2py_runtime/_client.py +809 -0
- spec2py_runtime/_exceptions.py +193 -0
- spec2py_runtime/_files.py +79 -0
- spec2py_runtime/_models.py +260 -0
- spec2py_runtime/_pagination.py +293 -0
- spec2py_runtime/_qs.py +92 -0
- spec2py_runtime/_response.py +98 -0
- spec2py_runtime/_retry.py +77 -0
- spec2py_runtime/_streaming.py +245 -0
- spec2py_runtime/_types.py +71 -0
- spec2py_runtime/_version.py +24 -0
- spec2py_runtime/py.typed +0 -0
- spec2py_runtime-0.1.0.dist-info/METADATA +56 -0
- spec2py_runtime-0.1.0.dist-info/RECORD +18 -0
- spec2py_runtime-0.1.0.dist-info/WHEEL +4 -0
- spec2py_runtime-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
"""Pagination strategies and page objects that iterate lazily across pages.
|
|
2
|
+
|
|
3
|
+
::
|
|
4
|
+
|
|
5
|
+
for invoice in client.invoices.list(status="open"): # every item, every page
|
|
6
|
+
...
|
|
7
|
+
|
|
8
|
+
page = client.invoices.list()
|
|
9
|
+
page.data, page.next_cursor # one page, for manual control
|
|
10
|
+
if page.has_next_page():
|
|
11
|
+
page = page.get_next_page()
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
import re
|
|
15
|
+
from collections.abc import AsyncIterator, Awaitable, Callable, Generator, Iterator
|
|
16
|
+
from dataclasses import dataclass, field
|
|
17
|
+
from typing import Any, Protocol, cast
|
|
18
|
+
|
|
19
|
+
import httpx2
|
|
20
|
+
|
|
21
|
+
__all__ = [
|
|
22
|
+
"AsyncPage",
|
|
23
|
+
"AsyncPaginator",
|
|
24
|
+
"CursorPagination",
|
|
25
|
+
"LinkHeaderPagination",
|
|
26
|
+
"NextPage",
|
|
27
|
+
"OffsetPagination",
|
|
28
|
+
"Page",
|
|
29
|
+
"PageNumberPagination",
|
|
30
|
+
"PageState",
|
|
31
|
+
"PaginationStrategy",
|
|
32
|
+
"dig",
|
|
33
|
+
]
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def dig(body: object, path: str | None) -> object:
|
|
37
|
+
"""Look up a dotted path (``"meta.next_cursor"``) in decoded JSON."""
|
|
38
|
+
if not path:
|
|
39
|
+
return body
|
|
40
|
+
current = body
|
|
41
|
+
for part in path.split("."):
|
|
42
|
+
if not isinstance(current, dict):
|
|
43
|
+
return None
|
|
44
|
+
current = cast(dict[str, object], current).get(part)
|
|
45
|
+
return current
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclass(frozen=True, slots=True)
|
|
49
|
+
class PageState:
|
|
50
|
+
"""What a strategy sees about the page just fetched."""
|
|
51
|
+
|
|
52
|
+
params: dict[str, object]
|
|
53
|
+
body: object
|
|
54
|
+
headers: httpx2.Headers
|
|
55
|
+
items: list[object]
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
@dataclass(frozen=True, slots=True)
|
|
59
|
+
class NextPage:
|
|
60
|
+
"""How to fetch the next page: query overrides, or a whole new URL."""
|
|
61
|
+
|
|
62
|
+
params: dict[str, object] = field(default_factory=dict[str, object])
|
|
63
|
+
url: str | None = None
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
class PaginationStrategy(Protocol):
|
|
67
|
+
@property
|
|
68
|
+
def items(self) -> str | None:
|
|
69
|
+
"""Dotted path to the item array in the body (``None``: the body is the array)."""
|
|
70
|
+
...
|
|
71
|
+
|
|
72
|
+
def next_page(self, state: PageState) -> NextPage | None: ...
|
|
73
|
+
|
|
74
|
+
def next_cursor(self, state: PageState) -> str | None: ...
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _more(state: PageState, has_more: str | None) -> bool:
|
|
78
|
+
if not state.items:
|
|
79
|
+
return False
|
|
80
|
+
return not (has_more and dig(state.body, has_more) is False)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
@dataclass(frozen=True, slots=True)
|
|
84
|
+
class CursorPagination:
|
|
85
|
+
"""Opaque cursors: ``?cursor=`` from a body field or from the last item's id."""
|
|
86
|
+
|
|
87
|
+
items: str | None = "data"
|
|
88
|
+
cursor_param: str = "cursor"
|
|
89
|
+
next_cursor_path: str | None = "next_cursor"
|
|
90
|
+
has_more: str | None = None
|
|
91
|
+
cursor_from_item: str | None = None
|
|
92
|
+
|
|
93
|
+
def next_cursor(self, state: PageState) -> str | None:
|
|
94
|
+
if self.cursor_from_item:
|
|
95
|
+
if not state.items:
|
|
96
|
+
return None
|
|
97
|
+
value = dig(state.items[-1], self.cursor_from_item)
|
|
98
|
+
else:
|
|
99
|
+
value = dig(state.body, self.next_cursor_path)
|
|
100
|
+
return None if value in (None, "") else str(value)
|
|
101
|
+
|
|
102
|
+
def next_page(self, state: PageState) -> NextPage | None:
|
|
103
|
+
if self.has_more and dig(state.body, self.has_more) is False:
|
|
104
|
+
return None
|
|
105
|
+
cursor = self.next_cursor(state)
|
|
106
|
+
if cursor is None:
|
|
107
|
+
return None
|
|
108
|
+
if cursor.startswith(("http://", "https://", "/")):
|
|
109
|
+
return NextPage(url=cursor)
|
|
110
|
+
return NextPage(params={self.cursor_param: cursor})
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
@dataclass(frozen=True, slots=True)
|
|
114
|
+
class OffsetPagination:
|
|
115
|
+
"""``?offset=&limit=`` paging."""
|
|
116
|
+
|
|
117
|
+
items: str | None = "data"
|
|
118
|
+
offset_param: str = "offset"
|
|
119
|
+
limit_param: str | None = "limit"
|
|
120
|
+
total: str | None = None
|
|
121
|
+
has_more: str | None = None
|
|
122
|
+
|
|
123
|
+
def next_cursor(self, state: PageState) -> str | None:
|
|
124
|
+
return None
|
|
125
|
+
|
|
126
|
+
def next_page(self, state: PageState) -> NextPage | None:
|
|
127
|
+
if not _more(state, self.has_more):
|
|
128
|
+
return None
|
|
129
|
+
offset = int(cast(Any, state.params.get(self.offset_param)) or 0)
|
|
130
|
+
next_offset = offset + len(state.items)
|
|
131
|
+
total = dig(state.body, self.total) if self.total else None
|
|
132
|
+
if isinstance(total, int) and next_offset >= total:
|
|
133
|
+
return None
|
|
134
|
+
limit = state.params.get(self.limit_param) if self.limit_param else None
|
|
135
|
+
if total is None and isinstance(limit, int) and len(state.items) < limit:
|
|
136
|
+
return None
|
|
137
|
+
return NextPage(params={self.offset_param: next_offset})
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
@dataclass(frozen=True, slots=True)
|
|
141
|
+
class PageNumberPagination:
|
|
142
|
+
"""``?page=N`` paging, counting from ``start``."""
|
|
143
|
+
|
|
144
|
+
items: str | None = "data"
|
|
145
|
+
page_param: str = "page"
|
|
146
|
+
total_pages: str | None = None
|
|
147
|
+
has_more: str | None = None
|
|
148
|
+
start: int = 1
|
|
149
|
+
|
|
150
|
+
def next_cursor(self, state: PageState) -> str | None:
|
|
151
|
+
return None
|
|
152
|
+
|
|
153
|
+
def next_page(self, state: PageState) -> NextPage | None:
|
|
154
|
+
if not _more(state, self.has_more):
|
|
155
|
+
return None
|
|
156
|
+
page = int(cast(Any, state.params.get(self.page_param)) or self.start)
|
|
157
|
+
total_pages = dig(state.body, self.total_pages) if self.total_pages else None
|
|
158
|
+
if isinstance(total_pages, int) and page + 1 - self.start >= total_pages:
|
|
159
|
+
return None
|
|
160
|
+
return NextPage(params={self.page_param: page + 1})
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
_LINK_RE = re.compile(r"<([^>]*)>\s*((?:;\s*[^;,]+)*)")
|
|
164
|
+
_REL_NEXT_RE = re.compile(r'rel\s*=\s*"?([^";]*\s)?next(\s[^";]*)?"?')
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
@dataclass(frozen=True, slots=True)
|
|
168
|
+
class LinkHeaderPagination:
|
|
169
|
+
"""RFC 8288 ``Link: <...>; rel="next"`` paging (GitHub style)."""
|
|
170
|
+
|
|
171
|
+
items: str | None = None
|
|
172
|
+
|
|
173
|
+
def next_cursor(self, state: PageState) -> str | None:
|
|
174
|
+
link = state.headers.get("link")
|
|
175
|
+
if not link:
|
|
176
|
+
return None
|
|
177
|
+
for url, params in _LINK_RE.findall(link):
|
|
178
|
+
if _REL_NEXT_RE.search(params):
|
|
179
|
+
return str(url)
|
|
180
|
+
return None
|
|
181
|
+
|
|
182
|
+
def next_page(self, state: PageState) -> NextPage | None:
|
|
183
|
+
url = self.next_cursor(state)
|
|
184
|
+
return NextPage(url=url) if url and state.items else None
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
class _BasePage[T]:
|
|
188
|
+
def __init__(
|
|
189
|
+
self,
|
|
190
|
+
*,
|
|
191
|
+
data: list[T],
|
|
192
|
+
response: httpx2.Response,
|
|
193
|
+
state: PageState,
|
|
194
|
+
strategy: PaginationStrategy,
|
|
195
|
+
) -> None:
|
|
196
|
+
self.data = data
|
|
197
|
+
self.response = response
|
|
198
|
+
self._state = state
|
|
199
|
+
self._strategy = strategy
|
|
200
|
+
|
|
201
|
+
@property
|
|
202
|
+
def next_cursor(self) -> str | None:
|
|
203
|
+
"""The cursor (or next URL) for the following page, if any."""
|
|
204
|
+
return self._strategy.next_cursor(self._state)
|
|
205
|
+
|
|
206
|
+
def has_next_page(self) -> bool:
|
|
207
|
+
return self._strategy.next_page(self._state) is not None
|
|
208
|
+
|
|
209
|
+
def _next(self) -> NextPage:
|
|
210
|
+
next_page = self._strategy.next_page(self._state)
|
|
211
|
+
if next_page is None:
|
|
212
|
+
raise RuntimeError("No next page; check has_next_page() first.")
|
|
213
|
+
return next_page
|
|
214
|
+
|
|
215
|
+
def __repr__(self) -> str:
|
|
216
|
+
return f"{type(self).__name__}(data={self.data!r})"
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
class Page[T](_BasePage[T]):
|
|
220
|
+
"""One page of results; iterating it walks every item on every later page."""
|
|
221
|
+
|
|
222
|
+
def __init__(
|
|
223
|
+
self,
|
|
224
|
+
*,
|
|
225
|
+
data: list[T],
|
|
226
|
+
response: httpx2.Response,
|
|
227
|
+
state: PageState,
|
|
228
|
+
strategy: PaginationStrategy,
|
|
229
|
+
fetch: Callable[[NextPage], Page[T]],
|
|
230
|
+
) -> None:
|
|
231
|
+
super().__init__(data=data, response=response, state=state, strategy=strategy)
|
|
232
|
+
self._fetch = fetch
|
|
233
|
+
|
|
234
|
+
def get_next_page(self) -> Page[T]:
|
|
235
|
+
return self._fetch(self._next())
|
|
236
|
+
|
|
237
|
+
def iter_pages(self) -> Iterator[Page[T]]:
|
|
238
|
+
page = self
|
|
239
|
+
yield page
|
|
240
|
+
while page.has_next_page():
|
|
241
|
+
page = page.get_next_page()
|
|
242
|
+
yield page
|
|
243
|
+
|
|
244
|
+
def __iter__(self) -> Iterator[T]:
|
|
245
|
+
for page in self.iter_pages():
|
|
246
|
+
yield from page.data
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
class AsyncPage[T](_BasePage[T]):
|
|
250
|
+
"""One page of results; ``async for`` walks every item on every later page."""
|
|
251
|
+
|
|
252
|
+
def __init__(
|
|
253
|
+
self,
|
|
254
|
+
*,
|
|
255
|
+
data: list[T],
|
|
256
|
+
response: httpx2.Response,
|
|
257
|
+
state: PageState,
|
|
258
|
+
strategy: PaginationStrategy,
|
|
259
|
+
fetch: Callable[[NextPage], Awaitable[AsyncPage[T]]],
|
|
260
|
+
) -> None:
|
|
261
|
+
super().__init__(data=data, response=response, state=state, strategy=strategy)
|
|
262
|
+
self._fetch = fetch
|
|
263
|
+
|
|
264
|
+
async def get_next_page(self) -> AsyncPage[T]:
|
|
265
|
+
return await self._fetch(self._next())
|
|
266
|
+
|
|
267
|
+
async def iter_pages(self) -> AsyncIterator[AsyncPage[T]]:
|
|
268
|
+
page = self
|
|
269
|
+
yield page
|
|
270
|
+
while page.has_next_page():
|
|
271
|
+
page = await page.get_next_page()
|
|
272
|
+
yield page
|
|
273
|
+
|
|
274
|
+
async def __aiter__(self) -> AsyncIterator[T]:
|
|
275
|
+
async for page in self.iter_pages():
|
|
276
|
+
for item in page.data:
|
|
277
|
+
yield item
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
class AsyncPaginator[T]:
|
|
281
|
+
"""Returned by async list methods: ``await`` it for the first page, or ``async for``
|
|
282
|
+
over it for every item."""
|
|
283
|
+
|
|
284
|
+
def __init__(self, fetch_first: Callable[[], Awaitable[AsyncPage[T]]]) -> None:
|
|
285
|
+
self._fetch_first = fetch_first
|
|
286
|
+
|
|
287
|
+
def __await__(self) -> Generator[Any, None, AsyncPage[T]]:
|
|
288
|
+
return self._fetch_first().__await__()
|
|
289
|
+
|
|
290
|
+
async def __aiter__(self) -> AsyncIterator[T]:
|
|
291
|
+
page = await self._fetch_first()
|
|
292
|
+
async for item in page:
|
|
293
|
+
yield item
|
spec2py_runtime/_qs.py
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
"""Serialize path and query parameters following OpenAPI ``style``/``explode`` rules."""
|
|
2
|
+
|
|
3
|
+
import enum
|
|
4
|
+
import urllib.parse
|
|
5
|
+
from collections.abc import Mapping, Sequence
|
|
6
|
+
from datetime import date, datetime, time
|
|
7
|
+
from typing import Literal, cast
|
|
8
|
+
|
|
9
|
+
import pydantic
|
|
10
|
+
|
|
11
|
+
from ._types import NotGiven
|
|
12
|
+
|
|
13
|
+
__all__ = ["QueryStyle", "encode_query", "path_template", "query_param"]
|
|
14
|
+
|
|
15
|
+
type QueryStyle = Literal["form", "spaceDelimited", "pipeDelimited", "deepObject"]
|
|
16
|
+
type QueryItems = list[tuple[str, str]]
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def _scalar(value: object) -> str:
|
|
20
|
+
match value:
|
|
21
|
+
case bool():
|
|
22
|
+
return "true" if value else "false"
|
|
23
|
+
case None:
|
|
24
|
+
return ""
|
|
25
|
+
case enum.Enum():
|
|
26
|
+
return _scalar(value.value)
|
|
27
|
+
case datetime() | date() | time():
|
|
28
|
+
return value.isoformat()
|
|
29
|
+
case _:
|
|
30
|
+
return str(value)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _as_mapping(value: object) -> Mapping[str, object] | None:
|
|
34
|
+
if isinstance(value, pydantic.BaseModel):
|
|
35
|
+
return cast(dict[str, object], value.model_dump(mode="json", by_alias=True))
|
|
36
|
+
if isinstance(value, Mapping):
|
|
37
|
+
return cast(Mapping[str, object], value)
|
|
38
|
+
return None
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def query_param(
|
|
42
|
+
name: str,
|
|
43
|
+
value: object,
|
|
44
|
+
*,
|
|
45
|
+
style: QueryStyle = "form",
|
|
46
|
+
explode: bool = True,
|
|
47
|
+
) -> QueryItems:
|
|
48
|
+
"""Encode one query parameter into ``(key, value)`` pairs."""
|
|
49
|
+
if isinstance(value, NotGiven):
|
|
50
|
+
return []
|
|
51
|
+
if (mapping := _as_mapping(value)) is not None:
|
|
52
|
+
if style == "deepObject":
|
|
53
|
+
return [(f"{name}[{k}]", _scalar(v)) for k, v in mapping.items()]
|
|
54
|
+
if explode:
|
|
55
|
+
return [(k, _scalar(v)) for k, v in mapping.items()]
|
|
56
|
+
flat = ",".join(f"{k},{_scalar(v)}" for k, v in mapping.items())
|
|
57
|
+
return [(name, flat)]
|
|
58
|
+
if isinstance(value, Sequence) and not isinstance(value, str | bytes):
|
|
59
|
+
items = [_scalar(v) for v in cast(Sequence[object], value)]
|
|
60
|
+
if explode and style == "form":
|
|
61
|
+
return [(name, v) for v in items]
|
|
62
|
+
sep = {"spaceDelimited": " ", "pipeDelimited": "|"}.get(style, ",")
|
|
63
|
+
return [(name, sep.join(items))]
|
|
64
|
+
return [(name, _scalar(value))]
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def encode_query(
|
|
68
|
+
params: Mapping[str, object],
|
|
69
|
+
styles: Mapping[str, tuple[QueryStyle, bool]] | None = None,
|
|
70
|
+
) -> QueryItems:
|
|
71
|
+
"""Encode a mapping of query parameters, skipping ``NOT_GIVEN`` values.
|
|
72
|
+
|
|
73
|
+
``styles`` maps a parameter name to its ``(style, explode)`` when it isn't the
|
|
74
|
+
OpenAPI default of ``("form", True)``.
|
|
75
|
+
"""
|
|
76
|
+
items: QueryItems = []
|
|
77
|
+
for name, value in params.items():
|
|
78
|
+
style, explode = (styles or {}).get(name, ("form", True))
|
|
79
|
+
items.extend(query_param(name, value, style=style, explode=explode))
|
|
80
|
+
return items
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def path_template(template: str, /, **values: object) -> str:
|
|
84
|
+
"""Fill ``{name}`` placeholders in a path, percent-encoding each value."""
|
|
85
|
+
out = template
|
|
86
|
+
for name, value in values.items():
|
|
87
|
+
if isinstance(value, Sequence) and not isinstance(value, str | bytes):
|
|
88
|
+
text = ",".join(_scalar(v) for v in cast(Sequence[object], value))
|
|
89
|
+
else:
|
|
90
|
+
text = _scalar(value)
|
|
91
|
+
out = out.replace("{" + name + "}", urllib.parse.quote(text, safe=""))
|
|
92
|
+
return out
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
"""Raw responses: status, headers and the undecoded body, alongside the typed parse.
|
|
2
|
+
|
|
3
|
+
::
|
|
4
|
+
|
|
5
|
+
raw = client.with_raw_response.invoices.retrieve("inv_1")
|
|
6
|
+
raw.status_code, raw.headers["x-request-id"]
|
|
7
|
+
invoice = raw.parse()
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
import contextvars
|
|
11
|
+
import functools
|
|
12
|
+
import json
|
|
13
|
+
from collections.abc import Awaitable, Callable
|
|
14
|
+
from typing import Any, Final, cast
|
|
15
|
+
|
|
16
|
+
import httpx2
|
|
17
|
+
|
|
18
|
+
__all__ = [
|
|
19
|
+
"APIResponse",
|
|
20
|
+
"async_to_raw_response_wrapper",
|
|
21
|
+
"raw_response_requested",
|
|
22
|
+
"to_raw_response_wrapper",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
_RAW_RESPONSE: Final = contextvars.ContextVar("spec2py_raw_response", default=False)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def raw_response_requested() -> bool:
|
|
29
|
+
return _RAW_RESPONSE.get()
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class APIResponse[T]:
|
|
33
|
+
"""An HTTP response plus a lazy, typed ``parse()``."""
|
|
34
|
+
|
|
35
|
+
def __init__(self, http_response: httpx2.Response, parse: Callable[[], T]) -> None:
|
|
36
|
+
self.http_response = http_response
|
|
37
|
+
self._parse = parse
|
|
38
|
+
self._parsed: list[T] = []
|
|
39
|
+
|
|
40
|
+
@property
|
|
41
|
+
def status_code(self) -> int:
|
|
42
|
+
return self.http_response.status_code
|
|
43
|
+
|
|
44
|
+
@property
|
|
45
|
+
def headers(self) -> httpx2.Headers:
|
|
46
|
+
return self.http_response.headers
|
|
47
|
+
|
|
48
|
+
@property
|
|
49
|
+
def content(self) -> bytes:
|
|
50
|
+
return self.http_response.content
|
|
51
|
+
|
|
52
|
+
@property
|
|
53
|
+
def text(self) -> str:
|
|
54
|
+
return self.http_response.text
|
|
55
|
+
|
|
56
|
+
def json(self) -> Any:
|
|
57
|
+
return json.loads(self.http_response.content)
|
|
58
|
+
|
|
59
|
+
def parse(self) -> T:
|
|
60
|
+
"""Parse the body into the operation's declared return type (cached)."""
|
|
61
|
+
if not self._parsed:
|
|
62
|
+
self._parsed.append(self._parse())
|
|
63
|
+
return self._parsed[0]
|
|
64
|
+
|
|
65
|
+
def __repr__(self) -> str:
|
|
66
|
+
return f"<APIResponse [{self.status_code}] {self.http_response.url}>"
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def to_raw_response_wrapper[**P, R](
|
|
70
|
+
func: Callable[P, R],
|
|
71
|
+
) -> Callable[P, APIResponse[R]]:
|
|
72
|
+
"""Wrap a sync resource method so it returns :class:`APIResponse` instead."""
|
|
73
|
+
|
|
74
|
+
@functools.wraps(func)
|
|
75
|
+
def wrapped(*args: P.args, **kwargs: P.kwargs) -> APIResponse[R]:
|
|
76
|
+
token = _RAW_RESPONSE.set(True)
|
|
77
|
+
try:
|
|
78
|
+
return cast(APIResponse[R], func(*args, **kwargs))
|
|
79
|
+
finally:
|
|
80
|
+
_RAW_RESPONSE.reset(token)
|
|
81
|
+
|
|
82
|
+
return wrapped
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def async_to_raw_response_wrapper[**P, R](
|
|
86
|
+
func: Callable[P, Awaitable[R]],
|
|
87
|
+
) -> Callable[P, Awaitable[APIResponse[R]]]:
|
|
88
|
+
"""Wrap an async resource method so it returns :class:`APIResponse` instead."""
|
|
89
|
+
|
|
90
|
+
@functools.wraps(func)
|
|
91
|
+
async def wrapped(*args: P.args, **kwargs: P.kwargs) -> APIResponse[R]:
|
|
92
|
+
token = _RAW_RESPONSE.set(True)
|
|
93
|
+
try:
|
|
94
|
+
return cast(APIResponse[R], await func(*args, **kwargs))
|
|
95
|
+
finally:
|
|
96
|
+
_RAW_RESPONSE.reset(token)
|
|
97
|
+
|
|
98
|
+
return wrapped
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
"""Retry policy: which failures to retry, and how long to wait between attempts."""
|
|
2
|
+
|
|
3
|
+
import contextlib
|
|
4
|
+
import email.utils
|
|
5
|
+
import random
|
|
6
|
+
import time
|
|
7
|
+
from dataclasses import dataclass
|
|
8
|
+
from typing import Final
|
|
9
|
+
|
|
10
|
+
import httpx2
|
|
11
|
+
|
|
12
|
+
__all__ = ["IDEMPOTENT_METHODS", "RetryPolicy"]
|
|
13
|
+
|
|
14
|
+
IDEMPOTENT_METHODS: Final = frozenset(
|
|
15
|
+
{"GET", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", "QUERY"}
|
|
16
|
+
)
|
|
17
|
+
_RETRY_STATUSES: Final = frozenset({408, 409, 429, 500, 502, 503, 504})
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@dataclass(frozen=True, slots=True)
|
|
21
|
+
class RetryPolicy:
|
|
22
|
+
"""Exponential backoff with jitter that honours ``Retry-After``.
|
|
23
|
+
|
|
24
|
+
Requests are retried only when they are safe to repeat: idempotent methods,
|
|
25
|
+
or any method carrying an idempotency key. A server may force the decision
|
|
26
|
+
either way with an ``x-should-retry: true|false`` header.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
max_retries: int = 2
|
|
30
|
+
initial_delay: float = 0.5
|
|
31
|
+
max_delay: float = 8.0
|
|
32
|
+
jitter: float = 0.25
|
|
33
|
+
max_retry_after: float = 60.0
|
|
34
|
+
retry_statuses: frozenset[int] = _RETRY_STATUSES
|
|
35
|
+
|
|
36
|
+
def can_retry(
|
|
37
|
+
self, request: httpx2.Request, idempotency_header: str | None
|
|
38
|
+
) -> bool:
|
|
39
|
+
if request.method.upper() in IDEMPOTENT_METHODS:
|
|
40
|
+
return True
|
|
41
|
+
return bool(idempotency_header and idempotency_header in request.headers)
|
|
42
|
+
|
|
43
|
+
def should_retry_response(self, response: httpx2.Response) -> bool:
|
|
44
|
+
match response.headers.get("x-should-retry", "").lower():
|
|
45
|
+
case "true":
|
|
46
|
+
return True
|
|
47
|
+
case "false":
|
|
48
|
+
return False
|
|
49
|
+
case _:
|
|
50
|
+
return response.status_code in self.retry_statuses
|
|
51
|
+
|
|
52
|
+
def delay(self, attempt: int, response: httpx2.Response | None = None) -> float:
|
|
53
|
+
"""Seconds to sleep before retry number ``attempt`` (0-based)."""
|
|
54
|
+
if response is not None and (hinted := self._retry_after(response)) is not None:
|
|
55
|
+
return hinted
|
|
56
|
+
backoff = min(self.initial_delay * 2.0**attempt, self.max_delay)
|
|
57
|
+
return backoff * (1 - self.jitter * random.random())
|
|
58
|
+
|
|
59
|
+
def _retry_after(self, response: httpx2.Response) -> float | None:
|
|
60
|
+
headers = response.headers
|
|
61
|
+
seconds: float | None = None
|
|
62
|
+
if (ms := headers.get("retry-after-ms")) is not None:
|
|
63
|
+
with contextlib.suppress(ValueError):
|
|
64
|
+
seconds = float(ms) / 1000
|
|
65
|
+
if seconds is None and (value := headers.get("retry-after")) is not None:
|
|
66
|
+
try:
|
|
67
|
+
seconds = float(value)
|
|
68
|
+
except ValueError:
|
|
69
|
+
try:
|
|
70
|
+
parsed = email.utils.parsedate_to_datetime(value)
|
|
71
|
+
except TypeError, ValueError:
|
|
72
|
+
parsed = None
|
|
73
|
+
if parsed is not None:
|
|
74
|
+
seconds = max(parsed.timestamp() - time.time(), 0.0)
|
|
75
|
+
if seconds is None or not 0 <= seconds <= self.max_retry_after:
|
|
76
|
+
return None
|
|
77
|
+
return seconds
|