xcrop 1.0.1__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.
- xcrop/__init__.py +41 -0
- xcrop/_http.py +334 -0
- xcrop/_version.py +3 -0
- xcrop/client.py +125 -0
- xcrop/errors.py +93 -0
- xcrop/py.typed +0 -0
- xcrop/resources/__init__.py +29 -0
- xcrop/resources/account.py +92 -0
- xcrop/resources/communities.py +167 -0
- xcrop/resources/lists.py +135 -0
- xcrop/resources/search.py +285 -0
- xcrop/resources/stream.py +30 -0
- xcrop/resources/trending.py +29 -0
- xcrop/resources/tweets.py +292 -0
- xcrop/resources/users.py +293 -0
- xcrop/types.py +219 -0
- xcrop-1.0.1.dist-info/METADATA +345 -0
- xcrop-1.0.1.dist-info/RECORD +19 -0
- xcrop-1.0.1.dist-info/WHEEL +4 -0
xcrop/__init__.py
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
"""XCROP — Official Python SDK for the XCROP API (X/Twitter data intelligence platform).
|
|
2
|
+
|
|
3
|
+
Usage::
|
|
4
|
+
|
|
5
|
+
from xcrop import XCropClient
|
|
6
|
+
|
|
7
|
+
client = XCropClient(api_key="xc_live_...")
|
|
8
|
+
user = client.users.get("elonmusk")
|
|
9
|
+
print(user["data"]["username"])
|
|
10
|
+
|
|
11
|
+
Async::
|
|
12
|
+
|
|
13
|
+
from xcrop import AsyncXCropClient
|
|
14
|
+
|
|
15
|
+
async with AsyncXCropClient(api_key="xc_live_...") as client:
|
|
16
|
+
user = await client.users.get("elonmusk")
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from .client import AsyncXCropClient, XCropClient
|
|
20
|
+
from .errors import (
|
|
21
|
+
AuthError,
|
|
22
|
+
NotFoundError,
|
|
23
|
+
RateLimitError,
|
|
24
|
+
ServerError,
|
|
25
|
+
StreamError,
|
|
26
|
+
XCropError,
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
from ._version import __version__
|
|
30
|
+
|
|
31
|
+
__all__ = [
|
|
32
|
+
"XCropClient",
|
|
33
|
+
"AsyncXCropClient",
|
|
34
|
+
"XCropError",
|
|
35
|
+
"AuthError",
|
|
36
|
+
"RateLimitError",
|
|
37
|
+
"NotFoundError",
|
|
38
|
+
"ServerError",
|
|
39
|
+
"StreamError",
|
|
40
|
+
"__version__",
|
|
41
|
+
]
|
xcrop/_http.py
ADDED
|
@@ -0,0 +1,334 @@
|
|
|
1
|
+
"""Low-level HTTP transport with retry, rate-limit back-off, and SSE streaming."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import time
|
|
7
|
+
import asyncio
|
|
8
|
+
from typing import (
|
|
9
|
+
Any,
|
|
10
|
+
AsyncIterator,
|
|
11
|
+
Dict,
|
|
12
|
+
Iterator,
|
|
13
|
+
Optional,
|
|
14
|
+
Union,
|
|
15
|
+
)
|
|
16
|
+
|
|
17
|
+
import httpx
|
|
18
|
+
|
|
19
|
+
from ._version import __version__
|
|
20
|
+
from .errors import (
|
|
21
|
+
AuthError,
|
|
22
|
+
NotFoundError,
|
|
23
|
+
RateLimitError,
|
|
24
|
+
ServerError,
|
|
25
|
+
StreamError,
|
|
26
|
+
XCropError,
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
DEFAULT_BASE_URL = "https://xcrop.io/api/v2"
|
|
30
|
+
DEFAULT_TIMEOUT = 30.0
|
|
31
|
+
MAX_RETRIES = 3
|
|
32
|
+
RETRY_BACKOFF_BASE = 1.0 # seconds
|
|
33
|
+
RETRY_BACKOFF_MAX = 30.0
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
# ---------------------------------------------------------------------------
|
|
37
|
+
# Helpers
|
|
38
|
+
# ---------------------------------------------------------------------------
|
|
39
|
+
|
|
40
|
+
def _raise_for_status(response: httpx.Response) -> None:
|
|
41
|
+
"""Raise a typed exception based on the HTTP status code."""
|
|
42
|
+
if response.is_success:
|
|
43
|
+
return
|
|
44
|
+
|
|
45
|
+
status = response.status_code
|
|
46
|
+
try:
|
|
47
|
+
body = response.json()
|
|
48
|
+
message = body.get("error", response.text)
|
|
49
|
+
code = body.get("code", "")
|
|
50
|
+
except Exception:
|
|
51
|
+
message = response.text or f"HTTP {status}"
|
|
52
|
+
code = ""
|
|
53
|
+
|
|
54
|
+
if status == 401 or status == 403:
|
|
55
|
+
raise AuthError(message, status_code=status, error_code=code, response=response)
|
|
56
|
+
if status == 404:
|
|
57
|
+
raise NotFoundError(message, error_code=code, response=response)
|
|
58
|
+
if status == 429:
|
|
59
|
+
retry_after = _parse_retry_after(response)
|
|
60
|
+
raise RateLimitError(
|
|
61
|
+
message, retry_after=retry_after, error_code=code, response=response,
|
|
62
|
+
)
|
|
63
|
+
if 500 <= status < 600:
|
|
64
|
+
raise ServerError(message, status_code=status, error_code=code, response=response)
|
|
65
|
+
|
|
66
|
+
raise XCropError(message, status_code=status, error_code=code, response=response)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _parse_retry_after(response: httpx.Response) -> Optional[float]:
|
|
70
|
+
val = response.headers.get("retry-after")
|
|
71
|
+
if val is None:
|
|
72
|
+
return None
|
|
73
|
+
try:
|
|
74
|
+
return float(val)
|
|
75
|
+
except ValueError:
|
|
76
|
+
return None
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _backoff(attempt: int) -> float:
|
|
80
|
+
return min(RETRY_BACKOFF_BASE * (2 ** attempt), RETRY_BACKOFF_MAX)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _should_retry(status: int) -> bool:
|
|
84
|
+
return status == 429 or status >= 500
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def _parse_sse_data(event_str: str) -> Optional[str]:
|
|
88
|
+
"""Parse an SSE event block, concatenating multiple data: lines per spec."""
|
|
89
|
+
data_lines = []
|
|
90
|
+
for line in event_str.split("\n"):
|
|
91
|
+
if line.startswith("data: "):
|
|
92
|
+
data_lines.append(line[6:])
|
|
93
|
+
elif line.startswith("data:"):
|
|
94
|
+
data_lines.append(line[5:])
|
|
95
|
+
if not data_lines:
|
|
96
|
+
return None
|
|
97
|
+
joined = "\n".join(data_lines)
|
|
98
|
+
if joined == "[DONE]":
|
|
99
|
+
return None
|
|
100
|
+
return joined
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
# ---------------------------------------------------------------------------
|
|
104
|
+
# Sync transport
|
|
105
|
+
# ---------------------------------------------------------------------------
|
|
106
|
+
|
|
107
|
+
class HttpTransport:
|
|
108
|
+
"""Synchronous HTTP transport with automatic retries."""
|
|
109
|
+
|
|
110
|
+
def __init__(
|
|
111
|
+
self,
|
|
112
|
+
api_key: str,
|
|
113
|
+
base_url: str = DEFAULT_BASE_URL,
|
|
114
|
+
timeout: float = DEFAULT_TIMEOUT,
|
|
115
|
+
max_retries: int = MAX_RETRIES,
|
|
116
|
+
http_client: Optional[httpx.Client] = None,
|
|
117
|
+
) -> None:
|
|
118
|
+
self.api_key = api_key
|
|
119
|
+
self.base_url = base_url.rstrip("/")
|
|
120
|
+
self.max_retries = max_retries
|
|
121
|
+
self._default_hdrs = self._default_headers()
|
|
122
|
+
self._owns_client = http_client is None
|
|
123
|
+
self._client = http_client or httpx.Client(timeout=timeout)
|
|
124
|
+
|
|
125
|
+
def _default_headers(self) -> Dict[str, str]:
|
|
126
|
+
return {
|
|
127
|
+
"Authorization": f"Bearer {self.api_key}",
|
|
128
|
+
"User-Agent": f"xcrop-python/{__version__}",
|
|
129
|
+
"Accept": "application/json",
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
# -- core request --
|
|
133
|
+
|
|
134
|
+
def request(
|
|
135
|
+
self,
|
|
136
|
+
method: str,
|
|
137
|
+
path: str,
|
|
138
|
+
*,
|
|
139
|
+
params: Optional[Dict[str, Any]] = None,
|
|
140
|
+
json_body: Optional[Dict[str, Any]] = None,
|
|
141
|
+
) -> Dict[str, Any]:
|
|
142
|
+
url = f"{self.base_url}{path}"
|
|
143
|
+
last_exc: Optional[Exception] = None
|
|
144
|
+
|
|
145
|
+
for attempt in range(self.max_retries + 1):
|
|
146
|
+
try:
|
|
147
|
+
resp = self._client.request(
|
|
148
|
+
method, url, params=params, json=json_body,
|
|
149
|
+
headers=self._default_hdrs,
|
|
150
|
+
)
|
|
151
|
+
except httpx.TransportError as exc:
|
|
152
|
+
last_exc = exc
|
|
153
|
+
if attempt < self.max_retries:
|
|
154
|
+
time.sleep(_backoff(attempt))
|
|
155
|
+
continue
|
|
156
|
+
raise XCropError(f"Transport error: {exc}") from exc
|
|
157
|
+
|
|
158
|
+
if resp.is_success:
|
|
159
|
+
return resp.json() # type: ignore[no-any-return]
|
|
160
|
+
|
|
161
|
+
if _should_retry(resp.status_code) and attempt < self.max_retries:
|
|
162
|
+
wait = _backoff(attempt)
|
|
163
|
+
if resp.status_code == 429:
|
|
164
|
+
ra = _parse_retry_after(resp)
|
|
165
|
+
if ra is not None:
|
|
166
|
+
wait = ra
|
|
167
|
+
time.sleep(wait)
|
|
168
|
+
last_exc = None
|
|
169
|
+
continue
|
|
170
|
+
|
|
171
|
+
_raise_for_status(resp)
|
|
172
|
+
|
|
173
|
+
# Should not reach here, but just in case
|
|
174
|
+
if last_exc:
|
|
175
|
+
raise XCropError(f"Max retries exceeded: {last_exc}") from last_exc
|
|
176
|
+
raise XCropError("Max retries exceeded")
|
|
177
|
+
|
|
178
|
+
def get(self, path: str, **params: Any) -> Dict[str, Any]:
|
|
179
|
+
# Filter None values
|
|
180
|
+
cleaned = {k: v for k, v in params.items() if v is not None}
|
|
181
|
+
return self.request("GET", path, params=cleaned)
|
|
182
|
+
|
|
183
|
+
def post(self, path: str, body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
|
184
|
+
return self.request("POST", path, json_body=body)
|
|
185
|
+
|
|
186
|
+
def delete(self, path: str, body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
|
187
|
+
return self.request("DELETE", path, json_body=body)
|
|
188
|
+
|
|
189
|
+
# -- SSE streaming --
|
|
190
|
+
|
|
191
|
+
def stream_sse(
|
|
192
|
+
self,
|
|
193
|
+
method: str,
|
|
194
|
+
path: str,
|
|
195
|
+
*,
|
|
196
|
+
params: Optional[Dict[str, Any]] = None,
|
|
197
|
+
json_body: Optional[Dict[str, Any]] = None,
|
|
198
|
+
) -> Iterator[Dict[str, Any]]:
|
|
199
|
+
url = f"{self.base_url}{path}"
|
|
200
|
+
with self._client.stream(
|
|
201
|
+
method, url, params=params, json=json_body, headers=self._default_hdrs,
|
|
202
|
+
) as resp:
|
|
203
|
+
if not resp.is_success:
|
|
204
|
+
resp.read()
|
|
205
|
+
_raise_for_status(resp)
|
|
206
|
+
buffer = ""
|
|
207
|
+
for chunk in resp.iter_text():
|
|
208
|
+
buffer += chunk
|
|
209
|
+
while "\n\n" in buffer:
|
|
210
|
+
event_str, buffer = buffer.split("\n\n", 1)
|
|
211
|
+
data = _parse_sse_data(event_str)
|
|
212
|
+
if data is not None:
|
|
213
|
+
try:
|
|
214
|
+
yield json.loads(data)
|
|
215
|
+
except json.JSONDecodeError:
|
|
216
|
+
continue
|
|
217
|
+
|
|
218
|
+
def close(self) -> None:
|
|
219
|
+
if self._owns_client:
|
|
220
|
+
self._client.close()
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
# ---------------------------------------------------------------------------
|
|
224
|
+
# Async transport
|
|
225
|
+
# ---------------------------------------------------------------------------
|
|
226
|
+
|
|
227
|
+
class AsyncHttpTransport:
|
|
228
|
+
"""Asynchronous HTTP transport with automatic retries."""
|
|
229
|
+
|
|
230
|
+
def __init__(
|
|
231
|
+
self,
|
|
232
|
+
api_key: str,
|
|
233
|
+
base_url: str = DEFAULT_BASE_URL,
|
|
234
|
+
timeout: float = DEFAULT_TIMEOUT,
|
|
235
|
+
max_retries: int = MAX_RETRIES,
|
|
236
|
+
http_client: Optional[httpx.AsyncClient] = None,
|
|
237
|
+
) -> None:
|
|
238
|
+
self.api_key = api_key
|
|
239
|
+
self.base_url = base_url.rstrip("/")
|
|
240
|
+
self.max_retries = max_retries
|
|
241
|
+
self._default_hdrs = self._default_headers()
|
|
242
|
+
self._owns_client = http_client is None
|
|
243
|
+
self._client = http_client or httpx.AsyncClient(timeout=timeout)
|
|
244
|
+
|
|
245
|
+
def _default_headers(self) -> Dict[str, str]:
|
|
246
|
+
return {
|
|
247
|
+
"Authorization": f"Bearer {self.api_key}",
|
|
248
|
+
"User-Agent": f"xcrop-python/{__version__}",
|
|
249
|
+
"Accept": "application/json",
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
async def request(
|
|
253
|
+
self,
|
|
254
|
+
method: str,
|
|
255
|
+
path: str,
|
|
256
|
+
*,
|
|
257
|
+
params: Optional[Dict[str, Any]] = None,
|
|
258
|
+
json_body: Optional[Dict[str, Any]] = None,
|
|
259
|
+
) -> Dict[str, Any]:
|
|
260
|
+
url = f"{self.base_url}{path}"
|
|
261
|
+
last_exc: Optional[Exception] = None
|
|
262
|
+
|
|
263
|
+
for attempt in range(self.max_retries + 1):
|
|
264
|
+
try:
|
|
265
|
+
resp = await self._client.request(
|
|
266
|
+
method, url, params=params, json=json_body,
|
|
267
|
+
headers=self._default_hdrs,
|
|
268
|
+
)
|
|
269
|
+
except httpx.TransportError as exc:
|
|
270
|
+
last_exc = exc
|
|
271
|
+
if attempt < self.max_retries:
|
|
272
|
+
await asyncio.sleep(_backoff(attempt))
|
|
273
|
+
continue
|
|
274
|
+
raise XCropError(f"Transport error: {exc}") from exc
|
|
275
|
+
|
|
276
|
+
if resp.is_success:
|
|
277
|
+
return resp.json() # type: ignore[no-any-return]
|
|
278
|
+
|
|
279
|
+
if _should_retry(resp.status_code) and attempt < self.max_retries:
|
|
280
|
+
wait = _backoff(attempt)
|
|
281
|
+
if resp.status_code == 429:
|
|
282
|
+
ra = _parse_retry_after(resp)
|
|
283
|
+
if ra is not None:
|
|
284
|
+
wait = ra
|
|
285
|
+
await asyncio.sleep(wait)
|
|
286
|
+
last_exc = None
|
|
287
|
+
continue
|
|
288
|
+
|
|
289
|
+
_raise_for_status(resp)
|
|
290
|
+
|
|
291
|
+
if last_exc:
|
|
292
|
+
raise XCropError(f"Max retries exceeded: {last_exc}") from last_exc
|
|
293
|
+
raise XCropError("Max retries exceeded")
|
|
294
|
+
|
|
295
|
+
async def get(self, path: str, **params: Any) -> Dict[str, Any]:
|
|
296
|
+
cleaned = {k: v for k, v in params.items() if v is not None}
|
|
297
|
+
return await self.request("GET", path, params=cleaned)
|
|
298
|
+
|
|
299
|
+
async def post(self, path: str, body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
|
300
|
+
return await self.request("POST", path, json_body=body)
|
|
301
|
+
|
|
302
|
+
async def delete(self, path: str, body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
|
303
|
+
return await self.request("DELETE", path, json_body=body)
|
|
304
|
+
|
|
305
|
+
async def stream_sse(
|
|
306
|
+
self,
|
|
307
|
+
method: str,
|
|
308
|
+
path: str,
|
|
309
|
+
*,
|
|
310
|
+
params: Optional[Dict[str, Any]] = None,
|
|
311
|
+
json_body: Optional[Dict[str, Any]] = None,
|
|
312
|
+
) -> AsyncIterator[Dict[str, Any]]:
|
|
313
|
+
url = f"{self.base_url}{path}"
|
|
314
|
+
async with self._client.stream(
|
|
315
|
+
method, url, params=params, json=json_body, headers=self._default_hdrs,
|
|
316
|
+
) as resp:
|
|
317
|
+
if not resp.is_success:
|
|
318
|
+
await resp.aread()
|
|
319
|
+
_raise_for_status(resp)
|
|
320
|
+
buffer = ""
|
|
321
|
+
async for chunk in resp.aiter_text():
|
|
322
|
+
buffer += chunk
|
|
323
|
+
while "\n\n" in buffer:
|
|
324
|
+
event_str, buffer = buffer.split("\n\n", 1)
|
|
325
|
+
data = _parse_sse_data(event_str)
|
|
326
|
+
if data is not None:
|
|
327
|
+
try:
|
|
328
|
+
yield json.loads(data)
|
|
329
|
+
except json.JSONDecodeError:
|
|
330
|
+
continue
|
|
331
|
+
|
|
332
|
+
async def close(self) -> None:
|
|
333
|
+
if self._owns_client:
|
|
334
|
+
await self._client.aclose()
|
xcrop/_version.py
ADDED
xcrop/client.py
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
"""XCROP API clients — sync and async."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Optional
|
|
6
|
+
|
|
7
|
+
import httpx
|
|
8
|
+
|
|
9
|
+
from ._http import AsyncHttpTransport, HttpTransport, DEFAULT_BASE_URL, DEFAULT_TIMEOUT, MAX_RETRIES
|
|
10
|
+
from .resources import (
|
|
11
|
+
AccountResource,
|
|
12
|
+
AsyncAccountResource,
|
|
13
|
+
AsyncCommunitiesResource,
|
|
14
|
+
AsyncListsResource,
|
|
15
|
+
AsyncSearchResource,
|
|
16
|
+
AsyncStreamResource,
|
|
17
|
+
AsyncTrendingResource,
|
|
18
|
+
AsyncTweetsResource,
|
|
19
|
+
AsyncUsersResource,
|
|
20
|
+
CommunitiesResource,
|
|
21
|
+
ListsResource,
|
|
22
|
+
SearchResource,
|
|
23
|
+
StreamResource,
|
|
24
|
+
TrendingResource,
|
|
25
|
+
TweetsResource,
|
|
26
|
+
UsersResource,
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class XCropClient:
|
|
31
|
+
"""Synchronous XCROP API client.
|
|
32
|
+
|
|
33
|
+
Usage::
|
|
34
|
+
|
|
35
|
+
client = XCropClient(api_key="xc_live_...")
|
|
36
|
+
user = client.users.get("elonmusk")
|
|
37
|
+
|
|
38
|
+
# Auto-paginate
|
|
39
|
+
for tweet in client.users.tweets.paginate("elonmusk", count=200):
|
|
40
|
+
print(tweet["text"])
|
|
41
|
+
|
|
42
|
+
client.close()
|
|
43
|
+
"""
|
|
44
|
+
|
|
45
|
+
def __init__(
|
|
46
|
+
self,
|
|
47
|
+
api_key: str,
|
|
48
|
+
*,
|
|
49
|
+
base_url: str = DEFAULT_BASE_URL,
|
|
50
|
+
timeout: float = DEFAULT_TIMEOUT,
|
|
51
|
+
max_retries: int = MAX_RETRIES,
|
|
52
|
+
http_client: Optional[httpx.Client] = None,
|
|
53
|
+
) -> None:
|
|
54
|
+
self._transport = HttpTransport(
|
|
55
|
+
api_key=api_key,
|
|
56
|
+
base_url=base_url,
|
|
57
|
+
timeout=timeout,
|
|
58
|
+
max_retries=max_retries,
|
|
59
|
+
http_client=http_client,
|
|
60
|
+
)
|
|
61
|
+
self.users = UsersResource(self._transport)
|
|
62
|
+
self.tweets = TweetsResource(self._transport)
|
|
63
|
+
self.search = SearchResource(self._transport)
|
|
64
|
+
self.lists = ListsResource(self._transport)
|
|
65
|
+
self.communities = CommunitiesResource(self._transport)
|
|
66
|
+
self.trending = TrendingResource(self._transport)
|
|
67
|
+
self.account = AccountResource(self._transport)
|
|
68
|
+
self.stream = StreamResource(self._transport)
|
|
69
|
+
|
|
70
|
+
def close(self) -> None:
|
|
71
|
+
"""Close the underlying HTTP client."""
|
|
72
|
+
self._transport.close()
|
|
73
|
+
|
|
74
|
+
def __enter__(self) -> "XCropClient":
|
|
75
|
+
return self
|
|
76
|
+
|
|
77
|
+
def __exit__(self, *args: object) -> None:
|
|
78
|
+
self.close()
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
class AsyncXCropClient:
|
|
82
|
+
"""Asynchronous XCROP API client.
|
|
83
|
+
|
|
84
|
+
Usage::
|
|
85
|
+
|
|
86
|
+
async with AsyncXCropClient(api_key="xc_live_...") as client:
|
|
87
|
+
user = await client.users.get("elonmusk")
|
|
88
|
+
async for tweet in client.users.tweets.paginate("elonmusk", count=200):
|
|
89
|
+
print(tweet)
|
|
90
|
+
"""
|
|
91
|
+
|
|
92
|
+
def __init__(
|
|
93
|
+
self,
|
|
94
|
+
api_key: str,
|
|
95
|
+
*,
|
|
96
|
+
base_url: str = DEFAULT_BASE_URL,
|
|
97
|
+
timeout: float = DEFAULT_TIMEOUT,
|
|
98
|
+
max_retries: int = MAX_RETRIES,
|
|
99
|
+
http_client: Optional[httpx.AsyncClient] = None,
|
|
100
|
+
) -> None:
|
|
101
|
+
self._transport = AsyncHttpTransport(
|
|
102
|
+
api_key=api_key,
|
|
103
|
+
base_url=base_url,
|
|
104
|
+
timeout=timeout,
|
|
105
|
+
max_retries=max_retries,
|
|
106
|
+
http_client=http_client,
|
|
107
|
+
)
|
|
108
|
+
self.users = AsyncUsersResource(self._transport)
|
|
109
|
+
self.tweets = AsyncTweetsResource(self._transport)
|
|
110
|
+
self.search = AsyncSearchResource(self._transport)
|
|
111
|
+
self.lists = AsyncListsResource(self._transport)
|
|
112
|
+
self.communities = AsyncCommunitiesResource(self._transport)
|
|
113
|
+
self.trending = AsyncTrendingResource(self._transport)
|
|
114
|
+
self.account = AsyncAccountResource(self._transport)
|
|
115
|
+
self.stream = AsyncStreamResource(self._transport)
|
|
116
|
+
|
|
117
|
+
async def close(self) -> None:
|
|
118
|
+
"""Close the underlying HTTP client."""
|
|
119
|
+
await self._transport.close()
|
|
120
|
+
|
|
121
|
+
async def __aenter__(self) -> "AsyncXCropClient":
|
|
122
|
+
return self
|
|
123
|
+
|
|
124
|
+
async def __aexit__(self, *args: object) -> None:
|
|
125
|
+
await self.close()
|
xcrop/errors.py
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
"""XCROP API exception classes."""
|
|
2
|
+
|
|
3
|
+
from typing import Optional
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class XCropError(Exception):
|
|
7
|
+
"""Base exception for all XCROP API errors."""
|
|
8
|
+
|
|
9
|
+
def __init__(
|
|
10
|
+
self,
|
|
11
|
+
message: str,
|
|
12
|
+
status_code: Optional[int] = None,
|
|
13
|
+
error_code: Optional[str] = None,
|
|
14
|
+
response: Optional[object] = None,
|
|
15
|
+
) -> None:
|
|
16
|
+
self.message = message
|
|
17
|
+
self.status_code = status_code
|
|
18
|
+
self.error_code = error_code
|
|
19
|
+
self.response = response
|
|
20
|
+
super().__init__(message)
|
|
21
|
+
|
|
22
|
+
def __repr__(self) -> str:
|
|
23
|
+
return (
|
|
24
|
+
f"{self.__class__.__name__}("
|
|
25
|
+
f"message={self.message!r}, "
|
|
26
|
+
f"status_code={self.status_code}, "
|
|
27
|
+
f"error_code={self.error_code!r})"
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class AuthError(XCropError):
|
|
32
|
+
"""Raised on 401 Unauthorized or 403 Forbidden responses."""
|
|
33
|
+
|
|
34
|
+
def __init__(
|
|
35
|
+
self,
|
|
36
|
+
message: str,
|
|
37
|
+
status_code: int = 401,
|
|
38
|
+
error_code: Optional[str] = None,
|
|
39
|
+
response: Optional[object] = None,
|
|
40
|
+
) -> None:
|
|
41
|
+
super().__init__(
|
|
42
|
+
message, status_code=status_code, error_code=error_code, response=response,
|
|
43
|
+
)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
class RateLimitError(XCropError):
|
|
47
|
+
"""Raised on 429 Too Many Requests (after all retries exhausted)."""
|
|
48
|
+
|
|
49
|
+
def __init__(
|
|
50
|
+
self,
|
|
51
|
+
message: str,
|
|
52
|
+
retry_after: Optional[float] = None,
|
|
53
|
+
error_code: Optional[str] = None,
|
|
54
|
+
response: Optional[object] = None,
|
|
55
|
+
) -> None:
|
|
56
|
+
super().__init__(
|
|
57
|
+
message, status_code=429, error_code=error_code, response=response,
|
|
58
|
+
)
|
|
59
|
+
self.retry_after = retry_after
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
class NotFoundError(XCropError):
|
|
63
|
+
"""Raised on 404 Not Found responses."""
|
|
64
|
+
|
|
65
|
+
def __init__(
|
|
66
|
+
self,
|
|
67
|
+
message: str,
|
|
68
|
+
error_code: Optional[str] = None,
|
|
69
|
+
response: Optional[object] = None,
|
|
70
|
+
) -> None:
|
|
71
|
+
super().__init__(
|
|
72
|
+
message, status_code=404, error_code=error_code, response=response,
|
|
73
|
+
)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
class ServerError(XCropError):
|
|
77
|
+
"""Raised on 5xx responses (after all retries exhausted)."""
|
|
78
|
+
|
|
79
|
+
def __init__(
|
|
80
|
+
self,
|
|
81
|
+
message: str,
|
|
82
|
+
status_code: int = 500,
|
|
83
|
+
error_code: Optional[str] = None,
|
|
84
|
+
response: Optional[object] = None,
|
|
85
|
+
) -> None:
|
|
86
|
+
super().__init__(
|
|
87
|
+
message, status_code=status_code, error_code=error_code, response=response,
|
|
88
|
+
)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
class StreamError(XCropError):
|
|
92
|
+
"""Raised when an SSE stream encounters an error."""
|
|
93
|
+
pass
|
xcrop/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""XCROP API resource namespaces."""
|
|
2
|
+
|
|
3
|
+
from .users import UsersResource, AsyncUsersResource
|
|
4
|
+
from .tweets import TweetsResource, AsyncTweetsResource
|
|
5
|
+
from .search import SearchResource, AsyncSearchResource
|
|
6
|
+
from .lists import ListsResource, AsyncListsResource
|
|
7
|
+
from .communities import CommunitiesResource, AsyncCommunitiesResource
|
|
8
|
+
from .trending import TrendingResource, AsyncTrendingResource
|
|
9
|
+
from .account import AccountResource, AsyncAccountResource
|
|
10
|
+
from .stream import StreamResource, AsyncStreamResource
|
|
11
|
+
|
|
12
|
+
__all__ = [
|
|
13
|
+
"UsersResource",
|
|
14
|
+
"AsyncUsersResource",
|
|
15
|
+
"TweetsResource",
|
|
16
|
+
"AsyncTweetsResource",
|
|
17
|
+
"SearchResource",
|
|
18
|
+
"AsyncSearchResource",
|
|
19
|
+
"ListsResource",
|
|
20
|
+
"AsyncListsResource",
|
|
21
|
+
"CommunitiesResource",
|
|
22
|
+
"AsyncCommunitiesResource",
|
|
23
|
+
"TrendingResource",
|
|
24
|
+
"AsyncTrendingResource",
|
|
25
|
+
"AccountResource",
|
|
26
|
+
"AsyncAccountResource",
|
|
27
|
+
"StreamResource",
|
|
28
|
+
"AsyncStreamResource",
|
|
29
|
+
]
|