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.
@@ -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