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,809 @@
|
|
|
1
|
+
"""The HTTP core shared by every generated client.
|
|
2
|
+
|
|
3
|
+
Generated clients subclass :class:`APIClient` / :class:`AsyncAPIClient` and their
|
|
4
|
+
resources subclass :class:`APIResource` / :class:`AsyncAPIResource`. All request
|
|
5
|
+
behaviour (retries, auth, hooks, tracing, parsing, errors) lives here, so fixing
|
|
6
|
+
it is a dependency upgrade rather than a regeneration.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import copy
|
|
10
|
+
import functools
|
|
11
|
+
import inspect
|
|
12
|
+
import json
|
|
13
|
+
import logging
|
|
14
|
+
import platform
|
|
15
|
+
import time
|
|
16
|
+
import uuid
|
|
17
|
+
from collections.abc import (
|
|
18
|
+
Awaitable,
|
|
19
|
+
Callable,
|
|
20
|
+
Collection,
|
|
21
|
+
Mapping,
|
|
22
|
+
Sequence,
|
|
23
|
+
)
|
|
24
|
+
from dataclasses import dataclass, field
|
|
25
|
+
from types import NoneType, TracebackType
|
|
26
|
+
from typing import Any, Final, Required, Self, TypedDict, Unpack, cast
|
|
27
|
+
|
|
28
|
+
import anyio
|
|
29
|
+
import httpx2
|
|
30
|
+
from pydantic import ValidationError
|
|
31
|
+
|
|
32
|
+
from ._exceptions import (
|
|
33
|
+
APIConnectionError,
|
|
34
|
+
APIResponseValidationError,
|
|
35
|
+
APIStatusError,
|
|
36
|
+
APITimeoutError,
|
|
37
|
+
PaginationOriginError,
|
|
38
|
+
status_error_class,
|
|
39
|
+
)
|
|
40
|
+
from ._files import to_httpx_files, to_multipart_data
|
|
41
|
+
from ._models import jsonable, parse_value
|
|
42
|
+
from ._pagination import (
|
|
43
|
+
AsyncPage,
|
|
44
|
+
AsyncPaginator,
|
|
45
|
+
NextPage,
|
|
46
|
+
Page,
|
|
47
|
+
PageState,
|
|
48
|
+
PaginationStrategy,
|
|
49
|
+
dig,
|
|
50
|
+
)
|
|
51
|
+
from ._qs import QueryStyle, encode_query
|
|
52
|
+
from ._response import APIResponse, raw_response_requested
|
|
53
|
+
from ._retry import RetryPolicy
|
|
54
|
+
from ._streaming import (
|
|
55
|
+
AsyncStream,
|
|
56
|
+
AsyncStreamManager,
|
|
57
|
+
Stream,
|
|
58
|
+
StreamFormat,
|
|
59
|
+
StreamManager,
|
|
60
|
+
)
|
|
61
|
+
from ._types import NOT_GIVEN, FileTypes, NotGiven, TimeoutTypes
|
|
62
|
+
|
|
63
|
+
try:
|
|
64
|
+
from ._version import __version__
|
|
65
|
+
except ImportError: # pragma: no cover - running from a source checkout
|
|
66
|
+
__version__ = "0.0.0"
|
|
67
|
+
|
|
68
|
+
__all__ = [
|
|
69
|
+
"DEFAULT_MAX_RETRIES",
|
|
70
|
+
"DEFAULT_TIMEOUT",
|
|
71
|
+
"APIClient",
|
|
72
|
+
"APIResource",
|
|
73
|
+
"AsyncAPIClient",
|
|
74
|
+
"AsyncAPIResource",
|
|
75
|
+
"ClientOptions",
|
|
76
|
+
"Hooks",
|
|
77
|
+
"RequestOptions",
|
|
78
|
+
"RequestSpec",
|
|
79
|
+
"__version__",
|
|
80
|
+
]
|
|
81
|
+
|
|
82
|
+
logger = logging.getLogger("spec2py")
|
|
83
|
+
|
|
84
|
+
DEFAULT_TIMEOUT: Final = httpx2.Timeout(60.0, connect=5.0)
|
|
85
|
+
DEFAULT_MAX_RETRIES: Final = 2
|
|
86
|
+
|
|
87
|
+
type ErrorMap = Mapping[int | str, object]
|
|
88
|
+
type RequestHook = Callable[[httpx2.Request], object]
|
|
89
|
+
type ResponseHook = Callable[[httpx2.Response], object]
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
@dataclass(slots=True)
|
|
93
|
+
class Hooks:
|
|
94
|
+
"""Request and response middleware.
|
|
95
|
+
|
|
96
|
+
Hooks run on every attempt, including retries. Async clients await hooks that
|
|
97
|
+
return awaitables; sync clients call them plainly. Use them for logging,
|
|
98
|
+
metrics, request signing or test doubles.
|
|
99
|
+
"""
|
|
100
|
+
|
|
101
|
+
on_request: list[RequestHook] = field(default_factory=list[RequestHook])
|
|
102
|
+
on_response: list[ResponseHook] = field(default_factory=list[ResponseHook])
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
@dataclass(slots=True, kw_only=True)
|
|
106
|
+
class RequestSpec:
|
|
107
|
+
"""Everything a generated method knows about one call."""
|
|
108
|
+
|
|
109
|
+
method: str
|
|
110
|
+
path: str
|
|
111
|
+
query: Mapping[str, object] | None = None
|
|
112
|
+
query_styles: Mapping[str, tuple[QueryStyle, bool]] | None = None
|
|
113
|
+
headers: Mapping[str, object] | None = None
|
|
114
|
+
cookies: Mapping[str, object] | None = None
|
|
115
|
+
body: object = NOT_GIVEN
|
|
116
|
+
form: Mapping[str, object] | None = None
|
|
117
|
+
files: Mapping[str, FileTypes | Sequence[FileTypes] | NotGiven | None] | None = None
|
|
118
|
+
content: bytes | NotGiven | None = None
|
|
119
|
+
content_type: str | None = None
|
|
120
|
+
security: bool = True
|
|
121
|
+
errors: ErrorMap | None = None
|
|
122
|
+
extra_headers: Mapping[str, object] | None = None
|
|
123
|
+
extra_query: Mapping[str, object] | None = None
|
|
124
|
+
extra_body: Mapping[str, object] | None = None
|
|
125
|
+
timeout: TimeoutTypes | NotGiven = NOT_GIVEN
|
|
126
|
+
url: str | None = None
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
class RequestOptions(TypedDict, total=False):
|
|
130
|
+
"""Keyword arguments generated methods pass through to :class:`RequestSpec`."""
|
|
131
|
+
|
|
132
|
+
query: Mapping[str, object] | None
|
|
133
|
+
query_styles: Mapping[str, tuple[QueryStyle, bool]] | None
|
|
134
|
+
headers: Mapping[str, object] | None
|
|
135
|
+
cookies: Mapping[str, object] | None
|
|
136
|
+
body: object
|
|
137
|
+
form: Mapping[str, object] | None
|
|
138
|
+
files: Mapping[str, FileTypes | Sequence[FileTypes] | NotGiven | None] | None
|
|
139
|
+
content: bytes | NotGiven | None
|
|
140
|
+
content_type: str | None
|
|
141
|
+
security: bool
|
|
142
|
+
errors: ErrorMap | None
|
|
143
|
+
extra_headers: Mapping[str, object] | None
|
|
144
|
+
extra_query: Mapping[str, object] | None
|
|
145
|
+
extra_body: Mapping[str, object] | None
|
|
146
|
+
timeout: TimeoutTypes | NotGiven
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
class ClientOptions(TypedDict, total=False):
|
|
150
|
+
"""The keyword arguments both clients pass through to the shared core."""
|
|
151
|
+
|
|
152
|
+
base_url: Required[str]
|
|
153
|
+
auth: httpx2.Auth | None
|
|
154
|
+
timeout: TimeoutTypes
|
|
155
|
+
max_retries: int
|
|
156
|
+
default_headers: Mapping[str, str] | None
|
|
157
|
+
default_query: Mapping[str, object] | None
|
|
158
|
+
hooks: Hooks | None
|
|
159
|
+
idempotency_header: str | None
|
|
160
|
+
strict_response_validation: bool
|
|
161
|
+
trusted_pagination_origins: Collection[str]
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
def _header_value(value: object) -> str:
|
|
165
|
+
if isinstance(value, bool):
|
|
166
|
+
return "true" if value else "false"
|
|
167
|
+
return str(value)
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def _decode_body(response: httpx2.Response) -> object:
|
|
171
|
+
if not response.content:
|
|
172
|
+
return None
|
|
173
|
+
content_type = response.headers.get("content-type", "")
|
|
174
|
+
if "json" in content_type or not content_type:
|
|
175
|
+
try:
|
|
176
|
+
return json.loads(response.content)
|
|
177
|
+
except ValueError:
|
|
178
|
+
return response.text
|
|
179
|
+
return response.text
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
class _BaseClient:
|
|
183
|
+
"""Request building, parsing and error mapping shared by both clients."""
|
|
184
|
+
|
|
185
|
+
_package: str = "spec2py-client"
|
|
186
|
+
_version: str = "0"
|
|
187
|
+
|
|
188
|
+
def __init__(
|
|
189
|
+
self,
|
|
190
|
+
*,
|
|
191
|
+
base_url: str,
|
|
192
|
+
auth: httpx2.Auth | None = None,
|
|
193
|
+
timeout: TimeoutTypes = DEFAULT_TIMEOUT,
|
|
194
|
+
max_retries: int = DEFAULT_MAX_RETRIES,
|
|
195
|
+
default_headers: Mapping[str, str] | None = None,
|
|
196
|
+
default_query: Mapping[str, object] | None = None,
|
|
197
|
+
hooks: Hooks | None = None,
|
|
198
|
+
idempotency_header: str | None = None,
|
|
199
|
+
strict_response_validation: bool = True,
|
|
200
|
+
trusted_pagination_origins: Collection[str] = (),
|
|
201
|
+
) -> None:
|
|
202
|
+
self.base_url = base_url
|
|
203
|
+
self.auth = auth
|
|
204
|
+
self.timeout = timeout
|
|
205
|
+
self.max_retries = max_retries
|
|
206
|
+
self.default_headers = dict(default_headers or {})
|
|
207
|
+
self.default_query = dict(default_query or {})
|
|
208
|
+
self.hooks = hooks or Hooks()
|
|
209
|
+
self.idempotency_header = idempotency_header
|
|
210
|
+
self.strict_response_validation = strict_response_validation
|
|
211
|
+
self.trusted_pagination_origins = frozenset(
|
|
212
|
+
_parse_origin(o) for o in trusted_pagination_origins
|
|
213
|
+
)
|
|
214
|
+
self._base_url = httpx2.URL(base_url)
|
|
215
|
+
self._base_origin = _origin(self._base_url)
|
|
216
|
+
self._owns_http_client = True
|
|
217
|
+
|
|
218
|
+
@functools.cached_property
|
|
219
|
+
def user_agent(self) -> str:
|
|
220
|
+
return (
|
|
221
|
+
f"{self._package}/{self._version} spec2py-runtime/{__version__} "
|
|
222
|
+
f"python/{platform.python_version()}"
|
|
223
|
+
)
|
|
224
|
+
|
|
225
|
+
@property
|
|
226
|
+
def retry_policy(self) -> RetryPolicy:
|
|
227
|
+
return RetryPolicy(max_retries=self.max_retries)
|
|
228
|
+
|
|
229
|
+
def with_options(
|
|
230
|
+
self,
|
|
231
|
+
*,
|
|
232
|
+
timeout: TimeoutTypes | NotGiven = NOT_GIVEN,
|
|
233
|
+
max_retries: int | NotGiven = NOT_GIVEN,
|
|
234
|
+
default_headers: Mapping[str, str] | NotGiven = NOT_GIVEN,
|
|
235
|
+
auth: httpx2.Auth | NotGiven | None = NOT_GIVEN,
|
|
236
|
+
) -> Self:
|
|
237
|
+
"""Return a copy of this client with some options changed.
|
|
238
|
+
|
|
239
|
+
The copy shares the underlying connection pool::
|
|
240
|
+
|
|
241
|
+
client.with_options(timeout=5, max_retries=0).invoices.retrieve("inv_1")
|
|
242
|
+
"""
|
|
243
|
+
new = copy.copy(self)
|
|
244
|
+
# Resources are cached per client; drop them so they bind to the copy.
|
|
245
|
+
for name in _cached_property_names(type(new).__mro__):
|
|
246
|
+
new.__dict__.pop(name, None)
|
|
247
|
+
new._owns_http_client = False
|
|
248
|
+
if not isinstance(timeout, NotGiven):
|
|
249
|
+
new.timeout = timeout
|
|
250
|
+
if not isinstance(max_retries, NotGiven):
|
|
251
|
+
new.max_retries = max_retries
|
|
252
|
+
if not isinstance(default_headers, NotGiven):
|
|
253
|
+
new.default_headers = {**self.default_headers, **default_headers}
|
|
254
|
+
if not isinstance(auth, NotGiven):
|
|
255
|
+
new.auth = auth
|
|
256
|
+
return new
|
|
257
|
+
|
|
258
|
+
# -- building ---------------------------------------------------------------
|
|
259
|
+
|
|
260
|
+
def _build_request(
|
|
261
|
+
self,
|
|
262
|
+
http: httpx2.Client | httpx2.AsyncClient,
|
|
263
|
+
spec: RequestSpec,
|
|
264
|
+
*,
|
|
265
|
+
idempotency_key: str | None,
|
|
266
|
+
retries_taken: int,
|
|
267
|
+
) -> httpx2.Request:
|
|
268
|
+
headers: dict[str, str] = {
|
|
269
|
+
"Accept": "application/json",
|
|
270
|
+
"User-Agent": self.user_agent,
|
|
271
|
+
**self.default_headers,
|
|
272
|
+
}
|
|
273
|
+
for source in (spec.headers, spec.extra_headers):
|
|
274
|
+
for key, value in (source or {}).items():
|
|
275
|
+
if isinstance(value, NotGiven):
|
|
276
|
+
headers.pop(key, None)
|
|
277
|
+
elif value is not None:
|
|
278
|
+
headers[key] = _header_value(value)
|
|
279
|
+
if idempotency_key and self.idempotency_header:
|
|
280
|
+
headers.setdefault(self.idempotency_header, idempotency_key)
|
|
281
|
+
if retries_taken:
|
|
282
|
+
headers["x-retry-count"] = str(retries_taken)
|
|
283
|
+
|
|
284
|
+
params = encode_query(self.default_query)
|
|
285
|
+
params += encode_query(spec.query or {}, spec.query_styles)
|
|
286
|
+
params += encode_query(spec.extra_query or {})
|
|
287
|
+
|
|
288
|
+
if spec.cookies:
|
|
289
|
+
pairs = [
|
|
290
|
+
f"{k}={_header_value(v)}"
|
|
291
|
+
for k, v in spec.cookies.items()
|
|
292
|
+
if not isinstance(v, NotGiven) and v is not None
|
|
293
|
+
]
|
|
294
|
+
if pairs:
|
|
295
|
+
headers["Cookie"] = "; ".join(pairs)
|
|
296
|
+
|
|
297
|
+
kwargs: dict[str, Any] = {}
|
|
298
|
+
if spec.files or spec.form is not None:
|
|
299
|
+
form = {**(spec.form or {}), **(spec.extra_body or {})}
|
|
300
|
+
kwargs["data"] = to_multipart_data(form)
|
|
301
|
+
if spec.files:
|
|
302
|
+
kwargs["files"] = to_httpx_files(spec.files)
|
|
303
|
+
elif spec.content is not None and not isinstance(spec.content, NotGiven):
|
|
304
|
+
kwargs["content"] = spec.content
|
|
305
|
+
headers.setdefault(
|
|
306
|
+
"Content-Type", spec.content_type or "application/octet-stream"
|
|
307
|
+
)
|
|
308
|
+
elif not isinstance(spec.body, NotGiven) or spec.extra_body:
|
|
309
|
+
body: object = {}
|
|
310
|
+
if not isinstance(spec.body, NotGiven):
|
|
311
|
+
body = jsonable(spec.body)
|
|
312
|
+
if spec.extra_body:
|
|
313
|
+
if not isinstance(body, dict):
|
|
314
|
+
raise TypeError("extra_body requires a JSON object request body")
|
|
315
|
+
body = {**cast(dict[str, object], body), **spec.extra_body}
|
|
316
|
+
kwargs["json"] = body
|
|
317
|
+
if spec.content_type:
|
|
318
|
+
headers["Content-Type"] = spec.content_type
|
|
319
|
+
|
|
320
|
+
timeout = self.timeout if isinstance(spec.timeout, NotGiven) else spec.timeout
|
|
321
|
+
url = spec.url or spec.path
|
|
322
|
+
return http.build_request(
|
|
323
|
+
spec.method.upper(),
|
|
324
|
+
url,
|
|
325
|
+
params=cast(Any, params) or None,
|
|
326
|
+
headers=headers,
|
|
327
|
+
timeout=timeout,
|
|
328
|
+
**kwargs,
|
|
329
|
+
)
|
|
330
|
+
|
|
331
|
+
def _new_idempotency_key(self, spec: RequestSpec) -> str | None:
|
|
332
|
+
if self.idempotency_header and spec.method.upper() not in {"GET", "HEAD"}:
|
|
333
|
+
return f"spec2py-retry-{uuid.uuid4()}"
|
|
334
|
+
return None
|
|
335
|
+
|
|
336
|
+
@staticmethod
|
|
337
|
+
def _transport_retry_reason(
|
|
338
|
+
exc: httpx2.TransportError, request: httpx2.Request, retryable: bool
|
|
339
|
+
) -> str:
|
|
340
|
+
"""Why a failed send is retried; raises the client error when it isn't."""
|
|
341
|
+
timed_out = isinstance(exc, httpx2.TimeoutException)
|
|
342
|
+
if not retryable:
|
|
343
|
+
error = APITimeoutError if timed_out else APIConnectionError
|
|
344
|
+
raise error(request) from exc
|
|
345
|
+
return "timeout" if timed_out else type(exc).__name__
|
|
346
|
+
|
|
347
|
+
@staticmethod
|
|
348
|
+
def _stream_spec(
|
|
349
|
+
method: str, path: str, stream_format: StreamFormat, options: RequestOptions
|
|
350
|
+
) -> RequestSpec:
|
|
351
|
+
spec = RequestSpec(method=method, path=path, **options)
|
|
352
|
+
accept = (
|
|
353
|
+
"text/event-stream" if stream_format == "sse" else "application/x-ndjson"
|
|
354
|
+
)
|
|
355
|
+
spec.extra_headers = {"Accept": accept, **(spec.extra_headers or {})}
|
|
356
|
+
return spec
|
|
357
|
+
|
|
358
|
+
# -- parsing ----------------------------------------------------------------
|
|
359
|
+
|
|
360
|
+
def _make_status_error(
|
|
361
|
+
self, response: httpx2.Response, errors: ErrorMap | None
|
|
362
|
+
) -> APIStatusError:
|
|
363
|
+
body = _decode_body(response)
|
|
364
|
+
parsed: object | None = None
|
|
365
|
+
status = response.status_code
|
|
366
|
+
model = None
|
|
367
|
+
if errors:
|
|
368
|
+
model = (
|
|
369
|
+
errors.get(status)
|
|
370
|
+
or errors.get(f"{status // 100}XX")
|
|
371
|
+
or errors.get("default")
|
|
372
|
+
)
|
|
373
|
+
if model is not None and body is not None:
|
|
374
|
+
try:
|
|
375
|
+
parsed = parse_value(cast(Any, model), body, strict=True)
|
|
376
|
+
except ValidationError:
|
|
377
|
+
parsed = None
|
|
378
|
+
message = self._error_message(body) or response.reason_phrase or "Error"
|
|
379
|
+
return status_error_class(status)(
|
|
380
|
+
message, response=response, body=body, parsed=parsed
|
|
381
|
+
)
|
|
382
|
+
|
|
383
|
+
@staticmethod
|
|
384
|
+
def _error_message(body: object) -> str | None:
|
|
385
|
+
if isinstance(body, str):
|
|
386
|
+
return body[:500] or None
|
|
387
|
+
if isinstance(body, dict):
|
|
388
|
+
data = cast(dict[str, object], body)
|
|
389
|
+
for key in ("message", "detail", "error_description", "title"):
|
|
390
|
+
if isinstance(data.get(key), str):
|
|
391
|
+
return cast(str, data[key])
|
|
392
|
+
error = data.get("error")
|
|
393
|
+
if isinstance(error, str):
|
|
394
|
+
return error
|
|
395
|
+
if isinstance(error, dict):
|
|
396
|
+
message = cast(dict[str, object], error).get("message")
|
|
397
|
+
if isinstance(message, str):
|
|
398
|
+
return message
|
|
399
|
+
return json.dumps(data)[:500]
|
|
400
|
+
return None
|
|
401
|
+
|
|
402
|
+
def _parse[T](self, response: httpx2.Response, cast_to: type[T]) -> T:
|
|
403
|
+
if cast_to is NoneType:
|
|
404
|
+
return cast(T, None)
|
|
405
|
+
if cast_to is httpx2.Response:
|
|
406
|
+
return cast(T, response)
|
|
407
|
+
if cast_to is bytes:
|
|
408
|
+
return cast(T, response.content)
|
|
409
|
+
if cast_to is str:
|
|
410
|
+
return cast(T, response.text)
|
|
411
|
+
body = _decode_body(response)
|
|
412
|
+
try:
|
|
413
|
+
return parse_value(cast_to, body, strict=self.strict_response_validation)
|
|
414
|
+
except ValidationError as exc:
|
|
415
|
+
raise APIResponseValidationError(response, body, str(exc)) from exc
|
|
416
|
+
|
|
417
|
+
def _result[T](self, response: httpx2.Response, cast_to: type[T]) -> T:
|
|
418
|
+
if raw_response_requested():
|
|
419
|
+
raw = APIResponse(response, lambda: self._parse(response, cast_to))
|
|
420
|
+
return cast(T, raw)
|
|
421
|
+
return self._parse(response, cast_to)
|
|
422
|
+
|
|
423
|
+
def _page_parts[T](
|
|
424
|
+
self,
|
|
425
|
+
response: httpx2.Response,
|
|
426
|
+
item_type: type[T],
|
|
427
|
+
strategy: PaginationStrategy,
|
|
428
|
+
params: dict[str, object],
|
|
429
|
+
) -> tuple[list[T], PageState]:
|
|
430
|
+
body = _decode_body(response)
|
|
431
|
+
raw_items = dig(body, strategy.items)
|
|
432
|
+
items = cast(list[object], raw_items) if isinstance(raw_items, list) else []
|
|
433
|
+
try:
|
|
434
|
+
data = parse_value(
|
|
435
|
+
list[item_type], # type: ignore[valid-type]
|
|
436
|
+
items,
|
|
437
|
+
strict=self.strict_response_validation,
|
|
438
|
+
)
|
|
439
|
+
except ValidationError as exc:
|
|
440
|
+
raise APIResponseValidationError(response, body, str(exc)) from exc
|
|
441
|
+
state = PageState(
|
|
442
|
+
params=params, body=body, headers=response.headers, items=items
|
|
443
|
+
)
|
|
444
|
+
return data, state
|
|
445
|
+
|
|
446
|
+
def _next_spec(
|
|
447
|
+
self, spec: RequestSpec, next_page: NextPage, response: httpx2.Response
|
|
448
|
+
) -> RequestSpec:
|
|
449
|
+
new = copy.copy(spec)
|
|
450
|
+
if next_page.url is not None:
|
|
451
|
+
self._check_page_url(next_page.url, response)
|
|
452
|
+
new.url = next_page.url
|
|
453
|
+
new.query = None
|
|
454
|
+
new.query_styles = None
|
|
455
|
+
else:
|
|
456
|
+
new.query = {**(spec.query or {}), **next_page.params}
|
|
457
|
+
return new
|
|
458
|
+
|
|
459
|
+
def _check_page_url(self, url: str, response: httpx2.Response) -> None:
|
|
460
|
+
"""Refuse next-page URLs the server points at another origin.
|
|
461
|
+
|
|
462
|
+
The follow-up request carries the client's auth, default headers and
|
|
463
|
+
query, and the operation's header and cookie parameters, so following
|
|
464
|
+
a foreign ``Link``/cursor URL would hand those credentials to that host.
|
|
465
|
+
Scheme counts too: https -> http on the same host is refused.
|
|
466
|
+
"""
|
|
467
|
+
target = _origin(self._base_url.join(url))
|
|
468
|
+
if target == self._base_origin or target in self.trusted_pagination_origins:
|
|
469
|
+
return
|
|
470
|
+
raise PaginationOriginError(
|
|
471
|
+
url, base_url=self.base_url, request=response.request
|
|
472
|
+
)
|
|
473
|
+
|
|
474
|
+
|
|
475
|
+
@functools.cache
|
|
476
|
+
def _cached_property_names(mro: tuple[type, ...]) -> tuple[str, ...]:
|
|
477
|
+
return tuple(
|
|
478
|
+
name
|
|
479
|
+
for klass in mro
|
|
480
|
+
for name, attr in vars(klass).items()
|
|
481
|
+
if isinstance(attr, functools.cached_property)
|
|
482
|
+
)
|
|
483
|
+
|
|
484
|
+
|
|
485
|
+
type Origin = tuple[str, str, int | None]
|
|
486
|
+
|
|
487
|
+
_DEFAULT_PORTS: Final = {"http": 80, "https": 443}
|
|
488
|
+
|
|
489
|
+
|
|
490
|
+
def _origin(url: httpx2.URL) -> Origin:
|
|
491
|
+
scheme = url.scheme.lower()
|
|
492
|
+
return scheme, url.host.lower(), url.port or _DEFAULT_PORTS.get(scheme)
|
|
493
|
+
|
|
494
|
+
|
|
495
|
+
def _parse_origin(value: str) -> Origin:
|
|
496
|
+
url = httpx2.URL(value)
|
|
497
|
+
if url.scheme not in _DEFAULT_PORTS or not url.host:
|
|
498
|
+
raise ValueError(
|
|
499
|
+
f"trusted pagination origin {value!r} must look like 'https://host[:port]'"
|
|
500
|
+
)
|
|
501
|
+
return _origin(url)
|
|
502
|
+
|
|
503
|
+
|
|
504
|
+
def _query_dict(spec: RequestSpec) -> dict[str, object]:
|
|
505
|
+
return {k: v for k, v in (spec.query or {}).items() if not isinstance(v, NotGiven)}
|
|
506
|
+
|
|
507
|
+
|
|
508
|
+
class APIClient(_BaseClient):
|
|
509
|
+
"""Synchronous HTTP core. Generated sync clients subclass this."""
|
|
510
|
+
|
|
511
|
+
def __init__(
|
|
512
|
+
self,
|
|
513
|
+
*,
|
|
514
|
+
http_client: httpx2.Client | None = None,
|
|
515
|
+
transport: httpx2.BaseTransport | None = None,
|
|
516
|
+
**options: Unpack[ClientOptions],
|
|
517
|
+
) -> None:
|
|
518
|
+
super().__init__(**options)
|
|
519
|
+
self._owns_http_client = http_client is None
|
|
520
|
+
self._http = http_client or httpx2.Client(
|
|
521
|
+
base_url=self._base_url, timeout=self.timeout, transport=transport
|
|
522
|
+
)
|
|
523
|
+
if http_client is not None:
|
|
524
|
+
self._http.base_url = self._base_url
|
|
525
|
+
|
|
526
|
+
def close(self) -> None:
|
|
527
|
+
if self._owns_http_client:
|
|
528
|
+
self._http.close()
|
|
529
|
+
|
|
530
|
+
def __enter__(self) -> Self:
|
|
531
|
+
return self
|
|
532
|
+
|
|
533
|
+
def __exit__(
|
|
534
|
+
self,
|
|
535
|
+
exc_type: type[BaseException] | None,
|
|
536
|
+
exc: BaseException | None,
|
|
537
|
+
tb: TracebackType | None,
|
|
538
|
+
) -> None:
|
|
539
|
+
self.close()
|
|
540
|
+
|
|
541
|
+
def _send(self, spec: RequestSpec, *, stream: bool = False) -> httpx2.Response:
|
|
542
|
+
policy = self.retry_policy
|
|
543
|
+
key = self._new_idempotency_key(spec)
|
|
544
|
+
auth = self.auth if spec.security else None
|
|
545
|
+
retries_taken = 0
|
|
546
|
+
while True:
|
|
547
|
+
request = self._build_request(
|
|
548
|
+
self._http, spec, idempotency_key=key, retries_taken=retries_taken
|
|
549
|
+
)
|
|
550
|
+
retryable = retries_taken < policy.max_retries and policy.can_retry(
|
|
551
|
+
request, self.idempotency_header
|
|
552
|
+
)
|
|
553
|
+
for hook in self.hooks.on_request:
|
|
554
|
+
hook(request)
|
|
555
|
+
try:
|
|
556
|
+
response = self._http.send(request, stream=stream, auth=auth)
|
|
557
|
+
except httpx2.TransportError as exc:
|
|
558
|
+
reason = self._transport_retry_reason(exc, request, retryable)
|
|
559
|
+
self._sleep(policy.delay(retries_taken), reason)
|
|
560
|
+
retries_taken += 1
|
|
561
|
+
continue
|
|
562
|
+
for response_hook in self.hooks.on_response:
|
|
563
|
+
response_hook(response)
|
|
564
|
+
if response.is_error:
|
|
565
|
+
if retryable and policy.should_retry_response(response):
|
|
566
|
+
response.close()
|
|
567
|
+
delay = policy.delay(retries_taken, response)
|
|
568
|
+
self._sleep(delay, str(response.status_code))
|
|
569
|
+
retries_taken += 1
|
|
570
|
+
continue
|
|
571
|
+
if stream:
|
|
572
|
+
response.read()
|
|
573
|
+
response.close()
|
|
574
|
+
raise self._make_status_error(response, spec.errors)
|
|
575
|
+
return response
|
|
576
|
+
|
|
577
|
+
@staticmethod
|
|
578
|
+
def _sleep(seconds: float, reason: str) -> None:
|
|
579
|
+
logger.info("Retrying request in %.2fs (%s)", seconds, reason)
|
|
580
|
+
time.sleep(seconds)
|
|
581
|
+
|
|
582
|
+
def request[T](
|
|
583
|
+
self,
|
|
584
|
+
method: str,
|
|
585
|
+
path: str,
|
|
586
|
+
*,
|
|
587
|
+
cast_to: type[T],
|
|
588
|
+
**kwargs: Unpack[RequestOptions],
|
|
589
|
+
) -> T:
|
|
590
|
+
"""Send one request and parse its body into ``cast_to``."""
|
|
591
|
+
spec = RequestSpec(method=method, path=path, **kwargs)
|
|
592
|
+
return self._result(self._send(spec), cast_to)
|
|
593
|
+
|
|
594
|
+
def get_api_list[T](
|
|
595
|
+
self,
|
|
596
|
+
method: str,
|
|
597
|
+
path: str,
|
|
598
|
+
*,
|
|
599
|
+
item_type: type[T],
|
|
600
|
+
strategy: PaginationStrategy,
|
|
601
|
+
**kwargs: Unpack[RequestOptions],
|
|
602
|
+
) -> Page[T]:
|
|
603
|
+
"""Fetch the first page of a paginated operation."""
|
|
604
|
+
spec = RequestSpec(method=method, path=path, **kwargs)
|
|
605
|
+
|
|
606
|
+
def fetch(spec: RequestSpec) -> Page[T]:
|
|
607
|
+
response = self._send(spec)
|
|
608
|
+
data, state = self._page_parts(
|
|
609
|
+
response, item_type, strategy, _query_dict(spec)
|
|
610
|
+
)
|
|
611
|
+
return Page(
|
|
612
|
+
data=data,
|
|
613
|
+
response=response,
|
|
614
|
+
state=state,
|
|
615
|
+
strategy=strategy,
|
|
616
|
+
fetch=lambda next_page: fetch(
|
|
617
|
+
self._next_spec(spec, next_page, response)
|
|
618
|
+
),
|
|
619
|
+
)
|
|
620
|
+
|
|
621
|
+
return fetch(spec)
|
|
622
|
+
|
|
623
|
+
def stream[T](
|
|
624
|
+
self,
|
|
625
|
+
method: str,
|
|
626
|
+
path: str,
|
|
627
|
+
*,
|
|
628
|
+
event_type: type[T],
|
|
629
|
+
stream_format: StreamFormat = "sse",
|
|
630
|
+
terminator: str | None = "[DONE]",
|
|
631
|
+
**kwargs: Unpack[RequestOptions],
|
|
632
|
+
) -> StreamManager[T]:
|
|
633
|
+
"""Prepare a streaming request; it is sent when the manager is entered."""
|
|
634
|
+
spec = self._stream_spec(method, path, stream_format, kwargs)
|
|
635
|
+
|
|
636
|
+
def open_stream() -> Stream[T]:
|
|
637
|
+
response = self._send(spec, stream=True)
|
|
638
|
+
return Stream(
|
|
639
|
+
response,
|
|
640
|
+
event_type=event_type,
|
|
641
|
+
stream_format=stream_format,
|
|
642
|
+
terminator=terminator,
|
|
643
|
+
strict=self.strict_response_validation,
|
|
644
|
+
)
|
|
645
|
+
|
|
646
|
+
return StreamManager(open_stream)
|
|
647
|
+
|
|
648
|
+
|
|
649
|
+
class AsyncAPIClient(_BaseClient):
|
|
650
|
+
"""Asynchronous HTTP core. Generated async clients subclass this."""
|
|
651
|
+
|
|
652
|
+
def __init__(
|
|
653
|
+
self,
|
|
654
|
+
*,
|
|
655
|
+
http_client: httpx2.AsyncClient | None = None,
|
|
656
|
+
transport: httpx2.AsyncBaseTransport | None = None,
|
|
657
|
+
**options: Unpack[ClientOptions],
|
|
658
|
+
) -> None:
|
|
659
|
+
super().__init__(**options)
|
|
660
|
+
self._owns_http_client = http_client is None
|
|
661
|
+
self._http = http_client or httpx2.AsyncClient(
|
|
662
|
+
base_url=self._base_url, timeout=self.timeout, transport=transport
|
|
663
|
+
)
|
|
664
|
+
if http_client is not None:
|
|
665
|
+
self._http.base_url = self._base_url
|
|
666
|
+
|
|
667
|
+
async def close(self) -> None:
|
|
668
|
+
if self._owns_http_client:
|
|
669
|
+
await self._http.aclose()
|
|
670
|
+
|
|
671
|
+
async def __aenter__(self) -> Self:
|
|
672
|
+
return self
|
|
673
|
+
|
|
674
|
+
async def __aexit__(
|
|
675
|
+
self,
|
|
676
|
+
exc_type: type[BaseException] | None,
|
|
677
|
+
exc: BaseException | None,
|
|
678
|
+
tb: TracebackType | None,
|
|
679
|
+
) -> None:
|
|
680
|
+
await self.close()
|
|
681
|
+
|
|
682
|
+
@staticmethod
|
|
683
|
+
async def _call_hook(hook: Callable[[Any], object], arg: object) -> None:
|
|
684
|
+
result = hook(arg)
|
|
685
|
+
if inspect.isawaitable(result):
|
|
686
|
+
await cast(Awaitable[object], result)
|
|
687
|
+
|
|
688
|
+
async def _send(
|
|
689
|
+
self, spec: RequestSpec, *, stream: bool = False
|
|
690
|
+
) -> httpx2.Response:
|
|
691
|
+
policy = self.retry_policy
|
|
692
|
+
key = self._new_idempotency_key(spec)
|
|
693
|
+
auth = self.auth if spec.security else None
|
|
694
|
+
retries_taken = 0
|
|
695
|
+
while True:
|
|
696
|
+
request = self._build_request(
|
|
697
|
+
self._http, spec, idempotency_key=key, retries_taken=retries_taken
|
|
698
|
+
)
|
|
699
|
+
retryable = retries_taken < policy.max_retries and policy.can_retry(
|
|
700
|
+
request, self.idempotency_header
|
|
701
|
+
)
|
|
702
|
+
for hook in self.hooks.on_request:
|
|
703
|
+
await self._call_hook(hook, request)
|
|
704
|
+
try:
|
|
705
|
+
response = await self._http.send(request, stream=stream, auth=auth)
|
|
706
|
+
except httpx2.TransportError as exc:
|
|
707
|
+
reason = self._transport_retry_reason(exc, request, retryable)
|
|
708
|
+
await self._sleep(policy.delay(retries_taken), reason)
|
|
709
|
+
retries_taken += 1
|
|
710
|
+
continue
|
|
711
|
+
for response_hook in self.hooks.on_response:
|
|
712
|
+
await self._call_hook(response_hook, response)
|
|
713
|
+
if response.is_error:
|
|
714
|
+
if retryable and policy.should_retry_response(response):
|
|
715
|
+
await response.aclose()
|
|
716
|
+
delay = policy.delay(retries_taken, response)
|
|
717
|
+
await self._sleep(delay, str(response.status_code))
|
|
718
|
+
retries_taken += 1
|
|
719
|
+
continue
|
|
720
|
+
if stream:
|
|
721
|
+
await response.aread()
|
|
722
|
+
await response.aclose()
|
|
723
|
+
raise self._make_status_error(response, spec.errors)
|
|
724
|
+
return response
|
|
725
|
+
|
|
726
|
+
@staticmethod
|
|
727
|
+
async def _sleep(seconds: float, reason: str) -> None:
|
|
728
|
+
logger.info("Retrying request in %.2fs (%s)", seconds, reason)
|
|
729
|
+
await anyio.sleep(seconds)
|
|
730
|
+
|
|
731
|
+
async def request[T](
|
|
732
|
+
self,
|
|
733
|
+
method: str,
|
|
734
|
+
path: str,
|
|
735
|
+
*,
|
|
736
|
+
cast_to: type[T],
|
|
737
|
+
**kwargs: Unpack[RequestOptions],
|
|
738
|
+
) -> T:
|
|
739
|
+
"""Send one request and parse its body into ``cast_to``."""
|
|
740
|
+
spec = RequestSpec(method=method, path=path, **kwargs)
|
|
741
|
+
return self._result(await self._send(spec), cast_to)
|
|
742
|
+
|
|
743
|
+
def get_api_list[T](
|
|
744
|
+
self,
|
|
745
|
+
method: str,
|
|
746
|
+
path: str,
|
|
747
|
+
*,
|
|
748
|
+
item_type: type[T],
|
|
749
|
+
strategy: PaginationStrategy,
|
|
750
|
+
**kwargs: Unpack[RequestOptions],
|
|
751
|
+
) -> AsyncPaginator[T]:
|
|
752
|
+
"""Return a paginator: ``await`` it for the first page or iterate every item."""
|
|
753
|
+
spec = RequestSpec(method=method, path=path, **kwargs)
|
|
754
|
+
|
|
755
|
+
async def fetch(spec: RequestSpec) -> AsyncPage[T]:
|
|
756
|
+
response = await self._send(spec)
|
|
757
|
+
data, state = self._page_parts(
|
|
758
|
+
response, item_type, strategy, _query_dict(spec)
|
|
759
|
+
)
|
|
760
|
+
return AsyncPage(
|
|
761
|
+
data=data,
|
|
762
|
+
response=response,
|
|
763
|
+
state=state,
|
|
764
|
+
strategy=strategy,
|
|
765
|
+
fetch=lambda next_page: fetch(
|
|
766
|
+
self._next_spec(spec, next_page, response)
|
|
767
|
+
),
|
|
768
|
+
)
|
|
769
|
+
|
|
770
|
+
return AsyncPaginator(lambda: fetch(spec))
|
|
771
|
+
|
|
772
|
+
def stream[T](
|
|
773
|
+
self,
|
|
774
|
+
method: str,
|
|
775
|
+
path: str,
|
|
776
|
+
*,
|
|
777
|
+
event_type: type[T],
|
|
778
|
+
stream_format: StreamFormat = "sse",
|
|
779
|
+
terminator: str | None = "[DONE]",
|
|
780
|
+
**kwargs: Unpack[RequestOptions],
|
|
781
|
+
) -> AsyncStreamManager[T]:
|
|
782
|
+
"""Prepare a streaming request; it is sent when the manager is entered."""
|
|
783
|
+
spec = self._stream_spec(method, path, stream_format, kwargs)
|
|
784
|
+
|
|
785
|
+
async def open_stream() -> AsyncStream[T]:
|
|
786
|
+
response = await self._send(spec, stream=True)
|
|
787
|
+
return AsyncStream(
|
|
788
|
+
response,
|
|
789
|
+
event_type=event_type,
|
|
790
|
+
stream_format=stream_format,
|
|
791
|
+
terminator=terminator,
|
|
792
|
+
strict=self.strict_response_validation,
|
|
793
|
+
)
|
|
794
|
+
|
|
795
|
+
return AsyncStreamManager(open_stream)
|
|
796
|
+
|
|
797
|
+
|
|
798
|
+
class APIResource:
|
|
799
|
+
"""Base for generated sync resources."""
|
|
800
|
+
|
|
801
|
+
def __init__(self, client: APIClient) -> None:
|
|
802
|
+
self._client = client
|
|
803
|
+
|
|
804
|
+
|
|
805
|
+
class AsyncAPIResource:
|
|
806
|
+
"""Base for generated async resources."""
|
|
807
|
+
|
|
808
|
+
def __init__(self, client: AsyncAPIClient) -> None:
|
|
809
|
+
self._client = client
|