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 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
@@ -0,0 +1,3 @@
1
+ """Single source of truth for the package version."""
2
+
3
+ __version__ = "1.0.1"
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
+ ]