verifyinboxes 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,102 @@
1
+ """The official Python library for the VerifyInboxes API.
2
+
3
+ from verifyinboxes import VerifyInboxes
4
+
5
+ client = VerifyInboxes() # reads VERIFYINBOXES_API_KEY
6
+ result = client.verify("ann@example.com")
7
+ print(result.verdict, result.safe_to_send)
8
+ """
9
+ from ._client import AsyncVerifyInboxes, VerifyInboxes
10
+ from ._exceptions import (
11
+ APIConnectionError,
12
+ APIError,
13
+ APITimeoutError,
14
+ AuthenticationError,
15
+ ConflictError,
16
+ InsufficientCreditsError,
17
+ InvalidRequestError,
18
+ MissingAPIKeyError,
19
+ NotFoundError,
20
+ PermissionDeniedError,
21
+ RateLimitError,
22
+ ServerError,
23
+ VerifyInboxesError,
24
+ WaitTimeoutError,
25
+ )
26
+ from ._models import (
27
+ Account,
28
+ Domain,
29
+ FeedbackEvent,
30
+ FeedbackRejection,
31
+ FeedbackResult,
32
+ Integration,
33
+ IntegrationCreated,
34
+ Job,
35
+ JobCreated,
36
+ Model,
37
+ MxHost,
38
+ Notice,
39
+ NoticePage,
40
+ PendingCheck,
41
+ ResolveCreated,
42
+ ResolveSkipped,
43
+ Result,
44
+ ResultRow,
45
+ ResultsPage,
46
+ SuppressionList,
47
+ VerdictCounts,
48
+ Webhook,
49
+ WebhookCreated,
50
+ )
51
+ from ._version import __version__
52
+ from ._webhooks import DELIVERY_HEADER, SIGNATURE_HEADER, verify_signature
53
+
54
+ __all__ = [
55
+ "__version__",
56
+ # clients
57
+ "VerifyInboxes",
58
+ "AsyncVerifyInboxes",
59
+ # webhooks
60
+ "verify_signature",
61
+ "SIGNATURE_HEADER",
62
+ "DELIVERY_HEADER",
63
+ # errors
64
+ "VerifyInboxesError",
65
+ "MissingAPIKeyError",
66
+ "APIConnectionError",
67
+ "APITimeoutError",
68
+ "APIError",
69
+ "InvalidRequestError",
70
+ "AuthenticationError",
71
+ "InsufficientCreditsError",
72
+ "PermissionDeniedError",
73
+ "NotFoundError",
74
+ "ConflictError",
75
+ "RateLimitError",
76
+ "ServerError",
77
+ "WaitTimeoutError",
78
+ # models
79
+ "Model",
80
+ "Account",
81
+ "Result",
82
+ "ResultRow",
83
+ "ResultsPage",
84
+ "PendingCheck",
85
+ "Job",
86
+ "JobCreated",
87
+ "VerdictCounts",
88
+ "ResolveCreated",
89
+ "ResolveSkipped",
90
+ "Domain",
91
+ "MxHost",
92
+ "SuppressionList",
93
+ "Webhook",
94
+ "WebhookCreated",
95
+ "Notice",
96
+ "NoticePage",
97
+ "FeedbackEvent",
98
+ "FeedbackResult",
99
+ "FeedbackRejection",
100
+ "Integration",
101
+ "IntegrationCreated",
102
+ ]
verifyinboxes/_base.py ADDED
@@ -0,0 +1,599 @@
1
+ """What the sync and the async client share: configuration, headers, the retry decision, backoff, the error an answer
2
+ makes, uploads and downloads, and the checks of arguments. Nothing here sends a request."""
3
+ from __future__ import annotations
4
+
5
+ import contextvars
6
+ import email.utils
7
+ import io
8
+ import json
9
+ import logging
10
+ import os
11
+ import random
12
+ import re
13
+ import threading
14
+ import time
15
+ import uuid
16
+ from dataclasses import dataclass
17
+ from typing import IO, Any, AsyncIterator, Dict, Iterator, List, Mapping, Optional, Sequence, Tuple, Type, Union
18
+ from urllib.parse import quote
19
+
20
+ import httpx
21
+
22
+ from ._exceptions import (
23
+ APIConnectionError,
24
+ APIError,
25
+ APITimeoutError,
26
+ AuthenticationError,
27
+ ConflictError,
28
+ InsufficientCreditsError,
29
+ InvalidRequestError,
30
+ MissingAPIKeyError,
31
+ NotFoundError,
32
+ PermissionDeniedError,
33
+ RateLimitError,
34
+ ServerError,
35
+ VerifyInboxesError,
36
+ )
37
+ from ._version import __version__
38
+
39
+ log = logging.getLogger("verifyinboxes")
40
+
41
+ DEFAULT_BASE_URL = "https://api.verifyinboxes.com"
42
+ API_KEY_ENV = "VERIFYINBOXES_API_KEY"
43
+ BASE_URL_ENV = "VERIFYINBOXES_BASE_URL"
44
+ USER_AGENT = f"verifyinboxes-python/{__version__}"
45
+
46
+ DEFAULT_TIMEOUT = 60.0 # one attempt of one request
47
+ LONG_TIMEOUT = 600.0 # an upload or a download: the API's own limit for a whole request
48
+ DEFAULT_MAX_RETRIES = 2
49
+ MAX_RETRY_AFTER = 60.0 # a longer Retry-After is not waited for: the error is raised
50
+ INITIAL_RETRY_DELAY = 0.5
51
+ MAX_RETRY_DELAY = 8.0
52
+
53
+ CHECK_TIMEOUT = 60.0 # verify and checks.wait
54
+ MANY_TIMEOUT = 600.0 # verify_many
55
+ POLL_INTERVAL = 2.0 # a check's job is asked every 2 seconds
56
+ LIST_POLL_INTERVALS = (2.0, 4.0, 8.0, 16.0, 30.0) # a list's: then every 30 seconds
57
+ SINGLES_AT_MOST = 10 # verify_many: up to this many addresses are checked one by one, together
58
+ SINGLES_APART = 0.1 # ... started 100 ms apart
59
+ PAGE_SIZE = 500
60
+ ACTIVE = frozenset({"queued", "running"})
61
+
62
+ FileSource = Union[str, "os.PathLike[str]", bytes, bytearray, memoryview, IO[bytes]]
63
+ Destination = Union[str, "os.PathLike[str]", IO[bytes]]
64
+
65
+ CALLER_INTERRUPTED: "contextvars.ContextVar[Optional[threading.Event]]" = contextvars.ContextVar(
66
+ "verifyinboxes_caller_interrupted", default=None)
67
+ """Around a request that makes a job (a check, `verify_many`'s list): the event its caller sets when it is
68
+ interrupted (Ctrl-C, a cancelled task) and waits for the request's answer, to know the job. Once it is set, an attempt
69
+ that fails is not sent again: the caller waits for the attempt on its way (or the rest of a pause before a retry), and
70
+ no longer."""
71
+
72
+
73
+ def caller_interrupted() -> bool:
74
+ """The caller of the request being sent was interrupted: an attempt that fails is not sent again."""
75
+ interrupted = CALLER_INTERRUPTED.get()
76
+ return interrupted is not None and interrupted.is_set()
77
+
78
+
79
+ # --- configuration ----------------------------------------------------------------------------------------------------
80
+
81
+
82
+ def resolve_api_key(api_key: Optional[str]) -> str:
83
+ value = api_key if api_key is not None else os.environ.get(API_KEY_ENV)
84
+ if value is not None and not isinstance(value, str):
85
+ raise TypeError("api_key must be a string")
86
+ value = (value or "").strip()
87
+ if not value:
88
+ raise MissingAPIKeyError(
89
+ f"No API key. Pass api_key=... or set the {API_KEY_ENV} environment variable. An organisation admin "
90
+ "makes keys in the VerifyInboxes app under Developers -> API keys."
91
+ )
92
+ if not re.fullmatch(r"[!-~]+", value):
93
+ # A key and a token are visible ASCII: anything else (a space, a control or zero-width character, a letter
94
+ # with an accent) is half of a copy and paste, and would fail on the first request instead.
95
+ raise ValueError("The API key holds a space, a control character or a character that is not ASCII: "
96
+ "copy it again, whole.")
97
+ return value
98
+
99
+
100
+ def resolve_base_url(base_url: Optional[str]) -> str:
101
+ value = base_url or os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL
102
+ if not isinstance(value, str):
103
+ raise TypeError("base_url must be a string")
104
+ value = value.strip()
105
+ if value.endswith("/"):
106
+ value = value[:-1]
107
+ if not re.match(r"^https?://[^/\s]+", value, re.IGNORECASE):
108
+ raise ValueError("base_url must be an http:// or https:// address")
109
+ return value
110
+
111
+
112
+ def check_timeout(name: str, value: Optional[float], *, allow_none: bool = True) -> Optional[float]:
113
+ if value is None and allow_none:
114
+ return None
115
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or value < 0:
116
+ raise ValueError(f"{name} must be a number of seconds, 0 or more")
117
+ return float(value)
118
+
119
+
120
+ def check_retries(value: int) -> int:
121
+ if isinstance(value, bool) or not isinstance(value, int) or value < 0:
122
+ raise ValueError("max_retries must be a whole number, 0 or more")
123
+ return value
124
+
125
+
126
+ def resolve_user_agent(product: Optional[str]) -> str:
127
+ """The User-Agent: the caller's product token, when given, in front of the library's own."""
128
+ if product is None or product == "":
129
+ return USER_AGENT
130
+ if not isinstance(product, str) or not re.fullmatch(r"[!-~]+", product):
131
+ raise ValueError("user_agent must be visible ASCII with no space, such as my-app/1.2")
132
+ return f"{product} {USER_AGENT}"
133
+
134
+
135
+ # --- requests ---------------------------------------------------------------------------------------------------------
136
+
137
+
138
+ def path_segment(value: str, what: str = "id") -> str:
139
+ """A value as one segment of a path: an id with a `/` or a `?` in it never reaches another address."""
140
+ if not isinstance(value, str) or not value:
141
+ raise ValueError(f"{what} must be a non-empty string")
142
+ return quote(value, safe="")
143
+
144
+
145
+ def new_idempotency_key() -> str:
146
+ return str(uuid.uuid4())
147
+
148
+
149
+ def idempotency_key(value: Optional[str]) -> str:
150
+ """The caller's own key, checked, or a new one."""
151
+ if value is None:
152
+ return new_idempotency_key()
153
+ if not isinstance(value, str) or not re.fullmatch(r"[!-~]{1,255}", value):
154
+ raise ValueError("idempotency_key must be 1 to 255 visible ASCII characters")
155
+ return value
156
+
157
+
158
+ # How a request may be sent again after a failed attempt.
159
+ ALWAYS = "always"
160
+ """GET and DELETE, and the POSTs the API answers again from the same `Idempotency-Key`."""
161
+ UNSENT = "unsent"
162
+ """A POST the API never replays (its answer holds a secret shown once): again only when it surely did not arrive (the
163
+ connection was never made) or was refused before it ran (429)."""
164
+
165
+
166
+ @dataclass
167
+ class Call:
168
+ """One request, as the resources describe it to the client's transport."""
169
+
170
+ method: str
171
+ path: str
172
+ params: Optional[Dict[str, str]] = None
173
+ json: Any = None
174
+ upload: Optional["Upload"] = None
175
+ idempotency_key: Optional[str] = None
176
+ retry: str = ALWAYS
177
+ long: bool = False
178
+ """An upload or a download: the longer timeout."""
179
+ gone_is_done: bool = False
180
+ """A DELETE whose earlier attempt got no answer: a 404 on a retry means the first one did it."""
181
+ accept: str = "application/json"
182
+
183
+
184
+ @dataclass
185
+ class Answer:
186
+ status: int
187
+ request_id: Optional[str]
188
+ data: Any
189
+
190
+
191
+ def results_params(page_size: int, cursor: Optional[str], only_safe_to_send: bool, verdicts: Optional[Sequence[str]],
192
+ partial: bool) -> Dict[str, str]:
193
+ if isinstance(page_size, bool) or not isinstance(page_size, int) or not 1 <= page_size <= 1000:
194
+ raise ValueError("page_size must be a whole number from 1 to 1000")
195
+ params = {"limit": str(page_size)}
196
+ if cursor is not None:
197
+ params["cursor"] = cursor
198
+ params.update(filter_params(only_safe_to_send, verdicts, partial))
199
+ return params
200
+
201
+
202
+ def filter_params(only_safe_to_send: bool, verdicts: Optional[Sequence[str]], partial: bool) -> Dict[str, str]:
203
+ params: Dict[str, str] = {}
204
+ if only_safe_to_send and verdicts:
205
+ raise ValueError("give only_safe_to_send or verdicts, not both")
206
+ if only_safe_to_send:
207
+ params["only"] = "safe_to_send"
208
+ if verdicts:
209
+ if isinstance(verdicts, str):
210
+ verdicts = [verdicts]
211
+ params["verdicts"] = ",".join(verdicts)
212
+ if partial:
213
+ params["partial"] = "1"
214
+ return params
215
+
216
+
217
+ def check_emails(emails: Sequence[str]) -> List[str]:
218
+ if isinstance(emails, (str, bytes)) or not isinstance(emails, Sequence):
219
+ raise TypeError("emails must be a list of addresses")
220
+ out = list(emails)
221
+ if not out:
222
+ raise ValueError("emails is empty: give one address or more")
223
+ for index, value in enumerate(out):
224
+ if not isinstance(value, str) or not value.strip():
225
+ raise ValueError(f"emails[{index}] is not an address")
226
+ return out
227
+
228
+
229
+ def check_email(email: str) -> str:
230
+ if not isinstance(email, str) or not email.strip():
231
+ raise ValueError("email must be an address")
232
+ return email
233
+
234
+
235
+ # --- answers ----------------------------------------------------------------------------------------------------------
236
+
237
+ _BY_STATUS: Dict[int, Type[APIError]] = {
238
+ 400: InvalidRequestError, 413: InvalidRequestError, 414: InvalidRequestError, 415: InvalidRequestError,
239
+ 422: InvalidRequestError, 401: AuthenticationError, 402: InsufficientCreditsError, 403: PermissionDeniedError,
240
+ 404: NotFoundError, 410: NotFoundError, 409: ConflictError, 429: RateLimitError,
241
+ }
242
+
243
+
244
+ def parse_retry_after(value: Optional[str]) -> Optional[float]:
245
+ if not value:
246
+ return None
247
+ try:
248
+ return max(0.0, float(value))
249
+ except ValueError:
250
+ pass
251
+ try:
252
+ when = email.utils.parsedate_to_datetime(value)
253
+ except (TypeError, ValueError, IndexError):
254
+ return None
255
+ return max(0.0, when.timestamp() - time.time())
256
+
257
+
258
+ def error_from_answer(status: int, headers: httpx.Headers, content: bytes) -> APIError:
259
+ """The typed error of an answer of 4xx or 5xx. The API's errors are `{"error": {"code", "message"}}`; a body that
260
+ is not one (a proxy's HTML page) keeps its status, with no code."""
261
+ body: Any
262
+ try:
263
+ body = json.loads(content.decode("utf-8")) if content else None
264
+ except ValueError:
265
+ body = content.decode("utf-8", "replace")
266
+ code = message = None
267
+ error = body.get("error") if isinstance(body, Mapping) else None
268
+ if isinstance(error, Mapping):
269
+ if isinstance(error.get("code"), str):
270
+ code = error["code"]
271
+ if isinstance(error.get("message"), str):
272
+ message = error["message"]
273
+ cls = _BY_STATUS.get(status) or (ServerError if status >= 500 else APIError)
274
+ return cls(
275
+ message or f"The API answered {status}",
276
+ status=status,
277
+ code=code,
278
+ request_id=headers.get("x-request-id"),
279
+ retry_after=parse_retry_after(headers.get("retry-after")),
280
+ body=body,
281
+ )
282
+
283
+
284
+ def parse_body(status: int, headers: httpx.Headers, content: bytes) -> Any:
285
+ if not content:
286
+ return None
287
+ try:
288
+ return json.loads(content.decode("utf-8"))
289
+ except ValueError:
290
+ request_id = headers.get("x-request-id")
291
+ raise VerifyInboxesError(
292
+ f"The API answered {status} with something that is not JSON"
293
+ + (f" (request id {request_id})" if request_id else "")
294
+ ) from None
295
+
296
+
297
+ def connection_error(exc: httpx.TransportError) -> Tuple[APIConnectionError, bool]:
298
+ """The error of a request that got no answer, and whether it surely never reached the API."""
299
+ never_sent = isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout))
300
+ if isinstance(exc, httpx.TimeoutException):
301
+ return APITimeoutError(), never_sent
302
+ detail = str(exc).strip()
303
+ text = "Could not reach the VerifyInboxes API" + (f": {detail}" if detail else ".")
304
+ return APIConnectionError(text), never_sent
305
+
306
+
307
+ # --- uploads ----------------------------------------------------------------------------------------------------------
308
+
309
+ _CHUNK = 64 * 1024
310
+
311
+
312
+ def _form_quote(value: str) -> str:
313
+ return value.replace("\\", "\\\\").replace('"', "%22").replace("\r", "%0D").replace("\n", "%0A")
314
+
315
+
316
+ class Upload:
317
+ """A CSV sent as `multipart/form-data`: the field `email_column`, then the file. It is built again for every
318
+ attempt: a path is opened again, a seekable stream rewound to where it was; a stream that can be read only once
319
+ is sent once."""
320
+
321
+ def __init__(self, source: FileSource, *, email_column: str, filename: Optional[str]) -> None:
322
+ if not isinstance(email_column, str) or not email_column:
323
+ raise ValueError("email_column must be a column's name")
324
+ self._path: Optional[str] = None
325
+ self._data: Optional[bytes] = None
326
+ self._stream: Optional[IO[bytes]] = None
327
+ self._start: Optional[int] = None
328
+ if isinstance(source, (str, os.PathLike)):
329
+ self._path = os.fspath(source)
330
+ if not os.path.isfile(self._path):
331
+ raise FileNotFoundError(f"no such file: {self._path}")
332
+ name = filename or os.path.basename(self._path) or "list.csv"
333
+ elif isinstance(source, (bytes, bytearray, memoryview)):
334
+ self._data = bytes(source)
335
+ name = filename or "list.csv"
336
+ elif hasattr(source, "read"):
337
+ if isinstance(source, io.TextIOBase) or "b" not in str(getattr(source, "mode", "b")):
338
+ raise TypeError("file is open in text mode: open it in binary mode: open(path, 'rb')")
339
+ self._stream = source
340
+ self._start = _position(source)
341
+ name = filename or "list.csv"
342
+ else:
343
+ raise TypeError("file must be a path, bytes, or a file opened in binary mode")
344
+ self.boundary = uuid.uuid4().hex
345
+ self._head = (
346
+ f'--{self.boundary}\r\nContent-Disposition: form-data; name="email_column"\r\n\r\n'
347
+ f"{email_column}\r\n"
348
+ f'--{self.boundary}\r\nContent-Disposition: form-data; name="file"; filename="{_form_quote(name)}"\r\n'
349
+ "Content-Type: text/csv\r\n\r\n"
350
+ ).encode("utf-8")
351
+ self._tail = f"\r\n--{self.boundary}--\r\n".encode("ascii")
352
+ self.started = False
353
+ """Whether a one-way stream has begun to be read: it cannot be sent again."""
354
+
355
+ @property
356
+ def resendable(self) -> bool:
357
+ return self._stream is None or self._start is not None or not self.started
358
+
359
+ def _headers(self, size: Optional[int]) -> Dict[str, str]:
360
+ headers = {"Content-Type": f"multipart/form-data; boundary={self.boundary}"}
361
+ if size is not None:
362
+ headers["Content-Length"] = str(len(self._head) + size + len(self._tail))
363
+ return headers
364
+
365
+ def _open(self) -> Tuple[Optional[IO[bytes]], Optional[int]]:
366
+ """The file for this attempt and its size (`None`: unknown, sent chunked)."""
367
+ if self._path is not None:
368
+ handle: IO[bytes] = open(self._path, "rb")
369
+ return handle, os.fstat(handle.fileno()).st_size
370
+ if self._stream is not None:
371
+ if self._start is None:
372
+ return self._stream, None
373
+ end = self._stream.seek(0, io.SEEK_END)
374
+ self._stream.seek(self._start)
375
+ return self._stream, max(0, end - self._start)
376
+ return None, None
377
+
378
+ def sync_body(self) -> Tuple[Dict[str, str], Union[bytes, Iterator[bytes]], "_Closer"]:
379
+ if self._data is not None:
380
+ return self._headers(len(self._data)), self._head + self._data + self._tail, _Closer(None, False)
381
+ handle, size = self._open()
382
+ assert handle is not None
383
+ closer = _Closer(handle, self._path is not None)
384
+
385
+ def chunks() -> Iterator[bytes]:
386
+ self.started = True
387
+ yield self._head
388
+ while True:
389
+ chunk = handle.read(_CHUNK)
390
+ if not chunk:
391
+ break
392
+ yield chunk
393
+ yield self._tail
394
+
395
+ return self._headers(size), chunks(), closer
396
+
397
+ def async_body(self) -> Tuple[Dict[str, str], Union[bytes, AsyncIterator[bytes]], "_Closer"]:
398
+ if self._data is not None:
399
+ return self._headers(len(self._data)), self._head + self._data + self._tail, _Closer(None, False)
400
+ handle, size = self._open()
401
+ assert handle is not None
402
+ closer = _Closer(handle, self._path is not None)
403
+
404
+ async def chunks() -> AsyncIterator[bytes]:
405
+ self.started = True
406
+ yield self._head
407
+ while True:
408
+ chunk = handle.read(_CHUNK)
409
+ if not chunk:
410
+ break
411
+ yield chunk
412
+ yield self._tail
413
+
414
+ return self._headers(size), chunks(), closer
415
+
416
+
417
+ class _Closer:
418
+ def __init__(self, handle: Optional[IO[bytes]], owned: bool) -> None:
419
+ self._handle = handle
420
+ self._owned = owned
421
+
422
+ def close(self) -> None:
423
+ if self._handle is not None and self._owned:
424
+ self._handle.close()
425
+
426
+
427
+ def _position(stream: Any) -> Optional[int]:
428
+ """Where a seekable stream is (to rewind it to on a retry); `None` for a stream read only once."""
429
+ try:
430
+ if callable(getattr(stream, "seekable", None)) and not stream.seekable():
431
+ return None
432
+ position = stream.tell()
433
+ return position if isinstance(position, int) else None
434
+ except (OSError, ValueError, AttributeError):
435
+ return None
436
+
437
+
438
+ # --- downloads --------------------------------------------------------------------------------------------------------
439
+
440
+
441
+ class Sink:
442
+ """Where a download goes. To a path: a part file beside it, renamed over it once the whole body arrived, removed on
443
+ any failure, so the file there was is untouched. To a stream: written as it comes."""
444
+
445
+ def __init__(self, destination: Destination) -> None:
446
+ self._path: Optional[str] = None
447
+ self._stream: Optional[IO[bytes]] = None
448
+ if isinstance(destination, (str, os.PathLike)):
449
+ self._path = os.path.abspath(os.fspath(destination))
450
+ elif hasattr(destination, "write"):
451
+ self._stream = destination
452
+ else:
453
+ raise TypeError("destination must be a path or a file opened in binary mode for writing")
454
+ self._part: Optional[str] = None
455
+ self._file: Optional[IO[bytes]] = None
456
+ self.written = 0
457
+ """Bytes written by this attempt."""
458
+
459
+ @property
460
+ def resendable(self) -> bool:
461
+ """Whether a failed attempt can be made again from the start: always to a path, to a stream before its first
462
+ byte."""
463
+ return self._path is not None or self.written == 0
464
+
465
+ def begin(self) -> None:
466
+ self.written = 0
467
+ if self._path is not None:
468
+ directory, name = os.path.split(self._path)
469
+ for _ in range(10):
470
+ part = os.path.join(directory, f"{name}.part-{uuid.uuid4().hex[:12]}")
471
+ try:
472
+ self._file = open(part, "xb")
473
+ except FileExistsError:
474
+ continue
475
+ self._part = part
476
+ return
477
+ raise VerifyInboxesError(f"could not make a part file beside {self._path}")
478
+
479
+ def write(self, chunk: bytes) -> None:
480
+ if not chunk:
481
+ return
482
+ target = self._file if self._path is not None else self._stream
483
+ assert target is not None
484
+ target.write(chunk)
485
+ self.written += len(chunk)
486
+
487
+ def commit(self) -> int:
488
+ if self._path is not None and self._file is not None and self._part is not None:
489
+ self._file.flush()
490
+ os.fsync(self._file.fileno())
491
+ self._file.close()
492
+ self._file = None
493
+ os.replace(self._part, self._path)
494
+ self._part = None
495
+ return self.written
496
+
497
+ def abort(self) -> None:
498
+ if self._file is not None:
499
+ self._file.close()
500
+ self._file = None
501
+ if self._part is not None:
502
+ try:
503
+ os.unlink(self._part)
504
+ except FileNotFoundError:
505
+ pass
506
+ self._part = None
507
+
508
+
509
+ # --- the client's shared part -----------------------------------------------------------------------------------------
510
+
511
+
512
+ class BaseClient:
513
+ """Configuration and policy. It sends nothing: `VerifyInboxes` and `AsyncVerifyInboxes` do."""
514
+
515
+ def __init__(self, *, api_key: Optional[str], base_url: Optional[str], timeout: Optional[float],
516
+ max_retries: int, user_agent: Optional[str] = None) -> None:
517
+ self.api_key = resolve_api_key(api_key)
518
+ self.base_url = resolve_base_url(base_url)
519
+ self.timeout = check_timeout("timeout", timeout)
520
+ self.max_retries = check_retries(max_retries)
521
+ self._user_agent = resolve_user_agent(user_agent)
522
+
523
+ def __repr__(self) -> str:
524
+ return f"{type(self).__name__}(base_url={self.base_url!r}, api_key='{self.api_key[:6]}...')"
525
+
526
+ def _headers(self, call: Call, extra: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
527
+ headers = {"Authorization": f"Bearer {self.api_key}", "Accept": call.accept, "User-Agent": self._user_agent}
528
+ if call.idempotency_key is not None:
529
+ headers["Idempotency-Key"] = call.idempotency_key
530
+ if extra:
531
+ headers.update(extra)
532
+ return headers
533
+
534
+ def _url(self, path: str) -> str:
535
+ return f"{self.base_url}{path}"
536
+
537
+ def _timeout(self, call: Call) -> Optional[float]:
538
+ if self.timeout is None:
539
+ return None
540
+ return max(self.timeout, LONG_TIMEOUT) if call.long else self.timeout
541
+
542
+ def _backoff(self, attempt: int) -> float:
543
+ """The n-th retry's wait (n from 0): uniform between half of `min(8, 0.5 × 2^n)` seconds and all of it."""
544
+ ceiling = min(MAX_RETRY_DELAY, INITIAL_RETRY_DELAY * float(2 ** attempt))
545
+ return random.uniform(ceiling / 2, ceiling)
546
+
547
+ def _retry_delay(self, call: Call, error: VerifyInboxesError, attempt: int, *, never_sent: bool = False) -> Optional[float]:
548
+ """Seconds to wait before sending `call` again, or `None` to raise `error`."""
549
+ if attempt >= self.max_retries or caller_interrupted():
550
+ return None
551
+ if call.upload is not None and not call.upload.resendable:
552
+ return None
553
+ if isinstance(error, APIConnectionError):
554
+ if call.retry == UNSENT and not never_sent:
555
+ return None
556
+ return self._backoff(attempt)
557
+ if not isinstance(error, APIError):
558
+ return None
559
+ in_progress = error.status == 409 and error.code == "idempotency_in_progress"
560
+ if not (error.status == 429 or error.status >= 500 or in_progress):
561
+ return None
562
+ if call.retry == UNSENT and error.status != 429:
563
+ return None
564
+ if error.retry_after is not None:
565
+ return error.retry_after if error.retry_after <= MAX_RETRY_AFTER else None
566
+ return self._backoff(attempt)
567
+
568
+
569
+ def log_answer(call: Call, attempt: int, status: int, request_id: Optional[str]) -> None:
570
+ log.debug("%s %s: %s, request id %s (attempt %d)", call.method, call.path, status, request_id, attempt + 1)
571
+
572
+
573
+ def log_no_answer(call: Call, attempt: int, exc: BaseException) -> None:
574
+ log.debug("%s %s: no answer, %s (attempt %d)", call.method, call.path, type(exc).__name__, attempt + 1)
575
+
576
+
577
+ def note_interrupted(error: BaseException, job_ids: Sequence[str]) -> None:
578
+ """A call that made jobs was interrupted (Ctrl-C, a cancelled task, a timeout around it): the jobs carry on and
579
+ hold credits, so name them on the exception (where it takes attributes, and as a note on Python 3.11+) and in a
580
+ warning, before it is raised again."""
581
+ if not job_ids or isinstance(error, VerifyInboxesError):
582
+ return
583
+ ids = list(job_ids)
584
+ text = (f"interrupted; still running: {', '.join(ids)} "
585
+ "(wait for them again with client.checks.wait or client.lists.wait)")
586
+ try:
587
+ setattr(error, "job_ids", ids)
588
+ except (AttributeError, TypeError):
589
+ pass
590
+ add_note = getattr(error, "add_note", None)
591
+ if callable(add_note):
592
+ add_note(f"verifyinboxes: {text}")
593
+ log.warning("%s", text)
594
+
595
+
596
+ def wait_timeout_message(what: str, job_id: str, status: str, timeout: Optional[float], resume: str) -> str:
597
+ after = f" after {timeout:g} seconds" if timeout is not None else ""
598
+ return (f"The {what} {job_id} was still {status}{after}. It carries on, and its credits are held: "
599
+ f"wait for it again with {resume}({job_id!r}).")