devupai 1.0.0a1__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.
devupai/_client.py ADDED
@@ -0,0 +1,1154 @@
1
+ """The DEVUP AI API clients: options, request building, retries, the overall deadline and response reading.
2
+
3
+ ``DevupAI`` and ``AsyncDevupAI`` share one base class for validation, request building, error classification and
4
+ retry decisions. Only sending, reading, sleeping and closing differ between them.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ import math
11
+ import os
12
+ import random
13
+ import re
14
+ import ssl
15
+ import time
16
+ from collections.abc import AsyncIterator, Callable, Iterable, Iterator, Mapping, Sequence
17
+ from dataclasses import dataclass, field
18
+ from types import TracebackType
19
+ from typing import Any, Literal, Self, TypeAlias, TypedDict, TypeVar, cast
20
+
21
+ import anyio
22
+ import httpx
23
+
24
+ from devupai._errors import APIConnectionError, APITimeoutError, DevupAPIError, error_from_body
25
+ from devupai._response import APIResponse, make_api_response
26
+ from devupai._version import __version__
27
+ from devupai.resources import (
28
+ AsyncAudio,
29
+ AsyncBalance,
30
+ AsyncChat,
31
+ AsyncEmbeddings,
32
+ AsyncHealth,
33
+ AsyncImages,
34
+ AsyncMe,
35
+ AsyncModels,
36
+ AsyncNativeInference,
37
+ AsyncRerank,
38
+ AsyncResponses,
39
+ AsyncVideo,
40
+ Audio,
41
+ Balance,
42
+ Chat,
43
+ Embeddings,
44
+ Health,
45
+ Images,
46
+ Me,
47
+ Models,
48
+ NativeInference,
49
+ Rerank,
50
+ Responses,
51
+ Video,
52
+ )
53
+ from devupai.webhooks import Webhooks
54
+
55
+ __all__ = [
56
+ "BILLED_POST_RETRY",
57
+ "CONNECT_TIMEOUT",
58
+ "DEFAULT_BASE_URL",
59
+ "DEFAULT_MAX_RETRIES",
60
+ "DEFAULT_RETRY",
61
+ "DEFAULT_TIMEOUT",
62
+ "INITIAL_RETRY_DELAY",
63
+ "MAX_RETRY_DELAY",
64
+ "USER_AGENT",
65
+ "AsyncDevupAI",
66
+ "DebugEvent",
67
+ "DevupAI",
68
+ "MultipartParts",
69
+ "MultipartValue",
70
+ "RequestOptions",
71
+ "ResponseKind",
72
+ "RetryPolicy",
73
+ "async_request",
74
+ "connection_never_opened",
75
+ "effective_idle_timeout",
76
+ "sync_request",
77
+ ]
78
+
79
+ # Module-level hooks. They are always called through the module, so tests can replace them.
80
+ _sleep: Callable[[float], None] = time.sleep
81
+
82
+
83
+ async def _async_sleep(seconds: float) -> None:
84
+ """Waits ``seconds`` without blocking the event loop."""
85
+ await anyio.sleep(seconds)
86
+
87
+
88
+ _random: Callable[[], float] = random.random
89
+ _monotonic: Callable[[], float] = time.monotonic
90
+ _time: Callable[[], float] = time.time
91
+
92
+ DEFAULT_BASE_URL = "https://api.devupai.com/v1"
93
+ """Base URL of the API."""
94
+ DEFAULT_MAX_RETRIES = 2
95
+ """How many times a request is sent again after a transient error, by default."""
96
+ DEFAULT_TIMEOUT = 600.0
97
+ """Timeout of a request in seconds, by default."""
98
+ CONNECT_TIMEOUT = 10.0
99
+ """Longest time, in seconds, that opening a connection may take."""
100
+ INITIAL_RETRY_DELAY = 0.5
101
+ """Upper bound, in seconds, of the first random wait before a new attempt."""
102
+ MAX_RETRY_DELAY = 60.0
103
+ """Largest upper bound, in seconds, of a random wait before a new attempt."""
104
+ USER_AGENT = f"devupai-python/{__version__}"
105
+ """Value of the ``User-Agent`` header sent with every request."""
106
+
107
+ # Beyond this exponent the random wait is already capped by MAX_RETRY_DELAY; capping it avoids a float overflow.
108
+ _MAX_BACKOFF_EXPONENT = 32
109
+ # How deep connection_never_opened follows __cause__ / __context__.
110
+ _MAX_CAUSE_DEPTH = 5
111
+
112
+ _MAX_RETRIES_MESSAGE = "max_retries must be a non-negative integer."
113
+ _TIMEOUT_MESSAGE = "timeout must be a positive number of seconds."
114
+ _IDLE_TIMEOUT_MESSAGE = "stream_idle_timeout must be a non-negative number of seconds."
115
+ _KEY_TYPE_MESSAGE = "api_key must be a string."
116
+ _KEY_CHARS_MESSAGE = "api_key contains characters that are not allowed in an HTTP header."
117
+ _MISSING_KEY_MESSAGE = "DEVUP AI API key is missing. Pass api_key=... or set the DEVUP_API_KEY environment variable."
118
+ _HEADER_NAME_MESSAGE = "A header name contains characters that are not allowed in an HTTP header."
119
+ _CLOSED_MESSAGE = "The client is closed."
120
+
121
+ # Characters refused in a header value once leading and trailing spaces and tabs are removed: control
122
+ # characters (CR, LF and NUL included), DEL, and anything outside latin-1.
123
+ _FORBIDDEN_HEADER_CHARS = re.compile(r"[^\t\x20-\x7e\x80-\xff]")
124
+ # Removed from both ends of every header value before it is checked, as the Fetch Headers class does.
125
+ _HEADER_WHITESPACE = " \t"
126
+ _HEADER_PROTOCOL_MESSAGE = "The request could not be sent: a header value is not valid."
127
+ _BASE_URL_MESSAGE = "base_url must be an absolute http or https URL."
128
+ _URL_MESSAGE = "url must be an absolute http or https URL."
129
+ _BASE_URL_CREDENTIALS_MESSAGE = "base_url must not contain a user name or password."
130
+ _URL_CREDENTIALS_MESSAGE = "url must not contain a user name or password."
131
+ # An RFC 9110 token: the characters allowed in a header name.
132
+ _HEADER_TOKEN = re.compile(r"[!#$%&'*+\-.^_`|~0-9A-Za-z]+")
133
+ # Failures of a body read that come from the connection or from the bytes the API sent (a body that cannot be
134
+ # decoded, for example a corrupt gzip). Any other exception raised while a body is read is raised unchanged.
135
+ _BODY_READ_ERRORS = (httpx.TransportError, httpx.DecodingError)
136
+ _BODY_AND_MULTIPART_MESSAGE = "A request takes a JSON body or multipart parts, not both."
137
+ _MULTIPART_PART_MESSAGE = (
138
+ "A multipart part must be (name, text) or (name, (filename, content bytes, content type or None))."
139
+ )
140
+ _MULTIPART_TYPE_MESSAGE = "A multipart part has a content type that is not allowed in an HTTP header."
141
+ # A part's name and filename go in a quoted Content-Disposition parameter. As in the WHATWG multipart encoding that
142
+ # Node's FormData uses, only CR, LF and '"' are percent-encoded, so a value can never end the parameter or the header
143
+ # line; a backslash and every other character are sent as they are.
144
+ _FORM_PARAM_REPLACEMENTS: dict[str, str] = {"\r": "%0D", "\n": "%0A", '"': "%22"}
145
+ _FORM_PARAM_CHARS = re.compile("|".join(re.escape(char) for char in _FORM_PARAM_REPLACEMENTS))
146
+ _OCTET_STREAM = "application/octet-stream"
147
+
148
+ ResponseKind = Literal["json", "text", "raw", "stream"]
149
+ """How a successful body is read: ``"json"`` and ``"text"`` read it whole inside the deadline; ``"raw"`` and
150
+ ``"stream"`` return the ``httpx.Response`` with its body unread, and the deadline covers only the time until the
151
+ headers arrive."""
152
+
153
+ MultipartValue: TypeAlias = str | tuple[str, bytes, str | None]
154
+ """One multipart part value: a text, or ``(filename, content, content_type)``; a ``None`` content type is sent as
155
+ ``application/octet-stream``."""
156
+ MultipartParts: TypeAlias = Sequence[tuple[str, MultipartValue]]
157
+ """The parts of a multipart body as ``(name, value)`` pairs, sent in this order."""
158
+
159
+ # The kinds whose successful response is returned with its body unread.
160
+ _UNREAD_KINDS: frozenset[str] = frozenset({"raw", "stream"})
161
+ _ACCEPT: dict[str, str] = {"json": "application/json", "stream": "text/event-stream", "text": "*/*", "raw": "*/*"}
162
+
163
+
164
+ @dataclass(frozen=True)
165
+ class RetryPolicy:
166
+ """Which answers a request is sent again after.
167
+
168
+ ``statuses`` are the HTTP statuses after which the request is sent again. ``connection_errors`` is ``"all"`` for
169
+ every connection error, or ``"not_sent"`` for only an error showing that the connection was never opened, so
170
+ that nothing of the request reached the API.
171
+ """
172
+
173
+ statuses: frozenset[int]
174
+ connection_errors: Literal["all", "not_sent"]
175
+
176
+
177
+ DEFAULT_RETRY = RetryPolicy(frozenset({408, 429, 502, 503, 504}), "all")
178
+ """The retries of every request that is not a billed ``POST``: 408, 429, 502, 503, 504 and any connection error."""
179
+
180
+ BILLED_POST_RETRY = RetryPolicy(frozenset({429, 503}), "not_sent")
181
+ """The retries of a billed ``POST``: only 429 and 503, which the API answers before any work runs, and a connection
182
+ that was never opened. A 408, 502 or 504 answer, or a connection lost after it was opened, can come after the
183
+ request was processed and charged, so it is not retried."""
184
+
185
+
186
+ def connection_never_opened(error: BaseException) -> bool:
187
+ """True when ``error`` shows that the connection was never opened, so the request was not sent.
188
+
189
+ Only ``httpx.ConnectError``, ``httpx.ConnectTimeout`` and ``httpx.PoolTimeout`` count. A TLS handshake failure
190
+ (an ``ssl.SSLError`` on the error or its ``__cause__`` / ``__context__`` chain, up to depth 5) does not.
191
+ """
192
+ if not isinstance(error, (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout)):
193
+ return False
194
+ current: BaseException | None = error
195
+ depth = 0
196
+ while current is not None and depth <= _MAX_CAUSE_DEPTH:
197
+ if isinstance(current, ssl.SSLError):
198
+ return False
199
+ current = current.__cause__ if current.__cause__ is not None else current.__context__
200
+ depth += 1
201
+ return True
202
+
203
+
204
+ @dataclass(frozen=True)
205
+ class DebugEvent:
206
+ """An event passed to the ``on_debug`` client option.
207
+
208
+ ``type`` is ``"malformed_frame"`` when a stream frame that is not valid JSON was skipped, and ``"retry"`` when
209
+ the request is sent again. For ``"retry"``, ``detail`` is ``{"attempt", "status", "wait_ms"}`` (``status`` is
210
+ ``0`` when no response was received).
211
+ """
212
+
213
+ type: Literal["malformed_frame", "retry"]
214
+ detail: dict[str, object]
215
+
216
+
217
+ class RequestOptions(TypedDict, total=False):
218
+ """Options of one request. Values given here override the client options."""
219
+
220
+ timeout: float
221
+ """Timeout of the request in seconds."""
222
+ max_retries: int
223
+ """How many times the request is sent again after a transient error."""
224
+ extra_headers: Mapping[str, str]
225
+ """Headers to send with the request."""
226
+ stream_idle_timeout: float
227
+ """Ends a stream when no data arrives for this many seconds; ``0`` turns it off."""
228
+
229
+
230
+ # --- validation ----------------------------------------------------------------------------------------------------
231
+
232
+
233
+ def _check_max_retries(value: object) -> int:
234
+ if isinstance(value, bool) or not isinstance(value, int):
235
+ raise TypeError(_MAX_RETRIES_MESSAGE)
236
+ if value < 0:
237
+ raise ValueError(_MAX_RETRIES_MESSAGE)
238
+ return value
239
+
240
+
241
+ def _check_timeout(value: object) -> float:
242
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
243
+ raise TypeError(_TIMEOUT_MESSAGE)
244
+ number = float(value)
245
+ if not math.isfinite(number) or number <= 0:
246
+ raise ValueError(_TIMEOUT_MESSAGE)
247
+ return number
248
+
249
+
250
+ def _check_idle_timeout(value: object) -> float | None:
251
+ """``0`` turns the idle timeout off and is stored as ``None``."""
252
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
253
+ raise TypeError(_IDLE_TIMEOUT_MESSAGE)
254
+ number = float(value)
255
+ if not math.isfinite(number) or number < 0:
256
+ raise ValueError(_IDLE_TIMEOUT_MESSAGE)
257
+ return None if number == 0 else number
258
+
259
+
260
+ def _check_api_key(value: object) -> str:
261
+ """The error message never contains the key."""
262
+ if not isinstance(value, str):
263
+ raise TypeError(_KEY_TYPE_MESSAGE)
264
+ if _FORBIDDEN_HEADER_CHARS.search(value):
265
+ raise ValueError(_KEY_CHARS_MESSAGE)
266
+ return value
267
+
268
+
269
+ def _has_credentials(url: httpx.URL) -> bool:
270
+ """True when ``url`` carries a user name or a password (``user:password@host``)."""
271
+ return bool(url.userinfo)
272
+
273
+
274
+ def _check_base_url(value: object) -> str:
275
+ """``value`` or the default base URL, without a trailing ``/``. A user name or password in it is refused."""
276
+ if value is not None and not isinstance(value, str):
277
+ raise TypeError("base_url must be a string.")
278
+ base_url = (value or DEFAULT_BASE_URL).rstrip("/")
279
+ try:
280
+ parsed = httpx.URL(base_url)
281
+ except httpx.InvalidURL:
282
+ # Refused here, not at the first request, so repr() and base_url never show it: it can carry a password.
283
+ raise ValueError(_BASE_URL_MESSAGE) from None
284
+ if _has_credentials(parsed):
285
+ # The message never repeats the URL, so the credentials in it are not shown.
286
+ raise ValueError(_BASE_URL_CREDENTIALS_MESSAGE)
287
+ return base_url
288
+
289
+
290
+ _HttpClientT = TypeVar("_HttpClientT", httpx.Client, httpx.AsyncClient)
291
+
292
+
293
+ def _check_http_client(value: object, expected: type[_HttpClientT], message: str) -> _HttpClientT | None:
294
+ """``value`` when it is an instance of ``expected``, ``None`` when it is ``None``; anything else raises."""
295
+ if value is None:
296
+ return None
297
+ if not isinstance(value, expected):
298
+ raise TypeError(message)
299
+ return value
300
+
301
+
302
+ def _resolve_api_key(value: object) -> str:
303
+ """The key given, else ``DEVUP_API_KEY``, else (only when that variable is absent) ``DEVUPAI_API_KEY``."""
304
+ if value is not None:
305
+ return _check_api_key(value)
306
+ if "DEVUP_API_KEY" in os.environ:
307
+ found: str | None = os.environ["DEVUP_API_KEY"]
308
+ else:
309
+ found = os.environ.get("DEVUPAI_API_KEY")
310
+ if found is None or not found.strip():
311
+ raise ValueError(_MISSING_KEY_MESSAGE)
312
+ return _check_api_key(found)
313
+
314
+
315
+ # --- request building ----------------------------------------------------------------------------------------------
316
+
317
+ # Headers keyed by lower-cased name; each entry is the name as given and its value.
318
+ _HeaderMap = dict[str, tuple[str, str]]
319
+
320
+
321
+ def _set_header(headers: _HeaderMap, name: object, value: str) -> None:
322
+ if not isinstance(name, str):
323
+ raise ValueError(_HEADER_NAME_MESSAGE)
324
+ headers.pop(name.lower(), None)
325
+ headers[name.lower()] = (name, value)
326
+
327
+
328
+ def _merge_headers(headers: _HeaderMap, source: Mapping[str, object] | None) -> None:
329
+ """Later values win; names are compared without regard to case. Values that are not strings are skipped."""
330
+ if source is None:
331
+ return
332
+ items: Iterable[tuple[object, object]] = source.items()
333
+ for name, value in items:
334
+ if isinstance(value, str):
335
+ _set_header(headers, name, value)
336
+
337
+
338
+ def _encode_headers(headers: _HeaderMap) -> list[tuple[bytes, bytes]]:
339
+ """Checks every header name and value. The error names the header but never contains its value."""
340
+ encoded: list[tuple[bytes, bytes]] = []
341
+ for name, given_value in headers.values():
342
+ if not _HEADER_TOKEN.fullmatch(name):
343
+ raise ValueError(_HEADER_NAME_MESSAGE)
344
+ value_message = f'Header "{name}" has a value that is not allowed in an HTTP header.'
345
+ value = given_value.strip(_HEADER_WHITESPACE)
346
+ if _FORBIDDEN_HEADER_CHARS.search(value):
347
+ raise ValueError(value_message)
348
+ try:
349
+ raw_value = value.encode("latin-1")
350
+ except UnicodeEncodeError:
351
+ # The original error would repeat the value.
352
+ raise ValueError(value_message) from None
353
+ encoded.append((name.encode("ascii"), raw_value))
354
+ return encoded
355
+
356
+
357
+ def _describe(error: BaseException) -> str:
358
+ return str(error) or "unknown error"
359
+
360
+
361
+ def _decode(content: bytes) -> str:
362
+ return content.decode("utf-8-sig", errors="replace")
363
+
364
+
365
+ def _form_param(name: str, value: str) -> bytes:
366
+ """``name="value"`` for a Content-Disposition header, with the value escaped."""
367
+ escaped = _FORM_PARAM_CHARS.sub(lambda match: _FORM_PARAM_REPLACEMENTS[match.group(0)], value)
368
+ return f'{name}="{escaped}"'.encode()
369
+
370
+
371
+ def _check_part(part: object) -> tuple[str, str | tuple[str, bytes, str]]:
372
+ """One ``(name, value)`` part, checked, with a file part's content type filled in."""
373
+ if not isinstance(part, tuple) or len(part) != 2: # pyright: ignore[reportUnknownArgumentType]
374
+ raise TypeError(_MULTIPART_PART_MESSAGE)
375
+ name, value = cast("tuple[object, object]", part)
376
+ if not isinstance(name, str):
377
+ raise TypeError(_MULTIPART_PART_MESSAGE)
378
+ if isinstance(value, str):
379
+ return name, value
380
+ if not isinstance(value, tuple) or len(value) != 3: # pyright: ignore[reportUnknownArgumentType]
381
+ raise TypeError(_MULTIPART_PART_MESSAGE)
382
+ filename, content, content_type = cast("tuple[object, object, object]", value)
383
+ if not isinstance(filename, str) or not isinstance(content, bytes):
384
+ raise TypeError(_MULTIPART_PART_MESSAGE)
385
+ if content_type is None:
386
+ content_type = _OCTET_STREAM
387
+ if not isinstance(content_type, str):
388
+ raise TypeError(_MULTIPART_PART_MESSAGE)
389
+ content_type = content_type.strip(_HEADER_WHITESPACE)
390
+ if not content_type or _FORBIDDEN_HEADER_CHARS.search(content_type) or not content_type.isascii():
391
+ raise ValueError(_MULTIPART_TYPE_MESSAGE)
392
+ return name, (filename, content, content_type)
393
+
394
+
395
+ def _encode_multipart(parts: MultipartParts) -> tuple[bytes, str]:
396
+ """The ``multipart/form-data`` body of ``parts``, in their order, and its ``Content-Type`` value.
397
+
398
+ A text part has only a Content-Disposition header; a file part also has its filename and a Content-Type. The
399
+ body is built once, so every attempt of the request sends the same bytes.
400
+ """
401
+ rendered: list[tuple[bytes, bytes]] = []
402
+ for part in parts:
403
+ name, value = _check_part(part)
404
+ if isinstance(value, str):
405
+ head = b"Content-Disposition: form-data; " + _form_param("name", name)
406
+ rendered.append((head + b"\r\n\r\n", value.encode("utf-8")))
407
+ continue
408
+ filename, content, content_type = value
409
+ head = b"Content-Disposition: form-data; " + _form_param("name", name)
410
+ if filename:
411
+ head += b"; " + _form_param("filename", filename)
412
+ head += b"\r\nContent-Type: " + content_type.encode("ascii")
413
+ rendered.append((head + b"\r\n\r\n", content))
414
+ boundary = os.urandom(16).hex().encode("ascii")
415
+ # A boundary must not appear inside a part; with 128 random bits this loop almost never runs twice.
416
+ while any(boundary in head or boundary in data for head, data in rendered):
417
+ boundary = os.urandom(16).hex().encode("ascii")
418
+ chunks: list[bytes] = []
419
+ for head, data in rendered:
420
+ chunks.extend((b"--", boundary, b"\r\n", head, data, b"\r\n"))
421
+ chunks.extend((b"--", boundary, b"--\r\n"))
422
+ return b"".join(chunks), f"multipart/form-data; boundary={boundary.decode('ascii')}"
423
+
424
+
425
+ class _DeadlinePassed(Exception):
426
+ """Raised while a body is read once the deadline of the call has passed."""
427
+
428
+
429
+ class _DeadlineStream(httpx.SyncByteStream):
430
+ """A response body that stops with ``_DeadlinePassed`` when a chunk arrives after the deadline."""
431
+
432
+ def __init__(self, inner: httpx.SyncByteStream, deadline: float) -> None:
433
+ self._inner = inner
434
+ self._deadline = deadline
435
+
436
+ def __iter__(self) -> Iterator[bytes]:
437
+ for chunk in self._inner:
438
+ if _monotonic() >= self._deadline:
439
+ raise _DeadlinePassed()
440
+ yield chunk
441
+
442
+ def close(self) -> None:
443
+ self._inner.close()
444
+
445
+
446
+ class _AsyncDeadlineStream(httpx.AsyncByteStream):
447
+ """The async twin of :class:`_DeadlineStream`."""
448
+
449
+ def __init__(self, inner: httpx.AsyncByteStream, deadline: float) -> None:
450
+ self._inner = inner
451
+ self._deadline = deadline
452
+
453
+ async def __aiter__(self) -> AsyncIterator[bytes]:
454
+ async for chunk in self._inner:
455
+ if _monotonic() >= self._deadline:
456
+ raise _DeadlinePassed()
457
+ yield chunk
458
+
459
+ async def aclose(self) -> None:
460
+ await self._inner.aclose()
461
+
462
+
463
+ def _read_with_deadline(response: httpx.Response, deadline: float) -> bytes:
464
+ """Reads the whole body; a chunk that arrives after the deadline raises ``_DeadlinePassed``."""
465
+ if isinstance(response.stream, httpx.SyncByteStream):
466
+ response.stream = _DeadlineStream(response.stream, deadline)
467
+ return response.read()
468
+
469
+
470
+ async def _aread_with_deadline(response: httpx.Response, deadline: float) -> bytes:
471
+ """Reads the whole body. A chunk that arrives after the deadline raises ``_DeadlinePassed``, and a read that
472
+ stalls raises ``TimeoutError`` when the deadline passes."""
473
+ if isinstance(response.stream, httpx.AsyncByteStream):
474
+ response.stream = _AsyncDeadlineStream(response.stream, deadline)
475
+ with anyio.fail_after(max(deadline - _monotonic(), 0.0)):
476
+ return await response.aread()
477
+
478
+
479
+ @dataclass(frozen=True)
480
+ class _Prepared:
481
+ """A request built and validated once, sent by every attempt."""
482
+
483
+ method: str
484
+ url: httpx.URL
485
+ # Left out of the repr: the headers carry the API key, and the body may carry personal data.
486
+ headers: list[tuple[bytes, bytes]] = field(repr=False)
487
+ content: bytes | None = field(repr=False)
488
+ kind: ResponseKind
489
+ retry: RetryPolicy
490
+ timeout: float
491
+ max_retries: int
492
+ stream_idle_timeout: float | None
493
+ conditional: bool
494
+ deadline: float
495
+
496
+
497
+ class _BaseClient:
498
+ """Options, validation, request building, error classification and retry decisions shared by both clients."""
499
+
500
+ def __init__(
501
+ self,
502
+ *,
503
+ api_key: str | None,
504
+ base_url: str | None,
505
+ default_headers: Mapping[str, str] | None,
506
+ max_retries: int | None,
507
+ timeout: float | None,
508
+ stream_idle_timeout: float | None,
509
+ on_debug: Callable[[DebugEvent], None] | None,
510
+ ) -> None:
511
+ self._api_key = _resolve_api_key(api_key)
512
+ self._base_url = _check_base_url(base_url)
513
+ self._max_retries = DEFAULT_MAX_RETRIES if max_retries is None else _check_max_retries(max_retries)
514
+ self._timeout = DEFAULT_TIMEOUT if timeout is None else _check_timeout(timeout)
515
+ self._stream_idle_timeout = None if stream_idle_timeout is None else _check_idle_timeout(stream_idle_timeout)
516
+ self._default_headers: dict[str, object] = {} if default_headers is None else dict(default_headers)
517
+ self._on_debug = on_debug
518
+ self._closed = False
519
+
520
+ @property
521
+ def api_key(self) -> str:
522
+ """The API key sent as ``Authorization: Bearer <api_key>``."""
523
+ return self._api_key
524
+
525
+ @property
526
+ def base_url(self) -> str:
527
+ """Base URL of the API, without a trailing ``/``."""
528
+ return self._base_url
529
+
530
+ @property
531
+ def max_retries(self) -> int:
532
+ """How many times a request is sent again after a transient error."""
533
+ return self._max_retries
534
+
535
+ @property
536
+ def timeout(self) -> float:
537
+ """Timeout of a request in seconds."""
538
+ return self._timeout
539
+
540
+ @property
541
+ def stream_idle_timeout(self) -> float | None:
542
+ """Seconds without data after which a stream ends, or ``None`` when it is off."""
543
+ return self._stream_idle_timeout
544
+
545
+ def _effective_idle_timeout(self, options: RequestOptions | None) -> float | None:
546
+ """The idle timeout of one call: the per-call option when given (``0`` turns it off), else the client's."""
547
+ given = None if options is None else options.get("stream_idle_timeout")
548
+ return self._stream_idle_timeout if given is None else _check_idle_timeout(given)
549
+
550
+ def __repr__(self) -> str:
551
+ return f"{type(self).__name__}(base_url={self._base_url!r})"
552
+
553
+ # --- building ------------------------------------------------------------------------------------------------
554
+
555
+ def _prepare(
556
+ self,
557
+ method: Literal["GET", "POST"],
558
+ path: str | None,
559
+ *,
560
+ url: str | None,
561
+ query: Mapping[str, str | None] | None,
562
+ body: object,
563
+ auth: bool,
564
+ if_none_match: str | None,
565
+ retry: RetryPolicy,
566
+ kind: ResponseKind,
567
+ options: RequestOptions | None,
568
+ multipart: MultipartParts | None = None,
569
+ ) -> _Prepared:
570
+ """Steps 1 to 4 of a request: closed check, effective values, building and validation, deadline."""
571
+ if self._closed:
572
+ raise RuntimeError(_CLOSED_MESSAGE)
573
+ if body is not None and multipart is not None:
574
+ raise ValueError(_BODY_AND_MULTIPART_MESSAGE)
575
+ opts: Mapping[str, object] = {} if options is None else options
576
+ given_timeout = opts.get("timeout")
577
+ given_retries = opts.get("max_retries")
578
+ timeout = self._timeout if given_timeout is None else _check_timeout(given_timeout)
579
+ max_retries = self._max_retries if given_retries is None else _check_max_retries(given_retries)
580
+ idle = self._effective_idle_timeout(options)
581
+
582
+ target = self._build_url(path, url, query)
583
+ content: bytes | None = None
584
+ content_type: str | None = None
585
+ if multipart is not None:
586
+ content, content_type = _encode_multipart(multipart)
587
+ elif body is not None:
588
+ content = json.dumps(body, separators=(",", ":"), ensure_ascii=False, allow_nan=False).encode("utf-8")
589
+ content_type = "application/json"
590
+ extra = opts.get("extra_headers")
591
+ headers = self._build_headers(
592
+ kind=kind,
593
+ extra_headers=None if extra is None else _as_header_source(extra),
594
+ if_none_match=if_none_match,
595
+ auth=auth,
596
+ content_type=content_type,
597
+ )
598
+ encoded = _encode_headers(headers)
599
+ conditional = if_none_match is not None or (method == "GET" and "if-none-match" in headers)
600
+ return _Prepared(
601
+ method=method,
602
+ url=target,
603
+ headers=encoded,
604
+ content=content,
605
+ kind=kind,
606
+ retry=retry,
607
+ timeout=timeout,
608
+ max_retries=max_retries,
609
+ stream_idle_timeout=idle,
610
+ conditional=conditional,
611
+ deadline=_monotonic() + timeout,
612
+ )
613
+
614
+ def _build_url(self, path: str | None, url: str | None, query: Mapping[str, str | None] | None) -> httpx.URL:
615
+ if url is not None:
616
+ base, message, credentials_message = url, _URL_MESSAGE, _URL_CREDENTIALS_MESSAGE
617
+ elif path is not None:
618
+ base, message, credentials_message = (
619
+ f"{self._base_url}{path}",
620
+ _BASE_URL_MESSAGE,
621
+ _BASE_URL_CREDENTIALS_MESSAGE,
622
+ )
623
+ else:
624
+ raise TypeError("A request needs a path or a url.")
625
+ try:
626
+ target = httpx.URL(base)
627
+ except httpx.InvalidURL:
628
+ raise ValueError(message) from None
629
+ if _has_credentials(target):
630
+ # httpx would turn them into a Basic Authorization header. The message never repeats the URL.
631
+ raise ValueError(credentials_message)
632
+ if target.scheme not in ("http", "https") or not target.host:
633
+ raise ValueError(message)
634
+ for name, value in (query or {}).items():
635
+ if value is not None:
636
+ target = target.copy_set_param(name, value)
637
+ return target
638
+
639
+ def _build_headers(
640
+ self,
641
+ *,
642
+ kind: ResponseKind,
643
+ extra_headers: Mapping[str, object] | None,
644
+ if_none_match: str | None,
645
+ auth: bool,
646
+ content_type: str | None,
647
+ ) -> _HeaderMap:
648
+ headers: _HeaderMap = {}
649
+ _set_header(headers, "Accept", _ACCEPT[kind])
650
+ _set_header(headers, "User-Agent", USER_AGENT)
651
+ _merge_headers(headers, self._default_headers)
652
+ _merge_headers(headers, extra_headers)
653
+ if if_none_match is not None:
654
+ _set_header(headers, "If-None-Match", if_none_match)
655
+ headers.pop("authorization", None)
656
+ headers.pop("content-type", None)
657
+ if auth:
658
+ _set_header(headers, "Authorization", f"Bearer {self._api_key}")
659
+ if content_type is not None:
660
+ _set_header(headers, "Content-Type", content_type)
661
+ return headers
662
+
663
+ def _attempt_request(self, prepared: _Prepared) -> httpx.Request:
664
+ """The request of one attempt, with the time left as its timeout. Raises when no time is left."""
665
+ remaining = prepared.deadline - _monotonic()
666
+ if remaining <= 0:
667
+ raise self._timeout_error(prepared)
668
+ timeout = httpx.Timeout(remaining, connect=min(remaining, CONNECT_TIMEOUT))
669
+ return httpx.Request(
670
+ prepared.method,
671
+ prepared.url,
672
+ headers=prepared.headers,
673
+ content=prepared.content,
674
+ extensions={"timeout": timeout.as_dict()},
675
+ )
676
+
677
+ # --- classification --------------------------------------------------------------------------------------------
678
+
679
+ def _timeout_error(self, prepared: _Prepared) -> APITimeoutError:
680
+ return APITimeoutError(0, f"The request timed out after {prepared.timeout:g} seconds.")
681
+
682
+ def _past_deadline(self, prepared: _Prepared) -> bool:
683
+ return _monotonic() >= prepared.deadline
684
+
685
+ def _send_failure(
686
+ self, prepared: _Prepared, error: httpx.TransportError, attempt: int
687
+ ) -> tuple[APIConnectionError, float | None, Exception | None]:
688
+ """The error for a transport error raised while sending, the wait before a new attempt (``None``: raise),
689
+ and the exception to chain the error to (``None``: chain nothing).
690
+
691
+ Only ``httpx.TransportError`` comes here. Any other exception raised by ``send`` (an event hook of a caller
692
+ ``http_client``, an encoding error, a caller's own error) is raised unchanged and is never retried.
693
+ """
694
+ if isinstance(error, httpx.LocalProtocolError):
695
+ # The request was refused before it was sent. The original message can quote a header value (the
696
+ # API key included), so it is neither repeated nor chained. Sending again cannot succeed.
697
+ return APIConnectionError(0, _HEADER_PROTOCOL_MESSAGE), None, None
698
+ if self._past_deadline(prepared) or isinstance(error, (httpx.ReadTimeout, httpx.WriteTimeout)):
699
+ return self._timeout_error(prepared), None, error
700
+ failure = APIConnectionError(0, f"Network error: {_describe(error)}")
701
+ retryable = prepared.retry.connection_errors == "all" or connection_never_opened(error)
702
+ if not retryable or attempt >= prepared.max_retries:
703
+ return failure, None, error
704
+ wait = self._retry_wait(None, attempt, prepared.deadline)
705
+ if wait is not None:
706
+ self._debug_retry(attempt, 0, wait)
707
+ return failure, wait, error
708
+
709
+ def _status_wait(self, prepared: _Prepared, error: DevupAPIError, attempt: int) -> float | None:
710
+ """The wait before a new attempt after an error status, or ``None`` when the error is raised."""
711
+ if error.status not in prepared.retry.statuses or attempt >= prepared.max_retries:
712
+ return None
713
+ wait = self._retry_wait(error.retry_after_ms, attempt, prepared.deadline)
714
+ if wait is not None:
715
+ self._debug_retry(attempt, error.status, wait)
716
+ return wait
717
+
718
+ def _body_error(self, prepared: _Prepared, response: httpx.Response, error: Exception) -> APIConnectionError:
719
+ """The error for a 2xx body that could not be read (a transport error, or the deadline passed). It is never
720
+ retried."""
721
+ if self._past_deadline(prepared):
722
+ return self._timeout_error(prepared)
723
+ return APIConnectionError(0, f"Network error: {_describe(error)}", headers=response.headers)
724
+
725
+ def _is_not_modified(self, prepared: _Prepared, response: httpx.Response) -> bool:
726
+ return prepared.conditional and response.status_code == 304
727
+
728
+ def _open_stream(self, prepared: _Prepared, response: httpx.Response) -> None:
729
+ """After the headers of a ``"stream"`` response: from now on each read waits up to the idle timeout, or
730
+ without limit when it is off; the deadline of the call no longer applies.
731
+
732
+ The read timeout is the one the HTTP connection looks up when the body is read, so both clients apply it
733
+ there; on the async client the stream also bounds each read with ``anyio.move_on_after``, which covers a
734
+ transport that does not look the timeout up.
735
+ """
736
+ timeouts = response.request.extensions.get("timeout")
737
+ if isinstance(timeouts, dict):
738
+ cast("dict[str, float | None]", timeouts)["read"] = prepared.stream_idle_timeout
739
+
740
+ def _parse(self, prepared: _Prepared, response: httpx.Response, content: bytes) -> APIResponse[Any]:
741
+ text = _decode(content)
742
+ if prepared.kind == "text":
743
+ return make_api_response(text, response)
744
+ try:
745
+ data: Any = json.loads(text)
746
+ except (ValueError, RecursionError) as error:
747
+ raise DevupAPIError(
748
+ response.status_code, "The response body is not valid JSON.", headers=response.headers
749
+ ) from error
750
+ return make_api_response(data, response)
751
+
752
+ def _retry_wait(self, server_wait_ms: float | None, attempt: int, deadline: float) -> float | None:
753
+ """The wait in seconds before the next attempt, or ``None`` when it does not fit in the time left.
754
+
755
+ A wait the API asks for is taken as is (no cap but the deadline); otherwise the wait is random, up to
756
+ ``min(MAX_RETRY_DELAY, INITIAL_RETRY_DELAY * 2 ** attempt)``.
757
+ """
758
+ if server_wait_ms is not None:
759
+ wait = server_wait_ms / 1000
760
+ else:
761
+ exponent = min(attempt, _MAX_BACKOFF_EXPONENT)
762
+ wait = _random() * min(MAX_RETRY_DELAY, INITIAL_RETRY_DELAY * 2**exponent)
763
+ if wait > deadline - _monotonic():
764
+ return None
765
+ return wait
766
+
767
+ def _debug_retry(self, attempt: int, status: int, wait: float) -> None:
768
+ detail: dict[str, object] = {"attempt": attempt + 1, "status": status, "wait_ms": round(wait * 1000)}
769
+ self._debug(DebugEvent(type="retry", detail=detail))
770
+
771
+ def _debug(self, event: DebugEvent) -> None:
772
+ """Calls the ``on_debug`` hook. A hook that raises never changes the outcome of the request."""
773
+ hook = self._on_debug
774
+ if hook is None:
775
+ return
776
+ try:
777
+ hook(event)
778
+ except Exception:
779
+ # Deliberately not propagated: on_debug is a diagnostic hook, and its errors must not turn a
780
+ # successful request (or a retry) into a failure.
781
+ return
782
+
783
+
784
+ def _as_header_source(value: object) -> Mapping[str, object] | None:
785
+ """Per-call ``extra_headers`` as a mapping; anything else gives no headers."""
786
+ if isinstance(value, Mapping):
787
+ return cast("Mapping[str, object]", value)
788
+ return None
789
+
790
+
791
+ class DevupAI(_BaseClient):
792
+ """The synchronous DEVUP AI API client.
793
+
794
+ The key is ``api_key``, else the ``DEVUP_API_KEY`` environment variable, else (only when that variable is
795
+ absent) ``DEVUPAI_API_KEY``. ``timeout`` is in seconds and covers the whole call, retries included. A request is
796
+ sent again up to ``max_retries`` times after a 408, 429, 502, 503 or 504 answer or a connection error, except a
797
+ billed request: it is sent again only after a 429 or 503 answer, or when the connection was never opened.
798
+
799
+ Use it as a context manager, or call :meth:`close`, to release its connections. An ``http_client`` passed in
800
+ is used as is and never closed by the client.
801
+ """
802
+
803
+ def __init__(
804
+ self,
805
+ *,
806
+ api_key: str | None = None,
807
+ base_url: str | None = None,
808
+ default_headers: Mapping[str, str] | None = None,
809
+ max_retries: int | None = None,
810
+ timeout: float | None = None,
811
+ stream_idle_timeout: float | None = None,
812
+ http_client: httpx.Client | None = None,
813
+ on_debug: Callable[[DebugEvent], None] | None = None,
814
+ ) -> None:
815
+ """Creates the client. Raises ``TypeError`` or ``ValueError`` for an option that is not valid."""
816
+ super().__init__(
817
+ api_key=api_key,
818
+ base_url=base_url,
819
+ default_headers=default_headers,
820
+ max_retries=max_retries,
821
+ timeout=timeout,
822
+ stream_idle_timeout=stream_idle_timeout,
823
+ on_debug=on_debug,
824
+ )
825
+ given = _check_http_client(http_client, httpx.Client, "http_client must be an httpx.Client.")
826
+ self._owns_http = given is None
827
+ self._http = httpx.Client(follow_redirects=False, trust_env=True, timeout=None) if given is None else given
828
+
829
+ self.chat: Chat = Chat(self)
830
+ """Chat completions: ``chat.completions.create``."""
831
+ self.responses: Responses = Responses(self)
832
+ """The Responses API: ``responses.create``."""
833
+ self.models: Models = Models(self)
834
+ """The model catalog: ``models.list`` and ``models.retrieve``."""
835
+ self.images: Images = Images(self)
836
+ """Image generation and editing."""
837
+ self.embeddings: Embeddings = Embeddings(self)
838
+ """Embeddings: ``embeddings.create``."""
839
+ self.rerank: Rerank = Rerank(self)
840
+ """Reranking: ``rerank.create``."""
841
+ self.audio: Audio = Audio(self)
842
+ """Speech and transcriptions."""
843
+ self.video: Video = Video(self)
844
+ """Video generations and edits."""
845
+ self.inference: NativeInference = NativeInference(self)
846
+ """Native inference: ``inference.run``."""
847
+ self.balance: Balance = Balance(self)
848
+ """The account balance: ``balance.retrieve``."""
849
+ self.me: Me = Me(self)
850
+ """The account profile: ``me.retrieve``."""
851
+ self.health: Health = Health(self)
852
+ """The API health check: ``health.check``."""
853
+ self.webhooks: Webhooks = Webhooks()
854
+ """Webhook signature checks; they run locally and send nothing."""
855
+
856
+ def close(self) -> None:
857
+ """Closes the HTTP client this client created. Calling it again does nothing."""
858
+ if self._closed:
859
+ return
860
+ self._closed = True
861
+ if self._owns_http:
862
+ self._http.close()
863
+
864
+ def __enter__(self) -> Self:
865
+ return self
866
+
867
+ def __exit__(
868
+ self,
869
+ exc_type: type[BaseException] | None,
870
+ exc: BaseException | None,
871
+ traceback: TracebackType | None,
872
+ ) -> None:
873
+ self.close()
874
+
875
+ def _request(
876
+ self,
877
+ method: Literal["GET", "POST"],
878
+ path: str | None = None,
879
+ *,
880
+ url: str | None = None,
881
+ query: Mapping[str, str | None] | None = None,
882
+ body: object = None,
883
+ multipart: MultipartParts | None = None,
884
+ auth: bool = True,
885
+ if_none_match: str | None = None,
886
+ retry: RetryPolicy = DEFAULT_RETRY,
887
+ kind: ResponseKind = "json",
888
+ options: RequestOptions | None = None,
889
+ ) -> APIResponse[Any]:
890
+ """Sends a request with retries inside one deadline and returns the parsed response.
891
+
892
+ ``body`` is sent as JSON, ``multipart`` as ``multipart/form-data`` (in the given order); passing both raises
893
+ ``ValueError``. For ``kind="raw"`` and ``kind="stream"`` the data is the ``httpx.Response`` with its body
894
+ unread, and the caller closes it. Nothing is sent again once the headers of a 2xx answer have arrived.
895
+ """
896
+ prepared = self._prepare(
897
+ method,
898
+ path,
899
+ url=url,
900
+ query=query,
901
+ body=body,
902
+ multipart=multipart,
903
+ auth=auth,
904
+ if_none_match=if_none_match,
905
+ retry=retry,
906
+ kind=kind,
907
+ options=options,
908
+ )
909
+ attempt = 0
910
+ while True:
911
+ request = self._attempt_request(prepared)
912
+ try:
913
+ # auth=None: the auth of a caller http_client is never applied; the key goes in the headers.
914
+ response = self._http.send(request, stream=True, auth=None, follow_redirects=False)
915
+ except httpx.TransportError as error:
916
+ failure, wait, cause = self._send_failure(prepared, error, attempt)
917
+ if wait is None:
918
+ raise failure from cause
919
+ _sleep(wait)
920
+ attempt += 1
921
+ continue
922
+
923
+ if self._is_not_modified(prepared, response):
924
+ unread = prepared.kind in _UNREAD_KINDS
925
+ if not unread:
926
+ response.close()
927
+ return make_api_response(response if unread else None, response)
928
+
929
+ if not response.is_success:
930
+ try:
931
+ text = _decode(_read_with_deadline(response, prepared.deadline))
932
+ except _DeadlinePassed as error:
933
+ raise self._timeout_error(prepared) from error
934
+ except _BODY_READ_ERRORS as error:
935
+ if self._past_deadline(prepared):
936
+ raise self._timeout_error(prepared) from error
937
+ # The body could not be read: the message falls back to the HTTP status.
938
+ text = ""
939
+ finally:
940
+ response.close()
941
+ api_error = error_from_body(response.status_code, text, response.headers)
942
+ wait = self._status_wait(prepared, api_error, attempt)
943
+ if wait is None:
944
+ raise api_error
945
+ _sleep(wait)
946
+ attempt += 1
947
+ continue
948
+
949
+ if prepared.kind == "stream":
950
+ self._open_stream(prepared, response)
951
+ return make_api_response(response, response)
952
+ if prepared.kind == "raw":
953
+ return make_api_response(response, response)
954
+ try:
955
+ content = _read_with_deadline(response, prepared.deadline)
956
+ except (_DeadlinePassed, *_BODY_READ_ERRORS) as error:
957
+ raise self._body_error(prepared, response, error) from error
958
+ finally:
959
+ response.close()
960
+ return self._parse(prepared, response, content)
961
+
962
+
963
+ class AsyncDevupAI(_BaseClient):
964
+ """The asynchronous DEVUP AI API client, with the same options as :class:`DevupAI`.
965
+
966
+ Use it as an async context manager, or await :meth:`close`, to release its connections. An ``http_client``
967
+ passed in is used as is and never closed by the client.
968
+ """
969
+
970
+ def __init__(
971
+ self,
972
+ *,
973
+ api_key: str | None = None,
974
+ base_url: str | None = None,
975
+ default_headers: Mapping[str, str] | None = None,
976
+ max_retries: int | None = None,
977
+ timeout: float | None = None,
978
+ stream_idle_timeout: float | None = None,
979
+ http_client: httpx.AsyncClient | None = None,
980
+ on_debug: Callable[[DebugEvent], None] | None = None,
981
+ ) -> None:
982
+ """Creates the client. Raises ``TypeError`` or ``ValueError`` for an option that is not valid."""
983
+ super().__init__(
984
+ api_key=api_key,
985
+ base_url=base_url,
986
+ default_headers=default_headers,
987
+ max_retries=max_retries,
988
+ timeout=timeout,
989
+ stream_idle_timeout=stream_idle_timeout,
990
+ on_debug=on_debug,
991
+ )
992
+ given = _check_http_client(http_client, httpx.AsyncClient, "http_client must be an httpx.AsyncClient.")
993
+ self._owns_http = given is None
994
+ self._http = httpx.AsyncClient(follow_redirects=False, trust_env=True, timeout=None) if given is None else given
995
+
996
+ self.chat: AsyncChat = AsyncChat(self)
997
+ """Chat completions: ``chat.completions.create``."""
998
+ self.responses: AsyncResponses = AsyncResponses(self)
999
+ """The Responses API: ``responses.create``."""
1000
+ self.models: AsyncModels = AsyncModels(self)
1001
+ """The model catalog: ``models.list`` and ``models.retrieve``."""
1002
+ self.images: AsyncImages = AsyncImages(self)
1003
+ """Image generation and editing."""
1004
+ self.embeddings: AsyncEmbeddings = AsyncEmbeddings(self)
1005
+ """Embeddings: ``embeddings.create``."""
1006
+ self.rerank: AsyncRerank = AsyncRerank(self)
1007
+ """Reranking: ``rerank.create``."""
1008
+ self.audio: AsyncAudio = AsyncAudio(self)
1009
+ """Speech and transcriptions."""
1010
+ self.video: AsyncVideo = AsyncVideo(self)
1011
+ """Video generations and edits."""
1012
+ self.inference: AsyncNativeInference = AsyncNativeInference(self)
1013
+ """Native inference: ``inference.run``."""
1014
+ self.balance: AsyncBalance = AsyncBalance(self)
1015
+ """The account balance: ``balance.retrieve``."""
1016
+ self.me: AsyncMe = AsyncMe(self)
1017
+ """The account profile: ``me.retrieve``."""
1018
+ self.health: AsyncHealth = AsyncHealth(self)
1019
+ """The API health check: ``health.check``."""
1020
+ self.webhooks: Webhooks = Webhooks()
1021
+ """Webhook signature checks (synchronous on both clients); they run locally and send nothing."""
1022
+
1023
+ async def close(self) -> None:
1024
+ """Closes the HTTP client this client created. Calling it again does nothing."""
1025
+ if self._closed:
1026
+ return
1027
+ self._closed = True
1028
+ if self._owns_http:
1029
+ await self._http.aclose()
1030
+
1031
+ async def __aenter__(self) -> Self:
1032
+ return self
1033
+
1034
+ async def __aexit__(
1035
+ self,
1036
+ exc_type: type[BaseException] | None,
1037
+ exc: BaseException | None,
1038
+ traceback: TracebackType | None,
1039
+ ) -> None:
1040
+ await self.close()
1041
+
1042
+ async def _request(
1043
+ self,
1044
+ method: Literal["GET", "POST"],
1045
+ path: str | None = None,
1046
+ *,
1047
+ url: str | None = None,
1048
+ query: Mapping[str, str | None] | None = None,
1049
+ body: object = None,
1050
+ multipart: MultipartParts | None = None,
1051
+ auth: bool = True,
1052
+ if_none_match: str | None = None,
1053
+ retry: RetryPolicy = DEFAULT_RETRY,
1054
+ kind: ResponseKind = "json",
1055
+ options: RequestOptions | None = None,
1056
+ ) -> APIResponse[Any]:
1057
+ """Sends a request with retries inside one deadline and returns the parsed response, as
1058
+ :meth:`DevupAI._request` does.
1059
+
1060
+ For ``kind="stream"`` the async stream applies the idle timeout itself: each read is bounded with
1061
+ ``anyio.move_on_after`` (see :func:`effective_idle_timeout`).
1062
+ """
1063
+ prepared = self._prepare(
1064
+ method,
1065
+ path,
1066
+ url=url,
1067
+ query=query,
1068
+ body=body,
1069
+ multipart=multipart,
1070
+ auth=auth,
1071
+ if_none_match=if_none_match,
1072
+ retry=retry,
1073
+ kind=kind,
1074
+ options=options,
1075
+ )
1076
+ attempt = 0
1077
+ while True:
1078
+ request = self._attempt_request(prepared)
1079
+ try:
1080
+ # auth=None: the auth of a caller http_client is never applied; the key goes in the headers.
1081
+ response = await self._http.send(request, stream=True, auth=None, follow_redirects=False)
1082
+ except httpx.TransportError as error:
1083
+ failure, wait, cause = self._send_failure(prepared, error, attempt)
1084
+ if wait is None:
1085
+ raise failure from cause
1086
+ await _async_sleep(wait)
1087
+ attempt += 1
1088
+ continue
1089
+
1090
+ if self._is_not_modified(prepared, response):
1091
+ unread = prepared.kind in _UNREAD_KINDS
1092
+ if not unread:
1093
+ await response.aclose()
1094
+ return make_api_response(response if unread else None, response)
1095
+
1096
+ if not response.is_success:
1097
+ try:
1098
+ text = _decode(await _aread_with_deadline(response, prepared.deadline))
1099
+ except (TimeoutError, _DeadlinePassed) as error:
1100
+ raise self._timeout_error(prepared) from error
1101
+ except _BODY_READ_ERRORS as error:
1102
+ if self._past_deadline(prepared):
1103
+ raise self._timeout_error(prepared) from error
1104
+ # The body could not be read: the message falls back to the HTTP status.
1105
+ text = ""
1106
+ finally:
1107
+ await response.aclose()
1108
+ api_error = error_from_body(response.status_code, text, response.headers)
1109
+ wait = self._status_wait(prepared, api_error, attempt)
1110
+ if wait is None:
1111
+ raise api_error
1112
+ await _async_sleep(wait)
1113
+ attempt += 1
1114
+ continue
1115
+
1116
+ if prepared.kind == "stream":
1117
+ self._open_stream(prepared, response)
1118
+ return make_api_response(response, response)
1119
+ if prepared.kind == "raw":
1120
+ return make_api_response(response, response)
1121
+ try:
1122
+ content = await _aread_with_deadline(response, prepared.deadline)
1123
+ except TimeoutError as error:
1124
+ raise self._timeout_error(prepared) from error
1125
+ except (_DeadlinePassed, *_BODY_READ_ERRORS) as error:
1126
+ raise self._body_error(prepared, response, error) from error
1127
+ finally:
1128
+ await response.aclose()
1129
+ return self._parse(prepared, response, content)
1130
+
1131
+
1132
+ def sync_request(client: DevupAI, *args: Any, **kwargs: Any) -> APIResponse[Any]:
1133
+ """Sends a request through ``client`` with the parameters of ``DevupAI._request``; used by the resources.
1134
+
1135
+ The request method is looked up on the instance at each call, so a method set on the instance is the one used.
1136
+ """
1137
+ # This module defines the class; these two functions are the one place outside it that calls _request, so the
1138
+ # resources never touch a protected member.
1139
+ return client._request(*args, **kwargs) # pyright: ignore[reportPrivateUsage]
1140
+
1141
+
1142
+ async def async_request(client: AsyncDevupAI, *args: Any, **kwargs: Any) -> APIResponse[Any]:
1143
+ """The async twin of :func:`sync_request`, with the parameters of ``AsyncDevupAI._request``."""
1144
+ return await client._request(*args, **kwargs) # pyright: ignore[reportPrivateUsage]
1145
+
1146
+
1147
+ def effective_idle_timeout(client: DevupAI | AsyncDevupAI, options: RequestOptions | None) -> float | None:
1148
+ """The stream idle timeout of one call, in seconds, or ``None`` when it is off; used by the resources.
1149
+
1150
+ The ``stream_idle_timeout`` of ``options`` wins when it is given (``0`` turns it off); otherwise the client's
1151
+ ``stream_idle_timeout`` applies. A value that is not valid raises ``TypeError`` or ``ValueError``. It is the
1152
+ value ``_request(..., kind="stream")`` applies to the reads of the response.
1153
+ """
1154
+ return client._effective_idle_timeout(options) # pyright: ignore[reportPrivateUsage]