-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy path_base.py
More file actions
186 lines (155 loc) · 5.7 KB
/
_base.py
File metadata and controls
186 lines (155 loc) · 5.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
"""Shared logic for sync and async clients."""
from __future__ import annotations
import random
from typing import Literal
import httpx
from .exceptions import (
ERROR_CODE_TO_EXCEPTION,
AuthenticationError,
RateLimitedError,
SharpAPIError,
TierRestrictedError,
ValidationError,
canonical_code,
)
from .models import APIResponse, RateLimitInfo, ResponseMeta
DEFAULT_BASE_URL = "https://api.sharpapi.io"
DEFAULT_TIMEOUT = 30.0
USER_AGENT = "sharpapi-python/0.2.5"
# Supported REST authentication methods. SSE always uses ``?api_key=`` query
# regardless of this setting because EventSource cannot set custom headers.
AuthMethod = Literal["x-api-key", "bearer"]
DEFAULT_AUTH_METHOD: AuthMethod = "x-api-key"
RETRY_STATUSES = frozenset({502, 503, 504})
RETRY_MAX_ATTEMPTS = 3
RETRY_BASE_DELAY = 0.5
RETRY_MAX_DELAY = 4.0
def should_retry(response: httpx.Response | None, exc: Exception | None) -> bool:
"""True for transient upstream failures worth retrying."""
if exc is not None:
return isinstance(exc, (httpx.ConnectError, httpx.ReadError, httpx.RemoteProtocolError))
return response is not None and response.status_code in RETRY_STATUSES
def retry_delay(attempt: int) -> float:
"""Exponential backoff with full jitter. attempt is 1-indexed."""
ceiling = min(RETRY_BASE_DELAY * (2 ** (attempt - 1)), RETRY_MAX_DELAY)
return random.uniform(0, ceiling)
def parse_response(raw: dict, model_class: type) -> APIResponse:
"""Parse raw API JSON into a typed APIResponse."""
data_raw = raw.get("data", [])
if isinstance(data_raw, list):
items = [model_class.model_validate(item) for item in data_raw]
else:
items = [model_class.model_validate(data_raw)]
meta = None
meta_raw = raw.get("meta")
if meta_raw:
meta = ResponseMeta.model_validate(meta_raw)
return APIResponse(
success=raw.get("success"),
data=items,
meta=meta,
timestamp=raw.get("timestamp"),
tier=raw.get("tier"),
)
def parse_rate_limit(response: httpx.Response) -> RateLimitInfo:
"""Extract rate limit info from response headers."""
headers = response.headers
return RateLimitInfo(
limit=_int_or_none(headers.get("x-ratelimit-limit")),
remaining=_int_or_none(headers.get("x-ratelimit-remaining")),
reset=_float_or_none(headers.get("x-ratelimit-reset")),
tier=headers.get("x-tier"),
)
def handle_errors(response: httpx.Response) -> None:
"""Raise typed exceptions for error responses."""
if response.is_success:
return
try:
body = response.json()
except Exception:
body = {}
error_obj = body.get("error", body)
if isinstance(error_obj, dict):
error_msg = error_obj.get("message", error_obj.get("error", f"HTTP {response.status_code}"))
code = error_obj.get("code", body.get("code", "unknown_error"))
else:
error_msg = str(error_obj) if error_obj else f"HTTP {response.status_code}"
code = body.get("code", "unknown_error")
status = response.status_code
# Resolve deprecated code aliases (bad_request, invalid_request → validation_error).
code = canonical_code(code)
# Prefer the canonical code→exception mapping for well-known codes; fall back
# to HTTP-status-based routing for responses that omit an error code.
exc_class = ERROR_CODE_TO_EXCEPTION.get(code or "")
if exc_class is TierRestrictedError:
raise TierRestrictedError(
error_msg,
code=code,
status=status,
required_tier=body.get("required_tier"),
)
if exc_class is RateLimitedError:
raise RateLimitedError(
error_msg,
code=code,
status=status,
retry_after=body.get("retry_after"),
)
if exc_class is not None and exc_class is not SharpAPIError:
raise exc_class(error_msg, code=code, status=status)
# No canonical code match — route by HTTP status.
if status == 401:
raise AuthenticationError(error_msg, code=code, status=status)
elif status == 403:
raise TierRestrictedError(
error_msg,
code=code,
status=status,
required_tier=body.get("required_tier"),
)
elif status == 429:
raise RateLimitedError(
error_msg,
code=code,
status=status,
retry_after=body.get("retry_after"),
)
elif status == 400:
raise ValidationError(error_msg, code=code, status=status)
else:
raise SharpAPIError(error_msg, code=code, status=status)
def make_headers(
api_key: str,
auth_method: AuthMethod = DEFAULT_AUTH_METHOD,
) -> dict[str, str]:
"""Build default request headers.
Args:
api_key: The SharpAPI key (e.g. ``sk_live_...``).
auth_method: Either ``"x-api-key"`` (default — sends an
``X-API-Key`` header) or ``"bearer"`` (sends
``Authorization: Bearer <key>``). Useful when proxies, IAM
layers, or SSO gateways strip non-standard custom headers.
"""
headers: dict[str, str] = {
"Content-Type": "application/json",
"User-Agent": USER_AGENT,
}
if auth_method == "bearer":
headers["Authorization"] = f"Bearer {api_key}"
else:
headers["X-API-Key"] = api_key
return headers
def _int_or_none(value: str | None) -> int | None:
if value is None:
return None
try:
return int(value)
except (ValueError, TypeError):
return None
def _float_or_none(value: str | None) -> float | None:
if value is None:
return None
try:
return float(value)
except (ValueError, TypeError):
return None