flashdata 1.0.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.
- flashdata/__init__.py +34 -0
- flashdata/_async_client.py +213 -0
- flashdata/_client.py +210 -0
- flashdata/_common.py +265 -0
- flashdata/_resources.py +1945 -0
- flashdata/_schemas.json +1096 -0
- flashdata/errors.py +69 -0
- flashdata/py.typed +0 -0
- flashdata/types.py +1016 -0
- flashdata-1.0.0.dist-info/METADATA +315 -0
- flashdata-1.0.0.dist-info/RECORD +14 -0
- flashdata-1.0.0.dist-info/WHEEL +5 -0
- flashdata-1.0.0.dist-info/licenses/LICENSE +21 -0
- flashdata-1.0.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,315 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: flashdata
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Official Python SDK for FlashData Google Search, YouTube data and cloud media delivery APIs
|
|
5
|
+
Author-email: FlashData <support@flashdata.dev>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://flashdata.dev
|
|
8
|
+
Project-URL: Documentation, https://flashdata.dev/docs
|
|
9
|
+
Project-URL: Source, https://github.com/flashdatadev/flashdata-python
|
|
10
|
+
Project-URL: Issues, https://github.com/flashdatadev/flashdata-python/issues
|
|
11
|
+
Keywords: flashdata,google-search,youtube,transcripts,sdk,async,bulk
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Typing :: Typed
|
|
14
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
15
|
+
Requires-Python: >=3.10
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
License-File: LICENSE
|
|
18
|
+
Requires-Dist: httpx<1,>=0.27
|
|
19
|
+
Requires-Dist: jsonschema<5,>=4.23
|
|
20
|
+
Requires-Dist: typing_extensions<5,>=4.12
|
|
21
|
+
Provides-Extra: dev
|
|
22
|
+
Requires-Dist: pytest<10,>=8; extra == "dev"
|
|
23
|
+
Requires-Dist: pytest-asyncio<2,>=0.24; extra == "dev"
|
|
24
|
+
Requires-Dist: build<2,>=1; extra == "dev"
|
|
25
|
+
Requires-Dist: ruff<1,>=0.12; extra == "dev"
|
|
26
|
+
Requires-Dist: mypy<3,>=1.15; extra == "dev"
|
|
27
|
+
Requires-Dist: types-jsonschema; extra == "dev"
|
|
28
|
+
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
|
|
29
|
+
Provides-Extra: docs
|
|
30
|
+
Requires-Dist: sphinx<9,>=7; extra == "docs"
|
|
31
|
+
Requires-Dist: myst-parser<5,>=3; extra == "docs"
|
|
32
|
+
Requires-Dist: sphinx-rtd-theme<4,>=2; extra == "docs"
|
|
33
|
+
Dynamic: license-file
|
|
34
|
+
|
|
35
|
+
# FlashData Python SDK
|
|
36
|
+
|
|
37
|
+
[English](https://github.com/flashdatadev/flashdata-python/blob/main/README.md) | [简体中文](https://github.com/flashdatadev/flashdata-python/blob/main/README.zh-CN.md)
|
|
38
|
+
|
|
39
|
+
[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
|
|
40
|
+
|
|
41
|
+
Google search results and YouTube data for Python applications, research pipelines,
|
|
42
|
+
search monitoring, and retrieval workflows.
|
|
43
|
+
|
|
44
|
+
Get web, news, shopping, image, video, and local search results; discover YouTube videos,
|
|
45
|
+
read metadata and existing caption tracks; submit background jobs; and process video ID
|
|
46
|
+
files in bulk. The SDK includes synchronous and asynchronous clients, typed parameters,
|
|
47
|
+
local input validation, and structured errors. Python 3.10 or newer is required.
|
|
48
|
+
|
|
49
|
+
## What is FlashData?
|
|
50
|
+
|
|
51
|
+
[FlashData](https://flashdata.dev) provides APIs for Google search results, YouTube data,
|
|
52
|
+
and cloud media delivery. Developers and data teams use these APIs for search monitoring,
|
|
53
|
+
research, analytics, content discovery, and retrieval workflows for AI applications.
|
|
54
|
+
|
|
55
|
+
Retrieve web, news, shopping, image, video, and local search results; discover YouTube
|
|
56
|
+
videos and read metadata, existing caption tracks, channel data, and license labels.
|
|
57
|
+
Use realtime requests, background jobs, mixed batches, or bulk video ID files to fit your
|
|
58
|
+
workload. Media downloads deliver audio or video into your own cloud storage.
|
|
59
|
+
See the [API documentation](https://flashdata.dev/docs) and [pricing](https://flashdata.dev/pricing).
|
|
60
|
+
|
|
61
|
+
## Install
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
pip install flashdata
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
This command requires FlashData's official PyPI publication. For local testing before
|
|
68
|
+
release, use [installation from source](#install-from-source).
|
|
69
|
+
|
|
70
|
+
## Configure your API key
|
|
71
|
+
|
|
72
|
+
Obtain an API key from your [FlashData account](https://flashdata.dev) and pass it through
|
|
73
|
+
the client's `api_key` argument. The examples below use `os.getenv("FLASHDATA_API_KEY")`
|
|
74
|
+
to read the key from your environment. You can also pass a key supplied by your secret manager.
|
|
75
|
+
|
|
76
|
+
The SDK does not automatically load `.env` files. Load application configuration before
|
|
77
|
+
calling `os.getenv` if you use them.
|
|
78
|
+
|
|
79
|
+
```sh
|
|
80
|
+
# macOS / Linux
|
|
81
|
+
export FLASHDATA_API_KEY="YOUR_API_KEY"
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
```powershell
|
|
85
|
+
# PowerShell
|
|
86
|
+
$env:FLASHDATA_API_KEY = "YOUR_API_KEY"
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Search Google
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
import os
|
|
93
|
+
from flashdata import FlashData
|
|
94
|
+
|
|
95
|
+
with FlashData(api_key=os.getenv("FLASHDATA_API_KEY")) as client:
|
|
96
|
+
response = client.google.search("coffee roasters", gl="us", hl="en", num=5)
|
|
97
|
+
for page in response["results"]:
|
|
98
|
+
for hit in page.get("organic", []):
|
|
99
|
+
print(hit["title"], hit["link"])
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Responses are ordinary dictionaries. `response["results"]` contains source payloads:
|
|
103
|
+
Google web hits are in each payload's `organic` list. Other sources have their own
|
|
104
|
+
fields. Credits charged for the request are in `response["usage"]["credits"]`.
|
|
105
|
+
|
|
106
|
+
## Read a YouTube caption track
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
import os
|
|
110
|
+
from flashdata import FlashData
|
|
111
|
+
|
|
112
|
+
with FlashData(api_key=os.getenv("FLASHDATA_API_KEY")) as client:
|
|
113
|
+
response = client.youtube.captions("dQw4w9WgXcQ", language="en", auto=False)
|
|
114
|
+
for track in response["results"]:
|
|
115
|
+
print(track["languageCode"], track["isAutoGenerated"])
|
|
116
|
+
for segment in track.get("segments", [])[:3]:
|
|
117
|
+
print(segment["start"], segment["text"])
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Captions default to an uploaded track (`auto=False`); transcripts default to an automatic
|
|
121
|
+
track (`auto=True`). Choose a language and track that exist on the video. Missing tracks
|
|
122
|
+
return an API error; the service does not generate or translate them.
|
|
123
|
+
|
|
124
|
+
## Use asyncio
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
import os
|
|
128
|
+
import asyncio
|
|
129
|
+
from flashdata import AsyncFlashData
|
|
130
|
+
|
|
131
|
+
async def main():
|
|
132
|
+
async with AsyncFlashData(api_key=os.getenv("FLASHDATA_API_KEY")) as client:
|
|
133
|
+
response = await client.youtube.search("python tutorial", max_results=5)
|
|
134
|
+
for payload in response["results"]:
|
|
135
|
+
for video in payload.get("results", []):
|
|
136
|
+
print(video["title"], video["videoId"])
|
|
137
|
+
|
|
138
|
+
asyncio.run(main())
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
`AsyncFlashData` provides the same resources. Use `await` for requests and `async for`
|
|
142
|
+
for pagination and bulk row iterators. Reuse a client within an application or event loop.
|
|
143
|
+
|
|
144
|
+
## Run work in the background
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
import os
|
|
148
|
+
from flashdata import FlashData
|
|
149
|
+
|
|
150
|
+
with FlashData(api_key=os.getenv("FLASHDATA_API_KEY")) as client:
|
|
151
|
+
submitted = client.youtube.metadata("dQw4w9WgXcQ", mode="async", include_formats=False)
|
|
152
|
+
job_id = submitted["id"]
|
|
153
|
+
print("Save this job ID:", job_id, flush=True)
|
|
154
|
+
client.jobs.wait(job_id, timeout=300, poll_interval=2)
|
|
155
|
+
result = client.jobs.result(job_id)
|
|
156
|
+
print(result)
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Save the ID before waiting so the same job can be resumed after a process restart.
|
|
160
|
+
`wait()` returns the completed job record; `result()` retrieves its JSON output.
|
|
161
|
+
Use [batch submission](docs/jobs.md) for mixed queries and [bulk jobs](docs/bulk.md)
|
|
162
|
+
for UTF-8 files containing one YouTube video ID per line.
|
|
163
|
+
|
|
164
|
+
## Download YouTube videos in bulk
|
|
165
|
+
|
|
166
|
+
Create `video-ids.txt` with one video ID per line:
|
|
167
|
+
|
|
168
|
+
```text
|
|
169
|
+
dQw4w9WgXcQ
|
|
170
|
+
jNQXAC9IVRw
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Create `private-storage.json` with your destination configuration. For example, for S3:
|
|
174
|
+
|
|
175
|
+
```json
|
|
176
|
+
{
|
|
177
|
+
"storage_type": "s3",
|
|
178
|
+
"storage_url": "your-media-bucket",
|
|
179
|
+
"region": "us-east-1",
|
|
180
|
+
"object_prefix": "youtube",
|
|
181
|
+
"access_key": "YOUR_ACCESS_KEY",
|
|
182
|
+
"secret_key": "YOUR_SECRET_KEY"
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Then create the bulk download task, upload the ID file, and start processing:
|
|
187
|
+
|
|
188
|
+
```python
|
|
189
|
+
import json
|
|
190
|
+
import os
|
|
191
|
+
from pathlib import Path
|
|
192
|
+
from flashdata import FlashData
|
|
193
|
+
|
|
194
|
+
storage = json.loads(Path("private-storage.json").read_text(encoding="utf-8"))
|
|
195
|
+
|
|
196
|
+
with FlashData(api_key=os.getenv("FLASHDATA_API_KEY")) as client:
|
|
197
|
+
receipt = client.bulk.create({
|
|
198
|
+
"source": "youtube_download",
|
|
199
|
+
"options": {
|
|
200
|
+
"download_type": "audio_video",
|
|
201
|
+
"video_quality": "<=720",
|
|
202
|
+
"output_format": "mp4",
|
|
203
|
+
"storage": storage,
|
|
204
|
+
},
|
|
205
|
+
})
|
|
206
|
+
bulk_id = receipt["job"]["id"]
|
|
207
|
+
print("Save this bulk ID:", bulk_id, flush=True)
|
|
208
|
+
client.bulk.upload_file(receipt, Path("video-ids.txt"))
|
|
209
|
+
client.bulk.start(bulk_id)
|
|
210
|
+
|
|
211
|
+
completed = client.bulk.wait(bulk_id, timeout=3600, poll_interval=5)
|
|
212
|
+
print("Counts:", completed["counts"])
|
|
213
|
+
for row in client.bulk.rows(bulk_id):
|
|
214
|
+
print(row["video_id"], row["status"])
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Media files are delivered to your configured bucket. `bulk.rows()` reads the task's
|
|
218
|
+
JSON result records, including each video's status and source output in `results`.
|
|
219
|
+
Check the final counts and row statuses: a completed task can contain failed items.
|
|
220
|
+
Downloads are billed by actual delivered bytes; your storage provider may charge separately.
|
|
221
|
+
|
|
222
|
+
After a process restart or polling timeout, use the saved ID with `client.bulk.get()`,
|
|
223
|
+
`client.bulk.wait()`, and `client.bulk.rows()` to continue reading the existing task.
|
|
224
|
+
See [bulk controls and recovery](docs/bulk.md), [download options](docs/sources/youtube_download.md),
|
|
225
|
+
and [all supported storage providers](docs/storage.md).
|
|
226
|
+
|
|
227
|
+
The runnable example saves the job record beside its NDJSON export and resumes an
|
|
228
|
+
already started task without creating another submission:
|
|
229
|
+
|
|
230
|
+
```sh
|
|
231
|
+
python examples/bulk_download.py video-ids.txt --storage-file private-storage.json --output artifacts/downloads.ndjson
|
|
232
|
+
python examples/bulk_download.py --bulk-id bulk_YOUR_SAVED_ID --output artifacts/downloads.ndjson
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
## Handle failures
|
|
236
|
+
|
|
237
|
+
```python
|
|
238
|
+
import os
|
|
239
|
+
from flashdata import APIError, FlashData, SubmissionUnknownError
|
|
240
|
+
|
|
241
|
+
with FlashData(api_key=os.getenv("FLASHDATA_API_KEY"), timeout=120) as client:
|
|
242
|
+
try:
|
|
243
|
+
response = client.google.search("coffee", timeout=60)
|
|
244
|
+
except APIError as error:
|
|
245
|
+
print(error.status_code, error.code, error.request_id, error.retry_after)
|
|
246
|
+
except SubmissionUnknownError:
|
|
247
|
+
# The server may have accepted this paid request. Reconcile before resubmitting.
|
|
248
|
+
raise
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
The SDK sends each request once. It does not automatically retry paid queries or mutations.
|
|
252
|
+
See [errors and recovery](docs/errors.md) for rate limits, polling deadlines, failed jobs,
|
|
253
|
+
and storage errors. [Client configuration](docs/client.md) covers timeouts, proxies and TLS.
|
|
254
|
+
|
|
255
|
+
## Supported APIs
|
|
256
|
+
|
|
257
|
+
| Resource | Methods |
|
|
258
|
+
| --- | --- |
|
|
259
|
+
| Google | `search`, `images`, `news`, `shopping`, `videos`, `places`, bounded `pages` |
|
|
260
|
+
| YouTube | `search`, `search_extended`, `metadata`, `transcript`, `captions`, `license_check`, `channel`, `suggestions`, `download` |
|
|
261
|
+
| Queries | `realtime`, `submit`, `batch` with typed wire dictionaries |
|
|
262
|
+
| Jobs | `get`, `wait`, `result` |
|
|
263
|
+
| Bulk | `create`, `upload_file`, `start`, `get`, `list`, `iter_jobs`, `update`, `pause`, `resume`, `cancel`, `wait`, `manifest`, `part`, `iter_rows`, `rows` |
|
|
264
|
+
| Account | `access`, `balance`, `pricing`, `limits`, `usage` |
|
|
265
|
+
| Public | `sources`, `plans`, `health`, `status` (no key needed) |
|
|
266
|
+
|
|
267
|
+
All 15 sources support background submission and batch. The 14 data sources also support
|
|
268
|
+
realtime calls. Media downloads run in the background and require customer cloud storage.
|
|
269
|
+
Bulk supports metadata, transcripts, captions, license labels, and downloads.
|
|
270
|
+
|
|
271
|
+
## Guides and runnable examples
|
|
272
|
+
|
|
273
|
+
- [Getting started](docs/getting-started.md) — install, authenticate, understand responses.
|
|
274
|
+
- [Source guides](docs/sources/index.md) — parameters and useful recipes for every source.
|
|
275
|
+
- [Examples](examples/README.md) — CLI inputs, readable output, JSON/CSV/NDJSON export.
|
|
276
|
+
- [Pagination](docs/pagination.md), [jobs and batch](docs/jobs.md), [bulk datasets](docs/bulk.md).
|
|
277
|
+
- [Cloud storage](docs/storage.md), [account and usage](docs/account.md), [API reference](docs/api-reference.md).
|
|
278
|
+
|
|
279
|
+
```sh
|
|
280
|
+
python examples/google_search.py "coffee roasters" --output artifacts/search.json
|
|
281
|
+
python examples/search_to_csv.py "coffee roasters" --max-pages 2 --output artifacts/search.csv
|
|
282
|
+
python examples/youtube_captions.py dQw4w9WgXcQ --language en
|
|
283
|
+
python examples/async_query.py "python tutorial" --output artifacts/result.json
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
These commands call the live API and consume credits. Run `python examples/offline.py`
|
|
287
|
+
for a demonstration with a mock transport and no account.
|
|
288
|
+
|
|
289
|
+
The [SDK comparison](docs/sdk-parity.md) maps Python and TypeScript coverage, language
|
|
290
|
+
differences, workflow guarantees, and verification limits side by side.
|
|
291
|
+
|
|
292
|
+
## Install from source
|
|
293
|
+
|
|
294
|
+
From a checkout of this repository:
|
|
295
|
+
|
|
296
|
+
```sh
|
|
297
|
+
python -m pip install .
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
## Development
|
|
301
|
+
|
|
302
|
+
```sh
|
|
303
|
+
python -m pip install -e ".[dev,docs]"
|
|
304
|
+
python -m pytest
|
|
305
|
+
python -m ruff check src tests examples scripts docs/conf.py
|
|
306
|
+
python -m ruff format --check src tests examples scripts docs/conf.py
|
|
307
|
+
python -m mypy src/flashdata
|
|
308
|
+
python -m sphinx -n -W --keep-going -b html docs docs/_build/html
|
|
309
|
+
python -m build
|
|
310
|
+
python scripts/verify_package.py
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
Tests use mock transports and a local HTTP server by default. Explicit opt-in tests
|
|
314
|
+
exercise live APIs; see [contributing](CONTRIBUTING.md). The project is MIT licensed.
|
|
315
|
+
Report sensitive issues through [the security policy](SECURITY.md).
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
flashdata/__init__.py,sha256=mms_5udT12jpdzw_xEssgtA_YEWnlKt3ujcuGIov09Q,713
|
|
2
|
+
flashdata/_async_client.py,sha256=incFBT6rG3FYd_Dnp7XDO17iit02N8SThzb2RYlaCHo,8945
|
|
3
|
+
flashdata/_client.py,sha256=9WScojswhNzGICyJa9SMnu3Nmck8MzEWwqiRYNogvIQ,8658
|
|
4
|
+
flashdata/_common.py,sha256=6RLb-3Zv9SvlNZHSgeoeJhfvlrzFLxm_xnotY5ycyyk,10991
|
|
5
|
+
flashdata/_resources.py,sha256=lDhw_wKDap5i9e66wzoUF5llIPKVJToMwEi5PoPR3Pw,74273
|
|
6
|
+
flashdata/_schemas.json,sha256=EvZST5jmyBAC8W7rInecxAbaYUWKRgziB3Dy74UI3hM,32142
|
|
7
|
+
flashdata/errors.py,sha256=mR0FBzZgqCBbPXj7roq_59jEbCzIHOJxes1PLowKaeM,1957
|
|
8
|
+
flashdata/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
9
|
+
flashdata/types.py,sha256=Bh5gmqWqb4pXqz5_P3qXS6udlVVank_w_DeruXQVuB4,28995
|
|
10
|
+
flashdata-1.0.0.dist-info/licenses/LICENSE,sha256=bEsMP83WX5XIwLDTYq8cIsQVzhsxuRIhASHFoe1fG5Y,1066
|
|
11
|
+
flashdata-1.0.0.dist-info/METADATA,sha256=2A_FLKnL3lDZyRWFH0C2oXjMBwwSKww8hLm_OhScw6A,12384
|
|
12
|
+
flashdata-1.0.0.dist-info/WHEEL,sha256=a-udL2m4V_6Yn8b-uKzWb12RjRxwwMo6ohYFM24tpaY,91
|
|
13
|
+
flashdata-1.0.0.dist-info/top_level.txt,sha256=3GqDnfr9T5rfoVrBnZy12jW2VRXH3cHgGSLyCb9NMR4,10
|
|
14
|
+
flashdata-1.0.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 FlashData
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
flashdata
|