flashdata 1.0.0__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.
Files changed (99) hide show
  1. flashdata-1.0.0/.readthedocs.yaml +13 -0
  2. flashdata-1.0.0/CHANGELOG.md +33 -0
  3. flashdata-1.0.0/CONTRIBUTING.md +53 -0
  4. flashdata-1.0.0/LICENSE +21 -0
  5. flashdata-1.0.0/MANIFEST.in +11 -0
  6. flashdata-1.0.0/PKG-INFO +315 -0
  7. flashdata-1.0.0/README.md +281 -0
  8. flashdata-1.0.0/README.zh-CN.md +270 -0
  9. flashdata-1.0.0/SECURITY.md +16 -0
  10. flashdata-1.0.0/docs/_static/custom.css +5 -0
  11. flashdata-1.0.0/docs/account.md +45 -0
  12. flashdata-1.0.0/docs/api-reference.md +78 -0
  13. flashdata-1.0.0/docs/architecture.md +27 -0
  14. flashdata-1.0.0/docs/bulk.md +127 -0
  15. flashdata-1.0.0/docs/client.md +99 -0
  16. flashdata-1.0.0/docs/conf.py +21 -0
  17. flashdata-1.0.0/docs/errors.md +62 -0
  18. flashdata-1.0.0/docs/examples.md +7 -0
  19. flashdata-1.0.0/docs/getting-started.md +85 -0
  20. flashdata-1.0.0/docs/index.md +45 -0
  21. flashdata-1.0.0/docs/jobs.md +73 -0
  22. flashdata-1.0.0/docs/pagination.md +31 -0
  23. flashdata-1.0.0/docs/recipes.md +30 -0
  24. flashdata-1.0.0/docs/release.md +64 -0
  25. flashdata-1.0.0/docs/sdk-parity.md +108 -0
  26. flashdata-1.0.0/docs/sources/google_images.md +38 -0
  27. flashdata-1.0.0/docs/sources/google_news.md +38 -0
  28. flashdata-1.0.0/docs/sources/google_places.md +38 -0
  29. flashdata-1.0.0/docs/sources/google_search.md +38 -0
  30. flashdata-1.0.0/docs/sources/google_shopping.md +38 -0
  31. flashdata-1.0.0/docs/sources/google_videos.md +38 -0
  32. flashdata-1.0.0/docs/sources/index.md +43 -0
  33. flashdata-1.0.0/docs/sources/youtube_captions.md +36 -0
  34. flashdata-1.0.0/docs/sources/youtube_channel.md +32 -0
  35. flashdata-1.0.0/docs/sources/youtube_download.md +55 -0
  36. flashdata-1.0.0/docs/sources/youtube_metadata.md +32 -0
  37. flashdata-1.0.0/docs/sources/youtube_search.md +57 -0
  38. flashdata-1.0.0/docs/sources/youtube_search_extended.md +57 -0
  39. flashdata-1.0.0/docs/sources/youtube_suggestions.md +33 -0
  40. flashdata-1.0.0/docs/sources/youtube_trainability.md +31 -0
  41. flashdata-1.0.0/docs/sources/youtube_transcript.md +36 -0
  42. flashdata-1.0.0/docs/storage.md +41 -0
  43. flashdata-1.0.0/docs/validation.md +76 -0
  44. flashdata-1.0.0/examples/README.md +85 -0
  45. flashdata-1.0.0/examples/_bulk.py +39 -0
  46. flashdata-1.0.0/examples/_support.py +39 -0
  47. flashdata-1.0.0/examples/account.py +29 -0
  48. flashdata-1.0.0/examples/async_client.py +59 -0
  49. flashdata-1.0.0/examples/async_query.py +34 -0
  50. flashdata-1.0.0/examples/batch.py +43 -0
  51. flashdata-1.0.0/examples/bulk.py +24 -0
  52. flashdata-1.0.0/examples/bulk_download.py +41 -0
  53. flashdata-1.0.0/examples/discovery.py +26 -0
  54. flashdata-1.0.0/examples/google_images.py +30 -0
  55. flashdata-1.0.0/examples/google_news.py +29 -0
  56. flashdata-1.0.0/examples/google_places.py +29 -0
  57. flashdata-1.0.0/examples/google_search.py +30 -0
  58. flashdata-1.0.0/examples/google_shopping.py +29 -0
  59. flashdata-1.0.0/examples/google_videos.py +29 -0
  60. flashdata-1.0.0/examples/offline.py +29 -0
  61. flashdata-1.0.0/examples/pagination.py +7 -0
  62. flashdata-1.0.0/examples/search_to_csv.py +43 -0
  63. flashdata-1.0.0/examples/video-ids.example.txt +1 -0
  64. flashdata-1.0.0/examples/youtube_captions.py +30 -0
  65. flashdata-1.0.0/examples/youtube_channel.py +26 -0
  66. flashdata-1.0.0/examples/youtube_download.py +38 -0
  67. flashdata-1.0.0/examples/youtube_metadata.py +30 -0
  68. flashdata-1.0.0/examples/youtube_search.py +31 -0
  69. flashdata-1.0.0/examples/youtube_search_extended.py +31 -0
  70. flashdata-1.0.0/examples/youtube_suggestions.py +26 -0
  71. flashdata-1.0.0/examples/youtube_trainability.py +23 -0
  72. flashdata-1.0.0/examples/youtube_transcript.py +30 -0
  73. flashdata-1.0.0/openapi.json +5063 -0
  74. flashdata-1.0.0/pyproject.toml +53 -0
  75. flashdata-1.0.0/scripts/verify_package.py +136 -0
  76. flashdata-1.0.0/setup.cfg +4 -0
  77. flashdata-1.0.0/source-contract.json +1694 -0
  78. flashdata-1.0.0/src/flashdata/__init__.py +34 -0
  79. flashdata-1.0.0/src/flashdata/_async_client.py +213 -0
  80. flashdata-1.0.0/src/flashdata/_client.py +210 -0
  81. flashdata-1.0.0/src/flashdata/_common.py +265 -0
  82. flashdata-1.0.0/src/flashdata/_resources.py +1945 -0
  83. flashdata-1.0.0/src/flashdata/_schemas.json +1096 -0
  84. flashdata-1.0.0/src/flashdata/errors.py +69 -0
  85. flashdata-1.0.0/src/flashdata/py.typed +0 -0
  86. flashdata-1.0.0/src/flashdata/types.py +1016 -0
  87. flashdata-1.0.0/src/flashdata.egg-info/PKG-INFO +315 -0
  88. flashdata-1.0.0/src/flashdata.egg-info/SOURCES.txt +97 -0
  89. flashdata-1.0.0/src/flashdata.egg-info/dependency_links.txt +1 -0
  90. flashdata-1.0.0/src/flashdata.egg-info/requires.txt +19 -0
  91. flashdata-1.0.0/src/flashdata.egg-info/top_level.txt +1 -0
  92. flashdata-1.0.0/tests/conftest.py +135 -0
  93. flashdata-1.0.0/tests/fixtures/source-examples.json +647 -0
  94. flashdata-1.0.0/tests/test_examples_and_docs.py +146 -0
  95. flashdata-1.0.0/tests/test_http_integration.py +107 -0
  96. flashdata-1.0.0/tests/test_live.py +94 -0
  97. flashdata-1.0.0/tests/test_regressions.py +259 -0
  98. flashdata-1.0.0/tests/test_sdk.py +395 -0
  99. flashdata-1.0.0/tests/test_workflow_parity.py +139 -0
