xcrop 1.0.1__tar.gz

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-1.0.1/.gitignore ADDED
@@ -0,0 +1,19 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *$py.class
4
+ *.egg-info/
5
+ dist/
6
+ build/
7
+ .eggs/
8
+ *.egg
9
+ .venv/
10
+ venv/
11
+ env/
12
+ .env
13
+ .tox/
14
+ .mypy_cache/
15
+ .pytest_cache/
16
+ .ruff_cache/
17
+ *.so
18
+ .DS_Store
19
+ Thumbs.db
xcrop-1.0.1/PKG-INFO ADDED
@@ -0,0 +1,345 @@
1
+ Metadata-Version: 2.5
2
+ Name: xcrop
3
+ Version: 1.0.1
4
+ Summary: Official Python SDK for the XCROP API, the X/Twitter data intelligence platform
5
+ Project-URL: Homepage, https://xcrop.io
6
+ Project-URL: Documentation, https://xcrop.io/docs
7
+ Project-URL: Repository, https://github.com/xcrop-io/xcrop-python
8
+ Project-URL: Issues, https://github.com/xcrop-io/xcrop-python/issues
9
+ Author-email: XCROP <support@xcrop.io>
10
+ License-Expression: MIT
11
+ Keywords: api,data,intelligence,scraper,twitter,x,xcrop
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.8
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
+ Classifier: Typing :: Typed
24
+ Requires-Python: >=3.8
25
+ Requires-Dist: httpx>=0.24.0
26
+ Requires-Dist: typing-extensions>=3.7.4; python_version < '3.12'
27
+ Description-Content-Type: text/markdown
28
+
29
+ # XCROP Python SDK
30
+
31
+ Official Python client for the [XCROP API](https://xcrop.io), the X/Twitter data intelligence platform. 42 endpoints covering profile lookup, timelines, search, lists, communities, account monitoring, write operations, and interaction/eligibility checks.
32
+
33
+ ## Installation
34
+
35
+ ```bash
36
+ pip install xcrop
37
+ ```
38
+
39
+ ## Quick Start
40
+
41
+ ```python
42
+ from xcrop import XCropClient
43
+
44
+ client = XCropClient(api_key="xc_live_...")
45
+
46
+ # Get user profile
47
+ user = client.users.get("elonmusk")
48
+ print(user["data"]["name"])
49
+
50
+ # Get user tweets
51
+ tweets = client.users.tweets("elonmusk", count=50)
52
+ for tweet in tweets["data"]:
53
+ print(tweet["text"])
54
+ ```
55
+
56
+ ## Features
57
+
58
+ - **Sync & Async**: `XCropClient` (sync) and `AsyncXCropClient` (async) with identical APIs
59
+ - **Auto-retry**: Exponential backoff on 429 (rate limit) and 5xx errors, up to 3 retries
60
+ - **Auto-pagination**: `.paginate()` iterators handle cursor-based pagination automatically
61
+ - **SSE Streaming**: Real-time search streaming and event streams
62
+ - **Type hints**: Full typing for IDE autocomplete
63
+ - **Custom exceptions**: `AuthError`, `RateLimitError`, `NotFoundError`, `ServerError`
64
+
65
+ ## Usage
66
+
67
+ ### Users
68
+
69
+ ```python
70
+ # Profile
71
+ user = client.users.get("elonmusk")
72
+
73
+ # Tweets, followers, following, etc.
74
+ tweets = client.users.tweets("elonmusk", count=20)
75
+ followers = client.users.followers("elonmusk", count=50)
76
+ following = client.users.following("elonmusk")
77
+ mentions = client.users.mentions("elonmusk")
78
+ replies = client.users.replies("elonmusk")
79
+ media = client.users.media("elonmusk")
80
+ verified = client.users.verified_followers("elonmusk")
81
+
82
+ # Bulk follower IDs (up to 5,000 per call, no profile metadata)
83
+ ids = client.users.followers_ids("elonmusk", count=5000)
84
+
85
+ # Auto-paginate (fetches all pages, yields individual items)
86
+ for tweet in client.users.tweets.paginate("elonmusk", count=200):
87
+ print(tweet["text"])
88
+
89
+ # Batch lookup (up to 100)
90
+ users = client.users.batch(["elonmusk", "jack", "vaboronin"])
91
+
92
+ # Follow relationship check: does `source` follow `target`?
93
+ rel = client.users.check_follow(source="jack", target="elonmusk")
94
+ print(rel["data"]["source_follows_target"])
95
+
96
+ # Eligibility checks (for giveaway/airdrop gating)
97
+ account_ok = client.users.check_qualified_account(
98
+ "elonmusk", min_followers=100, min_age_days=30,
99
+ )
100
+ name_ok = client.users.check_qualified_name(
101
+ "elonmusk", contains="Musk", position="anywhere",
102
+ )
103
+
104
+ # Follow / unfollow (requires connected account)
105
+ client.users.follow("jack")
106
+ client.users.unfollow("jack")
107
+ ```
108
+
109
+ ### Tweets
110
+
111
+ ```python
112
+ # Single tweet
113
+ tweet = client.tweets.get("1234567890")
114
+
115
+ # Conversation thread
116
+ conv = client.tweets.conversation("1234567890", count=50)
117
+
118
+ # Quotes (with pagination)
119
+ for quote in client.tweets.quotes.paginate("1234567890", count=100):
120
+ print(quote["text"])
121
+
122
+ # Batch lookup
123
+ tweets = client.tweets.batch(["123", "456", "789"])
124
+
125
+ # Write operations (requires connected account)
126
+ result = client.tweets.create(text="Hello from XCROP SDK!")
127
+ client.tweets.reply(tweet_id="1234567890", text="Great thread!")
128
+ client.tweets.quote(tweet_id="1234567890", text="Interesting take")
129
+ client.tweets.delete(tweet_id="1234567890")
130
+
131
+ # Like / unlike / retweet / unretweet
132
+ client.tweets.like("1234567890")
133
+ client.tweets.unlike("1234567890")
134
+ client.tweets.retweet("1234567890")
135
+ client.tweets.unretweet("1234567890")
136
+
137
+ # Interaction checks (no connected account needed)
138
+ check = client.tweets.check_retweet("1234567890", username="jack")
139
+ print(check["data"]["result"]) # True/False
140
+
141
+ # check_reply / check_quote also accept an optional min_tags (0-20)
142
+ check = client.tweets.check_reply("1234567890", username="jack", min_tags=1)
143
+ ```
144
+
145
+ ### Search
146
+
147
+ ```python
148
+ # Basic search
149
+ results = client.search.tweets(query="bitcoin", count=50)
150
+
151
+ # Advanced search
152
+ results = client.search.tweets(
153
+ query="ethereum",
154
+ sort="popular",
155
+ lang="en",
156
+ min_likes=100,
157
+ exclude_replies=True,
158
+ since="2024-01-01",
159
+ )
160
+
161
+ # Auto-paginate search
162
+ for tweet in client.search.tweets_paginate(query="bitcoin", count=200, sort="latest"):
163
+ print(tweet["text"])
164
+
165
+ # SSE streaming search
166
+ for tweet in client.search.tweets_stream(query="breaking", count=100):
167
+ print(tweet)
168
+
169
+ # User search
170
+ users = client.search.users(query="crypto trader", count=20)
171
+ ```
172
+
173
+ ### Lists
174
+
175
+ ```python
176
+ tweets = client.lists.tweets("1234567890", count=50)
177
+ members = client.lists.members("1234567890")
178
+ subscribers = client.lists.subscribers("1234567890")
179
+
180
+ # Paginate
181
+ for tweet in client.lists.tweets.paginate("1234567890", count=200):
182
+ print(tweet["text"])
183
+ ```
184
+
185
+ ### Trending
186
+
187
+ ```python
188
+ trending = client.trending.get()
189
+ for topic in trending["data"]:
190
+ print(topic["name"], topic.get("tweet_count"))
191
+ ```
192
+
193
+ ### Communities (beta)
194
+
195
+ > Communities endpoints are still rolling out and may return a `503`
196
+ > (`ServerError`) while the underlying data source stabilizes.
197
+
198
+ ```python
199
+ from xcrop import ServerError
200
+
201
+ try:
202
+ community = client.communities.get("1708766018985501165")
203
+ tweets = client.communities.tweets("1708766018985501165", count=50)
204
+ members = client.communities.members("1708766018985501165", count=50)
205
+
206
+ for tweet in client.communities.tweets.paginate("1708766018985501165", count=200):
207
+ print(tweet["text"])
208
+ except ServerError:
209
+ print("Communities data source temporarily unavailable")
210
+ ```
211
+
212
+ ### Account Management
213
+
214
+ ```python
215
+ # Connect via credentials
216
+ client.account.connect(username="myuser", password="mypass", totp_secret="TOTP_SECRET")
217
+
218
+ # Connect via cookies
219
+ client.account.connect(cookies={"auth_token": "...", "ct0": "..."})
220
+
221
+ # Check status
222
+ status = client.account.status()
223
+ print(status["data"]["connected"])
224
+
225
+ # Disconnect
226
+ client.account.disconnect()
227
+ ```
228
+
229
+ ### Real-time Stream
230
+
231
+ ```python
232
+ for event in client.stream.connect():
233
+ print(event)
234
+ ```
235
+
236
+ ## Async Usage
237
+
238
+ ```python
239
+ import asyncio
240
+ from xcrop import AsyncXCropClient
241
+
242
+ async def main():
243
+ async with AsyncXCropClient(api_key="xc_live_...") as client:
244
+ # All methods are async
245
+ user = await client.users.get("elonmusk")
246
+ print(user["data"]["name"])
247
+
248
+ # Async pagination
249
+ async for tweet in client.users.tweets.paginate("elonmusk", count=200):
250
+ print(tweet["text"])
251
+
252
+ # Async search streaming
253
+ async for tweet in client.search.tweets_stream(query="breaking"):
254
+ print(tweet)
255
+
256
+ asyncio.run(main())
257
+ ```
258
+
259
+ ## Error Handling
260
+
261
+ ```python
262
+ from xcrop import XCropClient, AuthError, RateLimitError, NotFoundError, XCropError
263
+
264
+ client = XCropClient(api_key="xc_live_...")
265
+
266
+ try:
267
+ user = client.users.get("nonexistent_user_12345")
268
+ except NotFoundError:
269
+ print("User not found")
270
+ except AuthError:
271
+ print("Invalid API key")
272
+ except RateLimitError as e:
273
+ print(f"Rate limited. Retry after: {e.retry_after}s")
274
+ except XCropError as e:
275
+ print(f"API error: {e.message} (HTTP {e.status_code})")
276
+ ```
277
+
278
+ ## Configuration
279
+
280
+ ```python
281
+ client = XCropClient(
282
+ api_key="xc_live_...",
283
+ base_url="https://xcrop.io/api/v2", # default
284
+ timeout=30.0, # seconds, default
285
+ max_retries=3, # default
286
+ )
287
+ ```
288
+
289
+ You can also pass a custom `httpx.Client` or `httpx.AsyncClient`:
290
+
291
+ ```python
292
+ import httpx
293
+
294
+ http = httpx.Client(proxy="http://proxy:8080")
295
+ client = XCropClient(api_key="xc_live_...", http_client=http)
296
+ ```
297
+
298
+ ## Rate Limits & Plans
299
+
300
+ Per-minute request limits are enforced per plan (in addition to the monthly
301
+ credit allowance):
302
+
303
+ | Plan | Requests / min |
304
+ |---------|-----------------|
305
+ | Starter | 60 |
306
+ | Basic | 300 |
307
+ | Pro | 600 |
308
+ | PAYG | 300 |
309
+
310
+ Exceeding the limit raises `RateLimitError` (the SDK auto-retries 429s with
311
+ backoff before raising). See [xcrop.io/pricing](https://xcrop.io/pricing) for
312
+ credit costs per endpoint.
313
+
314
+ ## Billing
315
+
316
+ Plans and credit top-ups are paid via cryptocurrency: **USDT (BEP-20)**,
317
+ **USDC (BEP-20)**, **SOL**, and **POL**. Credit card payments via Stripe are
318
+ coming soon. See [xcrop.io/pricing](https://xcrop.io/pricing) and the
319
+ dashboard billing page to manage your subscription.
320
+
321
+ ## API Response Format
322
+
323
+ All methods return the raw API response as a dict:
324
+
325
+ ```python
326
+ {
327
+ "data": ..., # Response payload
328
+ "meta": {
329
+ "latency_ms": 123,
330
+ "cached": True,
331
+ "total": 50,
332
+ "cursor": "abc123",
333
+ "has_next": True,
334
+ }
335
+ }
336
+ ```
337
+
338
+ ## Requirements
339
+
340
+ - Python 3.8+
341
+ - httpx >= 0.24.0
342
+
343
+ ## License
344
+
345
+ MIT
xcrop-1.0.1/README.md ADDED
@@ -0,0 +1,317 @@
1
+ # XCROP Python SDK
2
+
3
+ Official Python client for the [XCROP API](https://xcrop.io), the X/Twitter data intelligence platform. 42 endpoints covering profile lookup, timelines, search, lists, communities, account monitoring, write operations, and interaction/eligibility checks.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pip install xcrop
9
+ ```
10
+
11
+ ## Quick Start
12
+
13
+ ```python
14
+ from xcrop import XCropClient
15
+
16
+ client = XCropClient(api_key="xc_live_...")
17
+
18
+ # Get user profile
19
+ user = client.users.get("elonmusk")
20
+ print(user["data"]["name"])
21
+
22
+ # Get user tweets
23
+ tweets = client.users.tweets("elonmusk", count=50)
24
+ for tweet in tweets["data"]:
25
+ print(tweet["text"])
26
+ ```
27
+
28
+ ## Features
29
+
30
+ - **Sync & Async**: `XCropClient` (sync) and `AsyncXCropClient` (async) with identical APIs
31
+ - **Auto-retry**: Exponential backoff on 429 (rate limit) and 5xx errors, up to 3 retries
32
+ - **Auto-pagination**: `.paginate()` iterators handle cursor-based pagination automatically
33
+ - **SSE Streaming**: Real-time search streaming and event streams
34
+ - **Type hints**: Full typing for IDE autocomplete
35
+ - **Custom exceptions**: `AuthError`, `RateLimitError`, `NotFoundError`, `ServerError`
36
+
37
+ ## Usage
38
+
39
+ ### Users
40
+
41
+ ```python
42
+ # Profile
43
+ user = client.users.get("elonmusk")
44
+
45
+ # Tweets, followers, following, etc.
46
+ tweets = client.users.tweets("elonmusk", count=20)
47
+ followers = client.users.followers("elonmusk", count=50)
48
+ following = client.users.following("elonmusk")
49
+ mentions = client.users.mentions("elonmusk")
50
+ replies = client.users.replies("elonmusk")
51
+ media = client.users.media("elonmusk")
52
+ verified = client.users.verified_followers("elonmusk")
53
+
54
+ # Bulk follower IDs (up to 5,000 per call, no profile metadata)
55
+ ids = client.users.followers_ids("elonmusk", count=5000)
56
+
57
+ # Auto-paginate (fetches all pages, yields individual items)
58
+ for tweet in client.users.tweets.paginate("elonmusk", count=200):
59
+ print(tweet["text"])
60
+
61
+ # Batch lookup (up to 100)
62
+ users = client.users.batch(["elonmusk", "jack", "vaboronin"])
63
+
64
+ # Follow relationship check: does `source` follow `target`?
65
+ rel = client.users.check_follow(source="jack", target="elonmusk")
66
+ print(rel["data"]["source_follows_target"])
67
+
68
+ # Eligibility checks (for giveaway/airdrop gating)
69
+ account_ok = client.users.check_qualified_account(
70
+ "elonmusk", min_followers=100, min_age_days=30,
71
+ )
72
+ name_ok = client.users.check_qualified_name(
73
+ "elonmusk", contains="Musk", position="anywhere",
74
+ )
75
+
76
+ # Follow / unfollow (requires connected account)
77
+ client.users.follow("jack")
78
+ client.users.unfollow("jack")
79
+ ```
80
+
81
+ ### Tweets
82
+
83
+ ```python
84
+ # Single tweet
85
+ tweet = client.tweets.get("1234567890")
86
+
87
+ # Conversation thread
88
+ conv = client.tweets.conversation("1234567890", count=50)
89
+
90
+ # Quotes (with pagination)
91
+ for quote in client.tweets.quotes.paginate("1234567890", count=100):
92
+ print(quote["text"])
93
+
94
+ # Batch lookup
95
+ tweets = client.tweets.batch(["123", "456", "789"])
96
+
97
+ # Write operations (requires connected account)
98
+ result = client.tweets.create(text="Hello from XCROP SDK!")
99
+ client.tweets.reply(tweet_id="1234567890", text="Great thread!")
100
+ client.tweets.quote(tweet_id="1234567890", text="Interesting take")
101
+ client.tweets.delete(tweet_id="1234567890")
102
+
103
+ # Like / unlike / retweet / unretweet
104
+ client.tweets.like("1234567890")
105
+ client.tweets.unlike("1234567890")
106
+ client.tweets.retweet("1234567890")
107
+ client.tweets.unretweet("1234567890")
108
+
109
+ # Interaction checks (no connected account needed)
110
+ check = client.tweets.check_retweet("1234567890", username="jack")
111
+ print(check["data"]["result"]) # True/False
112
+
113
+ # check_reply / check_quote also accept an optional min_tags (0-20)
114
+ check = client.tweets.check_reply("1234567890", username="jack", min_tags=1)
115
+ ```
116
+
117
+ ### Search
118
+
119
+ ```python
120
+ # Basic search
121
+ results = client.search.tweets(query="bitcoin", count=50)
122
+
123
+ # Advanced search
124
+ results = client.search.tweets(
125
+ query="ethereum",
126
+ sort="popular",
127
+ lang="en",
128
+ min_likes=100,
129
+ exclude_replies=True,
130
+ since="2024-01-01",
131
+ )
132
+
133
+ # Auto-paginate search
134
+ for tweet in client.search.tweets_paginate(query="bitcoin", count=200, sort="latest"):
135
+ print(tweet["text"])
136
+
137
+ # SSE streaming search
138
+ for tweet in client.search.tweets_stream(query="breaking", count=100):
139
+ print(tweet)
140
+
141
+ # User search
142
+ users = client.search.users(query="crypto trader", count=20)
143
+ ```
144
+
145
+ ### Lists
146
+
147
+ ```python
148
+ tweets = client.lists.tweets("1234567890", count=50)
149
+ members = client.lists.members("1234567890")
150
+ subscribers = client.lists.subscribers("1234567890")
151
+
152
+ # Paginate
153
+ for tweet in client.lists.tweets.paginate("1234567890", count=200):
154
+ print(tweet["text"])
155
+ ```
156
+
157
+ ### Trending
158
+
159
+ ```python
160
+ trending = client.trending.get()
161
+ for topic in trending["data"]:
162
+ print(topic["name"], topic.get("tweet_count"))
163
+ ```
164
+
165
+ ### Communities (beta)
166
+
167
+ > Communities endpoints are still rolling out and may return a `503`
168
+ > (`ServerError`) while the underlying data source stabilizes.
169
+
170
+ ```python
171
+ from xcrop import ServerError
172
+
173
+ try:
174
+ community = client.communities.get("1708766018985501165")
175
+ tweets = client.communities.tweets("1708766018985501165", count=50)
176
+ members = client.communities.members("1708766018985501165", count=50)
177
+
178
+ for tweet in client.communities.tweets.paginate("1708766018985501165", count=200):
179
+ print(tweet["text"])
180
+ except ServerError:
181
+ print("Communities data source temporarily unavailable")
182
+ ```
183
+
184
+ ### Account Management
185
+
186
+ ```python
187
+ # Connect via credentials
188
+ client.account.connect(username="myuser", password="mypass", totp_secret="TOTP_SECRET")
189
+
190
+ # Connect via cookies
191
+ client.account.connect(cookies={"auth_token": "...", "ct0": "..."})
192
+
193
+ # Check status
194
+ status = client.account.status()
195
+ print(status["data"]["connected"])
196
+
197
+ # Disconnect
198
+ client.account.disconnect()
199
+ ```
200
+
201
+ ### Real-time Stream
202
+
203
+ ```python
204
+ for event in client.stream.connect():
205
+ print(event)
206
+ ```
207
+
208
+ ## Async Usage
209
+
210
+ ```python
211
+ import asyncio
212
+ from xcrop import AsyncXCropClient
213
+
214
+ async def main():
215
+ async with AsyncXCropClient(api_key="xc_live_...") as client:
216
+ # All methods are async
217
+ user = await client.users.get("elonmusk")
218
+ print(user["data"]["name"])
219
+
220
+ # Async pagination
221
+ async for tweet in client.users.tweets.paginate("elonmusk", count=200):
222
+ print(tweet["text"])
223
+
224
+ # Async search streaming
225
+ async for tweet in client.search.tweets_stream(query="breaking"):
226
+ print(tweet)
227
+
228
+ asyncio.run(main())
229
+ ```
230
+
231
+ ## Error Handling
232
+
233
+ ```python
234
+ from xcrop import XCropClient, AuthError, RateLimitError, NotFoundError, XCropError
235
+
236
+ client = XCropClient(api_key="xc_live_...")
237
+
238
+ try:
239
+ user = client.users.get("nonexistent_user_12345")
240
+ except NotFoundError:
241
+ print("User not found")
242
+ except AuthError:
243
+ print("Invalid API key")
244
+ except RateLimitError as e:
245
+ print(f"Rate limited. Retry after: {e.retry_after}s")
246
+ except XCropError as e:
247
+ print(f"API error: {e.message} (HTTP {e.status_code})")
248
+ ```
249
+
250
+ ## Configuration
251
+
252
+ ```python
253
+ client = XCropClient(
254
+ api_key="xc_live_...",
255
+ base_url="https://xcrop.io/api/v2", # default
256
+ timeout=30.0, # seconds, default
257
+ max_retries=3, # default
258
+ )
259
+ ```
260
+
261
+ You can also pass a custom `httpx.Client` or `httpx.AsyncClient`:
262
+
263
+ ```python
264
+ import httpx
265
+
266
+ http = httpx.Client(proxy="http://proxy:8080")
267
+ client = XCropClient(api_key="xc_live_...", http_client=http)
268
+ ```
269
+
270
+ ## Rate Limits & Plans
271
+
272
+ Per-minute request limits are enforced per plan (in addition to the monthly
273
+ credit allowance):
274
+
275
+ | Plan | Requests / min |
276
+ |---------|-----------------|
277
+ | Starter | 60 |
278
+ | Basic | 300 |
279
+ | Pro | 600 |
280
+ | PAYG | 300 |
281
+
282
+ Exceeding the limit raises `RateLimitError` (the SDK auto-retries 429s with
283
+ backoff before raising). See [xcrop.io/pricing](https://xcrop.io/pricing) for
284
+ credit costs per endpoint.
285
+
286
+ ## Billing
287
+
288
+ Plans and credit top-ups are paid via cryptocurrency: **USDT (BEP-20)**,
289
+ **USDC (BEP-20)**, **SOL**, and **POL**. Credit card payments via Stripe are
290
+ coming soon. See [xcrop.io/pricing](https://xcrop.io/pricing) and the
291
+ dashboard billing page to manage your subscription.
292
+
293
+ ## API Response Format
294
+
295
+ All methods return the raw API response as a dict:
296
+
297
+ ```python
298
+ {
299
+ "data": ..., # Response payload
300
+ "meta": {
301
+ "latency_ms": 123,
302
+ "cached": True,
303
+ "total": 50,
304
+ "cursor": "abc123",
305
+ "has_next": True,
306
+ }
307
+ }
308
+ ```
309
+
310
+ ## Requirements
311
+
312
+ - Python 3.8+
313
+ - httpx >= 0.24.0
314
+
315
+ ## License
316
+
317
+ MIT