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/__init__.py +85 -0
- devupai/_client.py +1154 -0
- devupai/_errors.py +314 -0
- devupai/_response.py +225 -0
- devupai/_streaming.py +515 -0
- devupai/_version.py +3 -0
- devupai/py.typed +0 -0
- devupai/resources/__init__.py +137 -0
- devupai/resources/_base.py +207 -0
- devupai/resources/audio.py +663 -0
- devupai/resources/balance.py +103 -0
- devupai/resources/chat.py +428 -0
- devupai/resources/embeddings.py +141 -0
- devupai/resources/health.py +113 -0
- devupai/resources/images.py +503 -0
- devupai/resources/inference.py +347 -0
- devupai/resources/me.py +208 -0
- devupai/resources/models.py +405 -0
- devupai/resources/rerank.py +147 -0
- devupai/resources/responses.py +400 -0
- devupai/resources/shared.py +314 -0
- devupai/resources/video.py +600 -0
- devupai/types/__init__.py +264 -0
- devupai/types/_base.py +167 -0
- devupai/types/account.py +48 -0
- devupai/types/audio.py +89 -0
- devupai/types/chat.py +284 -0
- devupai/types/embeddings.py +51 -0
- devupai/types/images.py +238 -0
- devupai/types/models.py +107 -0
- devupai/types/rerank.py +41 -0
- devupai/types/responses.py +219 -0
- devupai/types/shared.py +79 -0
- devupai/types/video.py +218 -0
- devupai/types/webhooks.py +61 -0
- devupai/webhooks.py +278 -0
- devupai-1.0.0a1.dist-info/METADATA +221 -0
- devupai-1.0.0a1.dist-info/RECORD +40 -0
- devupai-1.0.0a1.dist-info/WHEEL +4 -0
- devupai-1.0.0a1.dist-info/licenses/LICENSE +21 -0
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]
|