@@ -0,0 +1,13 @@
1
+ version: 2
2
+ build:
3
+ os: ubuntu-24.04
4
+ tools:
5
+ python: "3.12"
6
+ sphinx:
7
+ configuration: docs/conf.py
8
+ fail_on_warning: true
9
+ python:
10
+ install:
11
+ - method: pip
12
+ path: .
13
+ extra_requirements: [docs]
@@ -0,0 +1,33 @@
1
+ # Changelog
2
+
3
+ [FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
4
+
5
+ Final local release check: verified Python 3.10/3.12, rejected API-key control characters
6
+ before transport creation, required explicit live-test opt-in, and checked dynamic
7
+ distribution versions and packaged English/Chinese README contents.
8
+
9
+ Cross-SDK review: aligned request/bulk typing and stored-result envelopes, added public
10
+ discovery and bulk download CLIs, saved bulk job records, preserved concurrent partial
11
+ results, validated waiting arguments before submission, fixed initial cursor loops,
12
+ added package-consumer verification, and linked every guide to official FlashData pages.
13
+
14
+ ## 1.0.0 — local release candidate
15
+
16
+ - Document explicit `api_key=os.getenv("FLASHDATA_API_KEY")` initialization consistently
17
+ across the README, guides, and authenticated CLI examples.
18
+ - Reworked the README and all source guides around executable tasks and actual response fields.
19
+ - Added a Sphinx documentation site, CLI inputs, JSON/CSV/NDJSON exports, and resumable workflows.
20
+ - Added per-request timeouts, proxy/TLS configuration, unauthenticated public discovery,
21
+ cached authenticated storage origins, bounded bulk listing and all-part row iteration.
22
+ - Fixed malformed callback/URL validation, runtime required-key typing, structured error
23
+ attributes, corrupt gzip handling, unexpected job envelopes, and polling deadline recovery.
24
+ - Added executable documentation tests, example integration checks, and opt-in paid live tests.
25
+
26
+ - All 15 Google and YouTube sources, source validation and typed requests.
27
+ - Realtime queries, background submissions, mixed batches and bounded Google pagination.
28
+ - Job readers, signed results and explicit bounded polling.
29
+ - Bulk create, streaming file upload, start, pause, resume, update, cancel, progress, manifest and gzip NDJSON parts.
30
+ - Account access, balance, pricing, limits, usage and public discovery.
31
+ - Documentation, runnable examples, offline tests, packaging and CI configuration.
32
+
33
+ GitHub and package-registry publication have not been performed.
@@ -0,0 +1,53 @@
1
+ # Contributing
2
+
3
+ [FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
4
+
5
+ Use a branch for changes and keep API examples runnable from a source checkout. Never
6
+ commit API keys, storage credentials, signed result URLs or customer data.
7
+
8
+ ## Local setup
9
+
10
+ ```sh
11
+ python -m venv .venv
12
+ # Activate .venv, then:
13
+ python -m pip install -e '.[dev,docs]'
14
+ python -m pytest
15
+ python -m ruff check src tests examples scripts docs/conf.py
16
+ python -m ruff format --check src tests examples scripts docs/conf.py
17
+ python -m mypy src/flashdata
18
+ python -m sphinx -n -W --keep-going -b html docs docs/_build/html
19
+ python -m build
20
+ python scripts/verify_package.py
21
+ python examples/offline.py
22
+ ```
23
+
24
+ Default tests use HTTPX mock transports and loopback HTTP servers. The async suite
25
+ requires a runtime that can initialize local asyncio sockets. A restricted Windows
26
+ sandbox may block event-loop initialization even without external network access.
27
+
28
+ The normal suite never submits paid production requests. It executes every documentation
29
+ Python block and every example with source-shaped mock responses, and verifies that
30
+ imports and `--help` do no network work. Keep those tests aligned with live response shapes.
31
+
32
+ ## Live integration tests
33
+
34
+ Set both `FLASHDATA_RUN_LIVE=1` and `FLASHDATA_LIVE_API_KEY` in your process environment,
35
+ then run `python -m pytest tests/test_live.py -q`. These tests consume credits: they run
36
+ 14 realtime sources, a background query, a mixed 14-item batch, and a small metadata
37
+ bulk job. They also read account/public APIs, signed results and errors, and check the
38
+ async client. No test cancels other work. The suite needs a key with access to all sources
39
+ and sufficient plan limits.
40
+
41
+ Media download tests validate requests and storage transport offline. Successful delivery
42
+ to customer cloud storage needs separate destination credentials and is not part of this
43
+ live suite. Automatic CI does not use production keys. The manually dispatched live
44
+ workflow requires its explicit paid-call input and a repository secret.
45
+
46
+ When changing contracts, update runtime validation, exported types, source guides,
47
+ examples and fixtures together. Preserve omitted values and explicit false. Test all
48
+ affected source modes, unknown submission outcomes and API/storage credential separation.
49
+ Keep HTTP retries out of the default client. Read [architecture](docs/architecture.md)
50
+ and [API coverage](docs/api-reference.md) before adding new resources.
51
+
52
+ CI configuration is included for Linux/Windows and supported runtime versions. It has
53
+ not executed on GitHub while the repository remains local. [Release preparation](docs/release.md).
@@ -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,11 @@
1
+ include LICENSE README.md CHANGELOG.md CONTRIBUTING.md SECURITY.md openapi.json source-contract.json
2
+ include README.zh-CN.md
3
+ recursive-include docs *.md *.rst *.py *.css
4
+ recursive-include examples *.py *.txt *.md
5
+ recursive-include tests *.py *.json
6
+ recursive-include scripts *.py
7
+ recursive-include src/flashdata *.json py.typed
8
+ include .readthedocs.yaml
9
+ prune docs/_build
10
+ prune artifacts
11
+ global-exclude *.py[cod]
@@ -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).