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.
- verifyinboxes/__init__.py +102 -0
- verifyinboxes/_base.py +599 -0
- verifyinboxes/_client.py +364 -0
- verifyinboxes/_exceptions.py +164 -0
- verifyinboxes/_models.py +373 -0
- verifyinboxes/_pagination.py +50 -0
- verifyinboxes/_resources.py +929 -0
- verifyinboxes/_version.py +1 -0
- verifyinboxes/_webhooks.py +81 -0
- verifyinboxes/py.typed +0 -0
- verifyinboxes-0.1.0.dist-info/METADATA +488 -0
- verifyinboxes-0.1.0.dist-info/RECORD +14 -0
- verifyinboxes-0.1.0.dist-info/WHEEL +4 -0
- verifyinboxes-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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}).")
|