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.
@@ -0,0 +1,1945 @@
1
+ from __future__ import annotations
2
+ import asyncio
3
+ import time
4
+ from typing import Any, Literal, overload
5
+ from typing_extensions import Unpack
6
+ from .types import (
7
+ ApiAccess,
8
+ ApiAccessBalance,
9
+ ApiAccessLimits,
10
+ ApiAccessPricing,
11
+ ApiKeyUsage,
12
+ AsyncQuery,
13
+ AsyncSubmission,
14
+ BatchResponse,
15
+ BulkJob,
16
+ BulkJobCreated,
17
+ BulkJobPage,
18
+ ConsoleJob,
19
+ CreateBulkJobRequest,
20
+ DataQueryResponse,
21
+ GoogleImagesParams,
22
+ GoogleImagesResponse,
23
+ GoogleNewsParams,
24
+ GoogleNewsResponse,
25
+ GooglePlacesParams,
26
+ GooglePlacesResponse,
27
+ GoogleSearchParams,
28
+ GoogleSearchResponse,
29
+ GoogleShoppingParams,
30
+ GoogleShoppingResponse,
31
+ GoogleVideosParams,
32
+ GoogleVideosResponse,
33
+ RealtimeQuery,
34
+ Source,
35
+ SourceCatalog,
36
+ Health,
37
+ PlanCatalog,
38
+ PublicStatus,
39
+ JobResult,
40
+ UpdateBulkJobRequest,
41
+ YoutubeCaptionsParams,
42
+ YoutubeCaptionsResponse,
43
+ YoutubeChannelParams,
44
+ YoutubeChannelResponse,
45
+ YoutubeDownloadParams,
46
+ YoutubeMetadataParams,
47
+ YoutubeMetadataResponse,
48
+ YoutubeSearchExtendedParams,
49
+ YoutubeSearchExtendedResponse,
50
+ YoutubeSearchParams,
51
+ YoutubeSearchResponse,
52
+ YoutubeSuggestionsParams,
53
+ YoutubeSuggestionsResponse,
54
+ YoutubeTrainabilityParams,
55
+ YoutubeTrainabilityResponse,
56
+ YoutubeTranscriptParams,
57
+ YoutubeTranscriptResponse,
58
+ )
59
+ from ._common import SOURCES, bulk_input, identifier, integer, positive, validate_query, result_rows, job_record
60
+ from .errors import (
61
+ JobFailedError,
62
+ JobPausedError,
63
+ PollingTimeoutError,
64
+ RequestTimeoutError,
65
+ ProtocolError,
66
+ ValidationError,
67
+ )
68
+
69
+
70
+ class Resource:
71
+ def __init__(self, client: Any):
72
+ self._client = client
73
+
74
+
75
+ class Queries(Resource):
76
+ def realtime(self, query: RealtimeQuery, *, timeout: float | None = None) -> DataQueryResponse:
77
+ return self._client._request(
78
+ "POST", "/v1/queries/realtime", data=True, body=validate_query(query), timeout=timeout
79
+ )
80
+
81
+ def submit(self, query: AsyncQuery, *, timeout: float | None = None) -> AsyncSubmission:
82
+ return self._client._request(
83
+ "POST", "/v1/queries", data=True, body=validate_query(query, async_mode=True), timeout=timeout
84
+ )
85
+
86
+ def batch(self, queries: list[AsyncQuery], *, timeout: float | None = None) -> BatchResponse:
87
+ if not isinstance(queries, list) or not queries:
88
+ raise ValidationError("Provide a non-empty list of queries; plan batch limits apply.")
89
+ return self._client._request(
90
+ "POST",
91
+ "/v1/queries/batch",
92
+ data=True,
93
+ body={"queries": [validate_query(q, async_mode=True) for q in queries]},
94
+ timeout=timeout,
95
+ )
96
+
97
+
98
+ class Account(Resource):
99
+ def access(self, *, timeout: float | None = None) -> ApiAccess:
100
+ return self._client._request("GET", "/api-access", timeout=timeout)
101
+
102
+ def balance(self, *, timeout: float | None = None) -> ApiAccessBalance:
103
+ return self._client._request("GET", "/api-access/balance", timeout=timeout)
104
+
105
+ def pricing(
106
+ self, *, source: Source | None = None, request_count: int = 1, timeout: float | None = None
107
+ ) -> ApiAccessPricing:
108
+ integer(request_count, "request_count", 1, 100000)
109
+ if source is not None and source not in SOURCES:
110
+ raise ValidationError("Unknown pricing source.")
111
+ params: dict[str, Any] = {"request_count": request_count}
112
+ if source is not None:
113
+ params["source"] = source
114
+ return self._client._request("GET", "/api-access/pricing", params=params, timeout=timeout)
115
+
116
+ def limits(self, *, timeout: float | None = None) -> ApiAccessLimits:
117
+ return self._client._request("GET", "/api-access/limits", timeout=timeout)
118
+
119
+ def usage(
120
+ self,
121
+ *,
122
+ source: Source | None = None,
123
+ from_: str | None = None,
124
+ to: str | None = None,
125
+ timeout: float | None = None,
126
+ ) -> ApiKeyUsage:
127
+ if source is not None and source not in SOURCES:
128
+ raise ValidationError("Unknown usage source.")
129
+ params = {k: v for k, v in {"source": source, "from": from_, "to": to}.items() if v is not None}
130
+ return self._client._request("GET", "/usage", params=params, timeout=timeout)
131
+
132
+
133
+ class Public(Resource):
134
+ def sources(self, *, timeout: float | None = None) -> SourceCatalog:
135
+ return self._client._request("GET", "/catalog/sources", public=True, timeout=timeout)
136
+
137
+ def plans(self, *, timeout: float | None = None) -> PlanCatalog:
138
+ return self._client._request("GET", "/plans", public=True, timeout=timeout)
139
+
140
+ def status(self, *, timeout: float | None = None) -> PublicStatus:
141
+ return self._client._request("GET", "/status", public=True, timeout=timeout)
142
+
143
+ def health(self, *, timeout: float | None = None) -> Health:
144
+ return self._client._request("GET", "/health", public=True, timeout=timeout)
145
+
146
+
147
+ class Jobs(Resource):
148
+ def get(self, job_id: str, *, timeout: float | None = None) -> ConsoleJob:
149
+ return job_record(self._client._request("GET", "/jobs/" + identifier(job_id), timeout=timeout))
150
+
151
+ def result(self, job_id: str, *, timeout: float | None = None) -> JobResult:
152
+ return self._client._result("/jobs/" + identifier(job_id) + "/results", timeout=timeout)
153
+
154
+ def wait(self, job_id: str, *, timeout: float = 300, poll_interval: float = 2) -> ConsoleJob:
155
+ """Poll an existing ID without resubmitting or canceling accepted work."""
156
+ identifier(job_id)
157
+ deadline = time.monotonic() + positive(timeout, "timeout")
158
+ positive(poll_interval, "poll_interval")
159
+ while True:
160
+ remaining = deadline - time.monotonic()
161
+ if remaining <= 0:
162
+ raise PollingTimeoutError(job_id)
163
+ try:
164
+ job = job_record(
165
+ self._client._request("GET", "/jobs/" + job_id, timeout=min(remaining, self._client.timeout))
166
+ )
167
+ except RequestTimeoutError:
168
+ if time.monotonic() >= deadline:
169
+ raise PollingTimeoutError(job_id) from None
170
+ raise
171
+ if time.monotonic() >= deadline:
172
+ raise PollingTimeoutError(job_id)
173
+ status = job.get("status")
174
+ if status == "completed":
175
+ return job
176
+ if status in ("failed",):
177
+ raise JobFailedError(job)
178
+ if status not in ("pending", "processing"):
179
+ raise ProtocolError("Unexpected job status.")
180
+ remaining = deadline - time.monotonic()
181
+ if remaining <= 0:
182
+ raise PollingTimeoutError(job_id)
183
+ time.sleep(min(poll_interval, remaining))
184
+
185
+
186
+ class Bulk(Resource):
187
+ def create(self, request: CreateBulkJobRequest, *, timeout: float | None = None) -> BulkJobCreated:
188
+ return self._client._request("POST", "/bulk-jobs", body=bulk_input(request), timeout=timeout)
189
+
190
+ def get(self, bulk_id: str, *, timeout: float | None = None) -> BulkJob:
191
+ return job_record(self._client._request("GET", "/bulk-jobs/" + identifier(bulk_id, True), timeout=timeout))
192
+
193
+ def list(self, *, cursor: str | None = None, limit: int = 20, timeout: float | None = None) -> BulkJobPage:
194
+ integer(limit, "limit", 1, 50)
195
+ params: dict[str, Any] = {"limit": limit}
196
+ if cursor is not None:
197
+ params["cursor"] = cursor
198
+ return self._client._request("GET", "/bulk-jobs", params=params, timeout=timeout)
199
+
200
+ def update(self, bulk_id: str, request: UpdateBulkJobRequest, *, timeout: float | None = None) -> BulkJob:
201
+ return job_record(
202
+ self._client._request(
203
+ "PATCH",
204
+ "/bulk-jobs/" + identifier(bulk_id, True),
205
+ body=bulk_input(request, partial=True),
206
+ timeout=timeout,
207
+ )
208
+ )
209
+
210
+ def upload_file(self, created: BulkJobCreated, path: Any, *, timeout: float | None = None) -> None:
211
+ self._client._upload(created, path, timeout=timeout)
212
+
213
+ def manifest(self, bulk_id: str, *, timeout: float | None = None) -> dict[str, Any]:
214
+ return self._client._result("/bulk-jobs/" + identifier(bulk_id, True) + "/results", timeout=timeout)
215
+
216
+ def part(self, bulk_id: str, part_number: int, *, timeout: float | None = None) -> bytes:
217
+ integer(part_number, "part_number", 0, 2**53 - 1)
218
+ return self._client._result(
219
+ "/bulk-jobs/" + identifier(bulk_id, True) + "/results/" + str(part_number), binary=True, timeout=timeout
220
+ )
221
+
222
+ def iter_rows(self, bulk_id: str, part_number: int, *, timeout: float | None = None):
223
+ """Iterate one bounded gzip/NDJSON part; decompressed lines use max_line_bytes."""
224
+ raw = self.part(bulk_id, part_number, timeout=timeout)
225
+ for row in result_rows(raw, self._client.max_response_bytes, self._client.max_line_bytes):
226
+ yield row
227
+
228
+ def wait(self, bulk_id: str, *, timeout: float = 3600, poll_interval: float = 5) -> BulkJob:
229
+ """Poll an existing ID without resubmitting or canceling accepted work."""
230
+ identifier(bulk_id, True)
231
+ deadline = time.monotonic() + positive(timeout, "timeout")
232
+ positive(poll_interval, "poll_interval")
233
+ while True:
234
+ remaining = deadline - time.monotonic()
235
+ if remaining <= 0:
236
+ raise PollingTimeoutError(bulk_id)
237
+ try:
238
+ job = job_record(
239
+ self._client._request("GET", "/bulk-jobs/" + bulk_id, timeout=min(remaining, self._client.timeout))
240
+ )
241
+ except RequestTimeoutError:
242
+ if time.monotonic() >= deadline:
243
+ raise PollingTimeoutError(bulk_id) from None
244
+ raise
245
+ if time.monotonic() >= deadline:
246
+ raise PollingTimeoutError(bulk_id)
247
+ status = job.get("status")
248
+ if status == "completed":
249
+ return job
250
+ if status == "paused":
251
+ raise JobPausedError(job)
252
+ if status in ("failed", "cancelled"):
253
+ raise JobFailedError(job)
254
+ if status not in ("awaiting_upload", "running", "finalizing"):
255
+ raise ProtocolError("Unexpected job status.")
256
+ remaining = deadline - time.monotonic()
257
+ if remaining <= 0:
258
+ raise PollingTimeoutError(bulk_id)
259
+ time.sleep(min(poll_interval, remaining))
260
+
261
+ def start(self, bulk_id: str, *, timeout: float | None = None) -> BulkJob:
262
+ return job_record(
263
+ self._client._request("POST", "/bulk-jobs/" + identifier(bulk_id, True) + "/start", timeout=timeout)
264
+ )
265
+
266
+ def pause(self, bulk_id: str, *, timeout: float | None = None) -> BulkJob:
267
+ return job_record(
268
+ self._client._request("POST", "/bulk-jobs/" + identifier(bulk_id, True) + "/pause", timeout=timeout)
269
+ )
270
+
271
+ def resume(self, bulk_id: str, *, timeout: float | None = None) -> BulkJob:
272
+ return job_record(
273
+ self._client._request("POST", "/bulk-jobs/" + identifier(bulk_id, True) + "/resume", timeout=timeout)
274
+ )
275
+
276
+ def cancel(self, bulk_id: str, *, timeout: float | None = None) -> BulkJob:
277
+ return job_record(
278
+ self._client._request("DELETE", "/bulk-jobs/" + identifier(bulk_id, True) + "", timeout=timeout)
279
+ )
280
+
281
+ def rows(self, bulk_id: str, *, timeout: float | None = None):
282
+ """Yield all result rows in manifest order, buffering one bounded part."""
283
+ manifest = self.manifest(bulk_id, timeout=timeout)
284
+ parts = manifest.get("parts")
285
+ if not isinstance(parts, list):
286
+ raise ProtocolError("Bulk manifest is missing its parts list.")
287
+ seen = set()
288
+ for part in parts:
289
+ if (
290
+ not isinstance(part, dict)
291
+ or type(part.get("number")) is not int
292
+ or part["number"] < 0
293
+ or part["number"] in seen
294
+ ):
295
+ raise ProtocolError("Invalid or duplicate bulk part number.")
296
+ seen.add(part["number"])
297
+ for row in self.iter_rows(bulk_id, part["number"], timeout=timeout):
298
+ yield row
299
+
300
+ def iter_jobs(self, *, max_pages: int, limit: int = 20, cursor: str | None = None, timeout: float | None = None):
301
+ """Yield bulk job records from a bounded number of cursor pages."""
302
+ integer(max_pages, "max_pages", 1, 1000)
303
+ seen = {cursor} if cursor else set()
304
+ for _ in range(max_pages):
305
+ page = self.list(limit=limit, cursor=cursor, timeout=timeout)
306
+ if not isinstance(page.get("data"), list) or not isinstance(page.get("pagination"), dict):
307
+ raise ProtocolError("Invalid bulk listing response.")
308
+ for job in page["data"]:
309
+ if not isinstance(job, dict):
310
+ raise ProtocolError("Expected a bulk job object.")
311
+ yield job
312
+ pagination = page["pagination"]
313
+ if not pagination.get("hasMore"):
314
+ return
315
+ cursor = pagination.get("nextCursor")
316
+ if not isinstance(cursor, str) or not cursor or cursor in seen:
317
+ raise ProtocolError("Bulk listing returned an invalid or repeated cursor.")
318
+ seen.add(cursor)
319
+
320
+
321
+ class Google(Resource):
322
+ @overload
323
+ def search(
324
+ self,
325
+ query: str,
326
+ *,
327
+ mode: Literal["realtime"] = "realtime",
328
+ callback_url: None = None,
329
+ timeout: float | None = None,
330
+ **params: Unpack[GoogleSearchParams],
331
+ ) -> GoogleSearchResponse: ...
332
+ @overload
333
+ def search(
334
+ self,
335
+ query: str,
336
+ *,
337
+ mode: Literal["async"],
338
+ callback_url: str | None = None,
339
+ timeout: float | None = None,
340
+ **params: Unpack[GoogleSearchParams],
341
+ ) -> AsyncSubmission: ...
342
+ def search(
343
+ self,
344
+ query: str,
345
+ *,
346
+ mode: Literal["realtime", "async"] = "realtime",
347
+ callback_url: str | None = None,
348
+ timeout: float | None = None,
349
+ **params: Unpack[GoogleSearchParams],
350
+ ) -> Any:
351
+ """google_search: https://flashdata.dev/docs/sources/google_search"""
352
+ if mode not in ("realtime", "async"):
353
+ raise ValidationError("mode must be realtime or async.")
354
+ if mode == "realtime" and callback_url is not None:
355
+ raise ValidationError("Callbacks apply only to background queries.")
356
+ payload: Any = {"source": "google_search", "query": query}
357
+ if params:
358
+ payload["params"] = params
359
+ if callback_url is not None:
360
+ payload["callback_url"] = callback_url
361
+ return (
362
+ self._client.queries.submit(payload, timeout=timeout)
363
+ if mode == "async"
364
+ else self._client.queries.realtime(payload, timeout=timeout)
365
+ )
366
+
367
+ @overload
368
+ def images(
369
+ self,
370
+ query: str,
371
+ *,
372
+ mode: Literal["realtime"] = "realtime",
373
+ callback_url: None = None,
374
+ timeout: float | None = None,
375
+ **params: Unpack[GoogleImagesParams],
376
+ ) -> GoogleImagesResponse: ...
377
+ @overload
378
+ def images(
379
+ self,
380
+ query: str,
381
+ *,
382
+ mode: Literal["async"],
383
+ callback_url: str | None = None,
384
+ timeout: float | None = None,
385
+ **params: Unpack[GoogleImagesParams],
386
+ ) -> AsyncSubmission: ...
387
+ def images(
388
+ self,
389
+ query: str,
390
+ *,
391
+ mode: Literal["realtime", "async"] = "realtime",
392
+ callback_url: str | None = None,
393
+ timeout: float | None = None,
394
+ **params: Unpack[GoogleImagesParams],
395
+ ) -> Any:
396
+ """google_images: https://flashdata.dev/docs/sources/google_images"""
397
+ if mode not in ("realtime", "async"):
398
+ raise ValidationError("mode must be realtime or async.")
399
+ if mode == "realtime" and callback_url is not None:
400
+ raise ValidationError("Callbacks apply only to background queries.")
401
+ payload: Any = {"source": "google_images", "query": query}
402
+ if params:
403
+ payload["params"] = params
404
+ if callback_url is not None:
405
+ payload["callback_url"] = callback_url
406
+ return (
407
+ self._client.queries.submit(payload, timeout=timeout)
408
+ if mode == "async"
409
+ else self._client.queries.realtime(payload, timeout=timeout)
410
+ )
411
+
412
+ @overload
413
+ def news(
414
+ self,
415
+ query: str,
416
+ *,
417
+ mode: Literal["realtime"] = "realtime",
418
+ callback_url: None = None,
419
+ timeout: float | None = None,
420
+ **params: Unpack[GoogleNewsParams],
421
+ ) -> GoogleNewsResponse: ...
422
+ @overload
423
+ def news(
424
+ self,
425
+ query: str,
426
+ *,
427
+ mode: Literal["async"],
428
+ callback_url: str | None = None,
429
+ timeout: float | None = None,
430
+ **params: Unpack[GoogleNewsParams],
431
+ ) -> AsyncSubmission: ...
432
+ def news(
433
+ self,
434
+ query: str,
435
+ *,
436
+ mode: Literal["realtime", "async"] = "realtime",
437
+ callback_url: str | None = None,
438
+ timeout: float | None = None,
439
+ **params: Unpack[GoogleNewsParams],
440
+ ) -> Any:
441
+ """google_news: https://flashdata.dev/docs/sources/google_news"""
442
+ if mode not in ("realtime", "async"):
443
+ raise ValidationError("mode must be realtime or async.")
444
+ if mode == "realtime" and callback_url is not None:
445
+ raise ValidationError("Callbacks apply only to background queries.")
446
+ payload: Any = {"source": "google_news", "query": query}
447
+ if params:
448
+ payload["params"] = params
449
+ if callback_url is not None:
450
+ payload["callback_url"] = callback_url
451
+ return (
452
+ self._client.queries.submit(payload, timeout=timeout)
453
+ if mode == "async"
454
+ else self._client.queries.realtime(payload, timeout=timeout)
455
+ )
456
+
457
+ @overload
458
+ def shopping(
459
+ self,
460
+ query: str,
461
+ *,
462
+ mode: Literal["realtime"] = "realtime",
463
+ callback_url: None = None,
464
+ timeout: float | None = None,
465
+ **params: Unpack[GoogleShoppingParams],
466
+ ) -> GoogleShoppingResponse: ...
467
+ @overload
468
+ def shopping(
469
+ self,
470
+ query: str,
471
+ *,
472
+ mode: Literal["async"],
473
+ callback_url: str | None = None,
474
+ timeout: float | None = None,
475
+ **params: Unpack[GoogleShoppingParams],
476
+ ) -> AsyncSubmission: ...
477
+ def shopping(
478
+ self,
479
+ query: str,
480
+ *,
481
+ mode: Literal["realtime", "async"] = "realtime",
482
+ callback_url: str | None = None,
483
+ timeout: float | None = None,
484
+ **params: Unpack[GoogleShoppingParams],
485
+ ) -> Any:
486
+ """google_shopping: https://flashdata.dev/docs/sources/google_shopping"""
487
+ if mode not in ("realtime", "async"):
488
+ raise ValidationError("mode must be realtime or async.")
489
+ if mode == "realtime" and callback_url is not None:
490
+ raise ValidationError("Callbacks apply only to background queries.")
491
+ payload: Any = {"source": "google_shopping", "query": query}
492
+ if params:
493
+ payload["params"] = params
494
+ if callback_url is not None:
495
+ payload["callback_url"] = callback_url
496
+ return (
497
+ self._client.queries.submit(payload, timeout=timeout)
498
+ if mode == "async"
499
+ else self._client.queries.realtime(payload, timeout=timeout)
500
+ )
501
+
502
+ @overload
503
+ def videos(
504
+ self,
505
+ query: str,
506
+ *,
507
+ mode: Literal["realtime"] = "realtime",
508
+ callback_url: None = None,
509
+ timeout: float | None = None,
510
+ **params: Unpack[GoogleVideosParams],
511
+ ) -> GoogleVideosResponse: ...
512
+ @overload
513
+ def videos(
514
+ self,
515
+ query: str,
516
+ *,
517
+ mode: Literal["async"],
518
+ callback_url: str | None = None,
519
+ timeout: float | None = None,
520
+ **params: Unpack[GoogleVideosParams],
521
+ ) -> AsyncSubmission: ...
522
+ def videos(
523
+ self,
524
+ query: str,
525
+ *,
526
+ mode: Literal["realtime", "async"] = "realtime",
527
+ callback_url: str | None = None,
528
+ timeout: float | None = None,
529
+ **params: Unpack[GoogleVideosParams],
530
+ ) -> Any:
531
+ """google_videos: https://flashdata.dev/docs/sources/google_videos"""
532
+ if mode not in ("realtime", "async"):
533
+ raise ValidationError("mode must be realtime or async.")
534
+ if mode == "realtime" and callback_url is not None:
535
+ raise ValidationError("Callbacks apply only to background queries.")
536
+ payload: Any = {"source": "google_videos", "query": query}
537
+ if params:
538
+ payload["params"] = params
539
+ if callback_url is not None:
540
+ payload["callback_url"] = callback_url
541
+ return (
542
+ self._client.queries.submit(payload, timeout=timeout)
543
+ if mode == "async"
544
+ else self._client.queries.realtime(payload, timeout=timeout)
545
+ )
546
+
547
+ @overload
548
+ def places(
549
+ self,
550
+ query: str,
551
+ *,
552
+ mode: Literal["realtime"] = "realtime",
553
+ callback_url: None = None,
554
+ timeout: float | None = None,
555
+ **params: Unpack[GooglePlacesParams],
556
+ ) -> GooglePlacesResponse: ...
557
+ @overload
558
+ def places(
559
+ self,
560
+ query: str,
561
+ *,
562
+ mode: Literal["async"],
563
+ callback_url: str | None = None,
564
+ timeout: float | None = None,
565
+ **params: Unpack[GooglePlacesParams],
566
+ ) -> AsyncSubmission: ...
567
+ def places(
568
+ self,
569
+ query: str,
570
+ *,
571
+ mode: Literal["realtime", "async"] = "realtime",
572
+ callback_url: str | None = None,
573
+ timeout: float | None = None,
574
+ **params: Unpack[GooglePlacesParams],
575
+ ) -> Any:
576
+ """google_places: https://flashdata.dev/docs/sources/google_places"""
577
+ if mode not in ("realtime", "async"):
578
+ raise ValidationError("mode must be realtime or async.")
579
+ if mode == "realtime" and callback_url is not None:
580
+ raise ValidationError("Callbacks apply only to background queries.")
581
+ payload: Any = {"source": "google_places", "query": query}
582
+ if params:
583
+ payload["params"] = params
584
+ if callback_url is not None:
585
+ payload["callback_url"] = callback_url
586
+ return (
587
+ self._client.queries.submit(payload, timeout=timeout)
588
+ if mode == "async"
589
+ else self._client.queries.realtime(payload, timeout=timeout)
590
+ )
591
+
592
+ def pages(
593
+ self,
594
+ source: Source,
595
+ query: str,
596
+ *,
597
+ max_pages: int,
598
+ start_page: int = 1,
599
+ timeout: float | None = None,
600
+ **params: Any,
601
+ ):
602
+ """Fetch at most max_pages paid Google pages, stopping on an empty result list."""
603
+ keys = {
604
+ "google_search": "organic",
605
+ "google_images": "images",
606
+ "google_news": "news",
607
+ "google_shopping": "shopping",
608
+ "google_videos": "videos",
609
+ "google_places": "places",
610
+ }
611
+ if not isinstance(source, str) or source not in keys or "page" in params:
612
+ raise ValidationError("Choose a Google source and use start_page for pagination.")
613
+ integer(max_pages, "max_pages", 1, 100)
614
+ integer(start_page, "start_page", 1, 100)
615
+ if start_page + max_pages > 101:
616
+ raise ValidationError("Requested pagination exceeds page 100.")
617
+ for page in range(start_page, start_page + max_pages):
618
+ payload: Any = {"source": source, "query": query, "params": {**params, "page": page}}
619
+ response = self._client.queries.realtime(payload, timeout=timeout)
620
+ yield response
621
+ if not any(isinstance(item, dict) and item.get(keys[source]) for item in response.get("results", [])):
622
+ break
623
+
624
+
625
+ class YouTube(Resource):
626
+ @overload
627
+ def search(
628
+ self,
629
+ query: str,
630
+ *,
631
+ mode: Literal["realtime"] = "realtime",
632
+ callback_url: None = None,
633
+ timeout: float | None = None,
634
+ **params: Unpack[YoutubeSearchParams],
635
+ ) -> YoutubeSearchResponse: ...
636
+ @overload
637
+ def search(
638
+ self,
639
+ query: str,
640
+ *,
641
+ mode: Literal["async"],
642
+ callback_url: str | None = None,
643
+ timeout: float | None = None,
644
+ **params: Unpack[YoutubeSearchParams],
645
+ ) -> AsyncSubmission: ...
646
+ def search(
647
+ self,
648
+ query: str,
649
+ *,
650
+ mode: Literal["realtime", "async"] = "realtime",
651
+ callback_url: str | None = None,
652
+ timeout: float | None = None,
653
+ **params: Unpack[YoutubeSearchParams],
654
+ ) -> Any:
655
+ """youtube_search: https://flashdata.dev/docs/sources/youtube_search"""
656
+ if mode not in ("realtime", "async"):
657
+ raise ValidationError("mode must be realtime or async.")
658
+ if mode == "realtime" and callback_url is not None:
659
+ raise ValidationError("Callbacks apply only to background queries.")
660
+ payload: Any = {"source": "youtube_search", "query": query}
661
+ if params:
662
+ payload["params"] = params
663
+ if callback_url is not None:
664
+ payload["callback_url"] = callback_url
665
+ return (
666
+ self._client.queries.submit(payload, timeout=timeout)
667
+ if mode == "async"
668
+ else self._client.queries.realtime(payload, timeout=timeout)
669
+ )
670
+
671
+ @overload
672
+ def search_extended(
673
+ self,
674
+ query: str,
675
+ *,
676
+ mode: Literal["realtime"] = "realtime",
677
+ callback_url: None = None,
678
+ timeout: float | None = None,
679
+ **params: Unpack[YoutubeSearchExtendedParams],
680
+ ) -> YoutubeSearchExtendedResponse: ...
681
+ @overload
682
+ def search_extended(
683
+ self,
684
+ query: str,
685
+ *,
686
+ mode: Literal["async"],
687
+ callback_url: str | None = None,
688
+ timeout: float | None = None,
689
+ **params: Unpack[YoutubeSearchExtendedParams],
690
+ ) -> AsyncSubmission: ...
691
+ def search_extended(
692
+ self,
693
+ query: str,
694
+ *,
695
+ mode: Literal["realtime", "async"] = "realtime",
696
+ callback_url: str | None = None,
697
+ timeout: float | None = None,
698
+ **params: Unpack[YoutubeSearchExtendedParams],
699
+ ) -> Any:
700
+ """youtube_search_extended: https://flashdata.dev/docs/sources/youtube_search_extended"""
701
+ if mode not in ("realtime", "async"):
702
+ raise ValidationError("mode must be realtime or async.")
703
+ if mode == "realtime" and callback_url is not None:
704
+ raise ValidationError("Callbacks apply only to background queries.")
705
+ payload: Any = {"source": "youtube_search_extended", "query": query}
706
+ if params:
707
+ payload["params"] = params
708
+ if callback_url is not None:
709
+ payload["callback_url"] = callback_url
710
+ return (
711
+ self._client.queries.submit(payload, timeout=timeout)
712
+ if mode == "async"
713
+ else self._client.queries.realtime(payload, timeout=timeout)
714
+ )
715
+
716
+ @overload
717
+ def metadata(
718
+ self,
719
+ video_id: str,
720
+ *,
721
+ mode: Literal["realtime"] = "realtime",
722
+ callback_url: None = None,
723
+ timeout: float | None = None,
724
+ **params: Unpack[YoutubeMetadataParams],
725
+ ) -> YoutubeMetadataResponse: ...
726
+ @overload
727
+ def metadata(
728
+ self,
729
+ video_id: str,
730
+ *,
731
+ mode: Literal["async"],
732
+ callback_url: str | None = None,
733
+ timeout: float | None = None,
734
+ **params: Unpack[YoutubeMetadataParams],
735
+ ) -> AsyncSubmission: ...
736
+ def metadata(
737
+ self,
738
+ video_id: str,
739
+ *,
740
+ mode: Literal["realtime", "async"] = "realtime",
741
+ callback_url: str | None = None,
742
+ timeout: float | None = None,
743
+ **params: Unpack[YoutubeMetadataParams],
744
+ ) -> Any:
745
+ """youtube_metadata: https://flashdata.dev/docs/sources/youtube_metadata"""
746
+ if mode not in ("realtime", "async"):
747
+ raise ValidationError("mode must be realtime or async.")
748
+ if mode == "realtime" and callback_url is not None:
749
+ raise ValidationError("Callbacks apply only to background queries.")
750
+ payload: Any = {"source": "youtube_metadata", "video_id": video_id}
751
+ if params:
752
+ payload["params"] = params
753
+ if callback_url is not None:
754
+ payload["callback_url"] = callback_url
755
+ return (
756
+ self._client.queries.submit(payload, timeout=timeout)
757
+ if mode == "async"
758
+ else self._client.queries.realtime(payload, timeout=timeout)
759
+ )
760
+
761
+ @overload
762
+ def transcript(
763
+ self,
764
+ video_id: str,
765
+ *,
766
+ mode: Literal["realtime"] = "realtime",
767
+ callback_url: None = None,
768
+ timeout: float | None = None,
769
+ **params: Unpack[YoutubeTranscriptParams],
770
+ ) -> YoutubeTranscriptResponse: ...
771
+ @overload
772
+ def transcript(
773
+ self,
774
+ video_id: str,
775
+ *,
776
+ mode: Literal["async"],
777
+ callback_url: str | None = None,
778
+ timeout: float | None = None,
779
+ **params: Unpack[YoutubeTranscriptParams],
780
+ ) -> AsyncSubmission: ...
781
+ def transcript(
782
+ self,
783
+ video_id: str,
784
+ *,
785
+ mode: Literal["realtime", "async"] = "realtime",
786
+ callback_url: str | None = None,
787
+ timeout: float | None = None,
788
+ **params: Unpack[YoutubeTranscriptParams],
789
+ ) -> Any:
790
+ """youtube_transcript: https://flashdata.dev/docs/sources/youtube_transcript"""
791
+ if mode not in ("realtime", "async"):
792
+ raise ValidationError("mode must be realtime or async.")
793
+ if mode == "realtime" and callback_url is not None:
794
+ raise ValidationError("Callbacks apply only to background queries.")
795
+ payload: Any = {"source": "youtube_transcript", "video_id": video_id}
796
+ if params:
797
+ payload["params"] = params
798
+ if callback_url is not None:
799
+ payload["callback_url"] = callback_url
800
+ return (
801
+ self._client.queries.submit(payload, timeout=timeout)
802
+ if mode == "async"
803
+ else self._client.queries.realtime(payload, timeout=timeout)
804
+ )
805
+
806
+ @overload
807
+ def captions(
808
+ self,
809
+ video_id: str,
810
+ *,
811
+ mode: Literal["realtime"] = "realtime",
812
+ callback_url: None = None,
813
+ timeout: float | None = None,
814
+ **params: Unpack[YoutubeCaptionsParams],
815
+ ) -> YoutubeCaptionsResponse: ...
816
+ @overload
817
+ def captions(
818
+ self,
819
+ video_id: str,
820
+ *,
821
+ mode: Literal["async"],
822
+ callback_url: str | None = None,
823
+ timeout: float | None = None,
824
+ **params: Unpack[YoutubeCaptionsParams],
825
+ ) -> AsyncSubmission: ...
826
+ def captions(
827
+ self,
828
+ video_id: str,
829
+ *,
830
+ mode: Literal["realtime", "async"] = "realtime",
831
+ callback_url: str | None = None,
832
+ timeout: float | None = None,
833
+ **params: Unpack[YoutubeCaptionsParams],
834
+ ) -> Any:
835
+ """youtube_captions: https://flashdata.dev/docs/sources/youtube_captions"""
836
+ if mode not in ("realtime", "async"):
837
+ raise ValidationError("mode must be realtime or async.")
838
+ if mode == "realtime" and callback_url is not None:
839
+ raise ValidationError("Callbacks apply only to background queries.")
840
+ payload: Any = {"source": "youtube_captions", "video_id": video_id}
841
+ if params:
842
+ payload["params"] = params
843
+ if callback_url is not None:
844
+ payload["callback_url"] = callback_url
845
+ return (
846
+ self._client.queries.submit(payload, timeout=timeout)
847
+ if mode == "async"
848
+ else self._client.queries.realtime(payload, timeout=timeout)
849
+ )
850
+
851
+ @overload
852
+ def license_check(
853
+ self,
854
+ video_id: str,
855
+ *,
856
+ mode: Literal["realtime"] = "realtime",
857
+ callback_url: None = None,
858
+ timeout: float | None = None,
859
+ **params: Unpack[YoutubeTrainabilityParams],
860
+ ) -> YoutubeTrainabilityResponse: ...
861
+ @overload
862
+ def license_check(
863
+ self,
864
+ video_id: str,
865
+ *,
866
+ mode: Literal["async"],
867
+ callback_url: str | None = None,
868
+ timeout: float | None = None,
869
+ **params: Unpack[YoutubeTrainabilityParams],
870
+ ) -> AsyncSubmission: ...
871
+ def license_check(
872
+ self,
873
+ video_id: str,
874
+ *,
875
+ mode: Literal["realtime", "async"] = "realtime",
876
+ callback_url: str | None = None,
877
+ timeout: float | None = None,
878
+ **params: Unpack[YoutubeTrainabilityParams],
879
+ ) -> Any:
880
+ """youtube_trainability: https://flashdata.dev/docs/sources/youtube_trainability"""
881
+ if mode not in ("realtime", "async"):
882
+ raise ValidationError("mode must be realtime or async.")
883
+ if mode == "realtime" and callback_url is not None:
884
+ raise ValidationError("Callbacks apply only to background queries.")
885
+ payload: Any = {"source": "youtube_trainability", "video_id": video_id}
886
+ if params:
887
+ payload["params"] = params
888
+ if callback_url is not None:
889
+ payload["callback_url"] = callback_url
890
+ return (
891
+ self._client.queries.submit(payload, timeout=timeout)
892
+ if mode == "async"
893
+ else self._client.queries.realtime(payload, timeout=timeout)
894
+ )
895
+
896
+ @overload
897
+ def channel(
898
+ self,
899
+ handle: str,
900
+ *,
901
+ mode: Literal["realtime"] = "realtime",
902
+ callback_url: None = None,
903
+ timeout: float | None = None,
904
+ **params: Unpack[YoutubeChannelParams],
905
+ ) -> YoutubeChannelResponse: ...
906
+ @overload
907
+ def channel(
908
+ self,
909
+ handle: str,
910
+ *,
911
+ mode: Literal["async"],
912
+ callback_url: str | None = None,
913
+ timeout: float | None = None,
914
+ **params: Unpack[YoutubeChannelParams],
915
+ ) -> AsyncSubmission: ...
916
+ def channel(
917
+ self,
918
+ handle: str,
919
+ *,
920
+ mode: Literal["realtime", "async"] = "realtime",
921
+ callback_url: str | None = None,
922
+ timeout: float | None = None,
923
+ **params: Unpack[YoutubeChannelParams],
924
+ ) -> Any:
925
+ """youtube_channel: https://flashdata.dev/docs/sources/youtube_channel"""
926
+ if mode not in ("realtime", "async"):
927
+ raise ValidationError("mode must be realtime or async.")
928
+ if mode == "realtime" and callback_url is not None:
929
+ raise ValidationError("Callbacks apply only to background queries.")
930
+ payload: Any = {"source": "youtube_channel", "handle": handle}
931
+ if params:
932
+ payload["params"] = params
933
+ if callback_url is not None:
934
+ payload["callback_url"] = callback_url
935
+ return (
936
+ self._client.queries.submit(payload, timeout=timeout)
937
+ if mode == "async"
938
+ else self._client.queries.realtime(payload, timeout=timeout)
939
+ )
940
+
941
+ @overload
942
+ def suggestions(
943
+ self,
944
+ query: str,
945
+ *,
946
+ mode: Literal["realtime"] = "realtime",
947
+ callback_url: None = None,
948
+ timeout: float | None = None,
949
+ **params: Unpack[YoutubeSuggestionsParams],
950
+ ) -> YoutubeSuggestionsResponse: ...
951
+ @overload
952
+ def suggestions(
953
+ self,
954
+ query: str,
955
+ *,
956
+ mode: Literal["async"],
957
+ callback_url: str | None = None,
958
+ timeout: float | None = None,
959
+ **params: Unpack[YoutubeSuggestionsParams],
960
+ ) -> AsyncSubmission: ...
961
+ def suggestions(
962
+ self,
963
+ query: str,
964
+ *,
965
+ mode: Literal["realtime", "async"] = "realtime",
966
+ callback_url: str | None = None,
967
+ timeout: float | None = None,
968
+ **params: Unpack[YoutubeSuggestionsParams],
969
+ ) -> Any:
970
+ """youtube_suggestions: https://flashdata.dev/docs/sources/youtube_suggestions"""
971
+ if mode not in ("realtime", "async"):
972
+ raise ValidationError("mode must be realtime or async.")
973
+ if mode == "realtime" and callback_url is not None:
974
+ raise ValidationError("Callbacks apply only to background queries.")
975
+ payload: Any = {"source": "youtube_suggestions", "query": query}
976
+ if params:
977
+ payload["params"] = params
978
+ if callback_url is not None:
979
+ payload["callback_url"] = callback_url
980
+ return (
981
+ self._client.queries.submit(payload, timeout=timeout)
982
+ if mode == "async"
983
+ else self._client.queries.realtime(payload, timeout=timeout)
984
+ )
985
+
986
+ def download(
987
+ self,
988
+ video_id: str,
989
+ *,
990
+ mode: Literal["async"] = "async",
991
+ callback_url: str | None = None,
992
+ timeout: float | None = None,
993
+ **params: Unpack[YoutubeDownloadParams],
994
+ ) -> AsyncSubmission:
995
+ """Submit cloud media delivery. Downloads always run in the background."""
996
+ if mode != "async":
997
+ raise ValidationError("Downloads support mode=async only.")
998
+ payload: Any = {"source": "youtube_download", "video_id": video_id}
999
+ if params:
1000
+ payload["params"] = params
1001
+ if callback_url is not None:
1002
+ payload["callback_url"] = callback_url
1003
+ return self._client.queries.submit(payload, timeout=timeout)
1004
+
1005
+
1006
+ class AsyncResource:
1007
+ def __init__(self, client: Any):
1008
+ self._client = client
1009
+
1010
+
1011
+ class AsyncQueries(AsyncResource):
1012
+ async def realtime(self, query: RealtimeQuery, *, timeout: float | None = None) -> DataQueryResponse:
1013
+ return await self._client._request(
1014
+ "POST", "/v1/queries/realtime", data=True, body=validate_query(query), timeout=timeout
1015
+ )
1016
+
1017
+ async def submit(self, query: AsyncQuery, *, timeout: float | None = None) -> AsyncSubmission:
1018
+ return await self._client._request(
1019
+ "POST", "/v1/queries", data=True, body=validate_query(query, async_mode=True), timeout=timeout
1020
+ )
1021
+
1022
+ async def batch(self, queries: list[AsyncQuery], *, timeout: float | None = None) -> BatchResponse:
1023
+ if not isinstance(queries, list) or not queries:
1024
+ raise ValidationError("Provide a non-empty list of queries; plan batch limits apply.")
1025
+ return await self._client._request(
1026
+ "POST",
1027
+ "/v1/queries/batch",
1028
+ data=True,
1029
+ body={"queries": [validate_query(q, async_mode=True) for q in queries]},
1030
+ timeout=timeout,
1031
+ )
1032
+
1033
+
1034
+ class AsyncAccount(AsyncResource):
1035
+ async def access(self, *, timeout: float | None = None) -> ApiAccess:
1036
+ return await self._client._request("GET", "/api-access", timeout=timeout)
1037
+
1038
+ async def balance(self, *, timeout: float | None = None) -> ApiAccessBalance:
1039
+ return await self._client._request("GET", "/api-access/balance", timeout=timeout)
1040
+
1041
+ async def pricing(
1042
+ self, *, source: Source | None = None, request_count: int = 1, timeout: float | None = None
1043
+ ) -> ApiAccessPricing:
1044
+ integer(request_count, "request_count", 1, 100000)
1045
+ if source is not None and source not in SOURCES:
1046
+ raise ValidationError("Unknown pricing source.")
1047
+ params: dict[str, Any] = {"request_count": request_count}
1048
+ if source is not None:
1049
+ params["source"] = source
1050
+ return await self._client._request("GET", "/api-access/pricing", params=params, timeout=timeout)
1051
+
1052
+ async def limits(self, *, timeout: float | None = None) -> ApiAccessLimits:
1053
+ return await self._client._request("GET", "/api-access/limits", timeout=timeout)
1054
+
1055
+ async def usage(
1056
+ self,
1057
+ *,
1058
+ source: Source | None = None,
1059
+ from_: str | None = None,
1060
+ to: str | None = None,
1061
+ timeout: float | None = None,
1062
+ ) -> ApiKeyUsage:
1063
+ if source is not None and source not in SOURCES:
1064
+ raise ValidationError("Unknown usage source.")
1065
+ params = {k: v for k, v in {"source": source, "from": from_, "to": to}.items() if v is not None}
1066
+ return await self._client._request("GET", "/usage", params=params, timeout=timeout)
1067
+
1068
+
1069
+ class AsyncPublic(AsyncResource):
1070
+ async def sources(self, *, timeout: float | None = None) -> SourceCatalog:
1071
+ return await self._client._request("GET", "/catalog/sources", public=True, timeout=timeout)
1072
+
1073
+ async def plans(self, *, timeout: float | None = None) -> PlanCatalog:
1074
+ return await self._client._request("GET", "/plans", public=True, timeout=timeout)
1075
+
1076
+ async def status(self, *, timeout: float | None = None) -> PublicStatus:
1077
+ return await self._client._request("GET", "/status", public=True, timeout=timeout)
1078
+
1079
+ async def health(self, *, timeout: float | None = None) -> Health:
1080
+ return await self._client._request("GET", "/health", public=True, timeout=timeout)
1081
+
1082
+
1083
+ class AsyncJobs(AsyncResource):
1084
+ async def get(self, job_id: str, *, timeout: float | None = None) -> ConsoleJob:
1085
+ return job_record(await self._client._request("GET", "/jobs/" + identifier(job_id), timeout=timeout))
1086
+
1087
+ async def result(self, job_id: str, *, timeout: float | None = None) -> JobResult:
1088
+ return await self._client._result("/jobs/" + identifier(job_id) + "/results", timeout=timeout)
1089
+
1090
+ async def wait(self, job_id: str, *, timeout: float = 300, poll_interval: float = 2) -> ConsoleJob:
1091
+ """Poll an existing ID without resubmitting or canceling accepted work."""
1092
+ identifier(job_id)
1093
+ deadline = time.monotonic() + positive(timeout, "timeout")
1094
+ positive(poll_interval, "poll_interval")
1095
+ while True:
1096
+ remaining = deadline - time.monotonic()
1097
+ if remaining <= 0:
1098
+ raise PollingTimeoutError(job_id)
1099
+ try:
1100
+ job = job_record(
1101
+ await self._client._request("GET", "/jobs/" + job_id, timeout=min(remaining, self._client.timeout))
1102
+ )
1103
+ except RequestTimeoutError:
1104
+ if time.monotonic() >= deadline:
1105
+ raise PollingTimeoutError(job_id) from None
1106
+ raise
1107
+ if time.monotonic() >= deadline:
1108
+ raise PollingTimeoutError(job_id)
1109
+ status = job.get("status")
1110
+ if status == "completed":
1111
+ return job
1112
+ if status in ("failed",):
1113
+ raise JobFailedError(job)
1114
+ if status not in ("pending", "processing"):
1115
+ raise ProtocolError("Unexpected job status.")
1116
+ remaining = deadline - time.monotonic()
1117
+ if remaining <= 0:
1118
+ raise PollingTimeoutError(job_id)
1119
+ await asyncio.sleep(min(poll_interval, remaining))
1120
+
1121
+
1122
+ class AsyncBulk(AsyncResource):
1123
+ async def create(self, request: CreateBulkJobRequest, *, timeout: float | None = None) -> BulkJobCreated:
1124
+ return await self._client._request("POST", "/bulk-jobs", body=bulk_input(request), timeout=timeout)
1125
+
1126
+ async def get(self, bulk_id: str, *, timeout: float | None = None) -> BulkJob:
1127
+ return job_record(
1128
+ await self._client._request("GET", "/bulk-jobs/" + identifier(bulk_id, True), timeout=timeout)
1129
+ )
1130
+
1131
+ async def list(self, *, cursor: str | None = None, limit: int = 20, timeout: float | None = None) -> BulkJobPage:
1132
+ integer(limit, "limit", 1, 50)
1133
+ params: dict[str, Any] = {"limit": limit}
1134
+ if cursor is not None:
1135
+ params["cursor"] = cursor
1136
+ return await self._client._request("GET", "/bulk-jobs", params=params, timeout=timeout)
1137
+
1138
+ async def update(self, bulk_id: str, request: UpdateBulkJobRequest, *, timeout: float | None = None) -> BulkJob:
1139
+ return job_record(
1140
+ await self._client._request(
1141
+ "PATCH",
1142
+ "/bulk-jobs/" + identifier(bulk_id, True),
1143
+ body=bulk_input(request, partial=True),
1144
+ timeout=timeout,
1145
+ )
1146
+ )
1147
+
1148
+ async def upload_file(self, created: BulkJobCreated, path: Any, *, timeout: float | None = None) -> None:
1149
+ await self._client._upload(created, path, timeout=timeout)
1150
+
1151
+ async def manifest(self, bulk_id: str, *, timeout: float | None = None) -> dict[str, Any]:
1152
+ return await self._client._result("/bulk-jobs/" + identifier(bulk_id, True) + "/results", timeout=timeout)
1153
+
1154
+ async def part(self, bulk_id: str, part_number: int, *, timeout: float | None = None) -> bytes:
1155
+ integer(part_number, "part_number", 0, 2**53 - 1)
1156
+ return await self._client._result(
1157
+ "/bulk-jobs/" + identifier(bulk_id, True) + "/results/" + str(part_number), binary=True, timeout=timeout
1158
+ )
1159
+
1160
+ async def iter_rows(self, bulk_id: str, part_number: int, *, timeout: float | None = None):
1161
+ """Iterate one bounded gzip/NDJSON part; decompressed lines use max_line_bytes."""
1162
+ raw = await self.part(bulk_id, part_number, timeout=timeout)
1163
+ for row in result_rows(raw, self._client.max_response_bytes, self._client.max_line_bytes):
1164
+ yield row
1165
+
1166
+ async def wait(self, bulk_id: str, *, timeout: float = 3600, poll_interval: float = 5) -> BulkJob:
1167
+ """Poll an existing ID without resubmitting or canceling accepted work."""
1168
+ identifier(bulk_id, True)
1169
+ deadline = time.monotonic() + positive(timeout, "timeout")
1170
+ positive(poll_interval, "poll_interval")
1171
+ while True:
1172
+ remaining = deadline - time.monotonic()
1173
+ if remaining <= 0:
1174
+ raise PollingTimeoutError(bulk_id)
1175
+ try:
1176
+ job = job_record(
1177
+ await self._client._request(
1178
+ "GET", "/bulk-jobs/" + bulk_id, timeout=min(remaining, self._client.timeout)
1179
+ )
1180
+ )
1181
+ except RequestTimeoutError:
1182
+ if time.monotonic() >= deadline:
1183
+ raise PollingTimeoutError(bulk_id) from None
1184
+ raise
1185
+ if time.monotonic() >= deadline:
1186
+ raise PollingTimeoutError(bulk_id)
1187
+ status = job.get("status")
1188
+ if status == "completed":
1189
+ return job
1190
+ if status == "paused":
1191
+ raise JobPausedError(job)
1192
+ if status in ("failed", "cancelled"):
1193
+ raise JobFailedError(job)
1194
+ if status not in ("awaiting_upload", "running", "finalizing"):
1195
+ raise ProtocolError("Unexpected job status.")
1196
+ remaining = deadline - time.monotonic()
1197
+ if remaining <= 0:
1198
+ raise PollingTimeoutError(bulk_id)
1199
+ await asyncio.sleep(min(poll_interval, remaining))
1200
+
1201
+ async def start(self, bulk_id: str, *, timeout: float | None = None) -> BulkJob:
1202
+ return job_record(
1203
+ await self._client._request("POST", "/bulk-jobs/" + identifier(bulk_id, True) + "/start", timeout=timeout)
1204
+ )
1205
+
1206
+ async def pause(self, bulk_id: str, *, timeout: float | None = None) -> BulkJob:
1207
+ return job_record(
1208
+ await self._client._request("POST", "/bulk-jobs/" + identifier(bulk_id, True) + "/pause", timeout=timeout)
1209
+ )
1210
+
1211
+ async def resume(self, bulk_id: str, *, timeout: float | None = None) -> BulkJob:
1212
+ return job_record(
1213
+ await self._client._request("POST", "/bulk-jobs/" + identifier(bulk_id, True) + "/resume", timeout=timeout)
1214
+ )
1215
+
1216
+ async def cancel(self, bulk_id: str, *, timeout: float | None = None) -> BulkJob:
1217
+ return job_record(
1218
+ await self._client._request("DELETE", "/bulk-jobs/" + identifier(bulk_id, True) + "", timeout=timeout)
1219
+ )
1220
+
1221
+ async def rows(self, bulk_id: str, *, timeout: float | None = None):
1222
+ """Yield all result rows in manifest order, buffering one bounded part."""
1223
+ manifest = await self.manifest(bulk_id, timeout=timeout)
1224
+ parts = manifest.get("parts")
1225
+ if not isinstance(parts, list):
1226
+ raise ProtocolError("Bulk manifest is missing its parts list.")
1227
+ seen = set()
1228
+ for part in parts:
1229
+ if (
1230
+ not isinstance(part, dict)
1231
+ or type(part.get("number")) is not int
1232
+ or part["number"] < 0
1233
+ or part["number"] in seen
1234
+ ):
1235
+ raise ProtocolError("Invalid or duplicate bulk part number.")
1236
+ seen.add(part["number"])
1237
+ async for row in self.iter_rows(bulk_id, part["number"], timeout=timeout):
1238
+ yield row
1239
+
1240
+ async def iter_jobs(
1241
+ self, *, max_pages: int, limit: int = 20, cursor: str | None = None, timeout: float | None = None
1242
+ ):
1243
+ """Yield bulk job records from a bounded number of cursor pages."""
1244
+ integer(max_pages, "max_pages", 1, 1000)
1245
+ seen = {cursor} if cursor else set()
1246
+ for _ in range(max_pages):
1247
+ page = await self.list(limit=limit, cursor=cursor, timeout=timeout)
1248
+ if not isinstance(page.get("data"), list) or not isinstance(page.get("pagination"), dict):
1249
+ raise ProtocolError("Invalid bulk listing response.")
1250
+ for job in page["data"]:
1251
+ if not isinstance(job, dict):
1252
+ raise ProtocolError("Expected a bulk job object.")
1253
+ yield job
1254
+ pagination = page["pagination"]
1255
+ if not pagination.get("hasMore"):
1256
+ return
1257
+ cursor = pagination.get("nextCursor")
1258
+ if not isinstance(cursor, str) or not cursor or cursor in seen:
1259
+ raise ProtocolError("Bulk listing returned an invalid or repeated cursor.")
1260
+ seen.add(cursor)
1261
+
1262
+
1263
+ class AsyncGoogle(AsyncResource):
1264
+ @overload
1265
+ async def search(
1266
+ self,
1267
+ query: str,
1268
+ *,
1269
+ mode: Literal["realtime"] = "realtime",
1270
+ callback_url: None = None,
1271
+ timeout: float | None = None,
1272
+ **params: Unpack[GoogleSearchParams],
1273
+ ) -> GoogleSearchResponse: ...
1274
+ @overload
1275
+ async def search(
1276
+ self,
1277
+ query: str,
1278
+ *,
1279
+ mode: Literal["async"],
1280
+ callback_url: str | None = None,
1281
+ timeout: float | None = None,
1282
+ **params: Unpack[GoogleSearchParams],
1283
+ ) -> AsyncSubmission: ...
1284
+ async def search(
1285
+ self,
1286
+ query: str,
1287
+ *,
1288
+ mode: Literal["realtime", "async"] = "realtime",
1289
+ callback_url: str | None = None,
1290
+ timeout: float | None = None,
1291
+ **params: Unpack[GoogleSearchParams],
1292
+ ) -> Any:
1293
+ """google_search: https://flashdata.dev/docs/sources/google_search"""
1294
+ if mode not in ("realtime", "async"):
1295
+ raise ValidationError("mode must be realtime or async.")
1296
+ if mode == "realtime" and callback_url is not None:
1297
+ raise ValidationError("Callbacks apply only to background queries.")
1298
+ payload: Any = {"source": "google_search", "query": query}
1299
+ if params:
1300
+ payload["params"] = params
1301
+ if callback_url is not None:
1302
+ payload["callback_url"] = callback_url
1303
+ return await (
1304
+ self._client.queries.submit(payload, timeout=timeout)
1305
+ if mode == "async"
1306
+ else self._client.queries.realtime(payload, timeout=timeout)
1307
+ )
1308
+
1309
+ @overload
1310
+ async def images(
1311
+ self,
1312
+ query: str,
1313
+ *,
1314
+ mode: Literal["realtime"] = "realtime",
1315
+ callback_url: None = None,
1316
+ timeout: float | None = None,
1317
+ **params: Unpack[GoogleImagesParams],
1318
+ ) -> GoogleImagesResponse: ...
1319
+ @overload
1320
+ async def images(
1321
+ self,
1322
+ query: str,
1323
+ *,
1324
+ mode: Literal["async"],
1325
+ callback_url: str | None = None,
1326
+ timeout: float | None = None,
1327
+ **params: Unpack[GoogleImagesParams],
1328
+ ) -> AsyncSubmission: ...
1329
+ async def images(
1330
+ self,
1331
+ query: str,
1332
+ *,
1333
+ mode: Literal["realtime", "async"] = "realtime",
1334
+ callback_url: str | None = None,
1335
+ timeout: float | None = None,
1336
+ **params: Unpack[GoogleImagesParams],
1337
+ ) -> Any:
1338
+ """google_images: https://flashdata.dev/docs/sources/google_images"""
1339
+ if mode not in ("realtime", "async"):
1340
+ raise ValidationError("mode must be realtime or async.")
1341
+ if mode == "realtime" and callback_url is not None:
1342
+ raise ValidationError("Callbacks apply only to background queries.")
1343
+ payload: Any = {"source": "google_images", "query": query}
1344
+ if params:
1345
+ payload["params"] = params
1346
+ if callback_url is not None:
1347
+ payload["callback_url"] = callback_url
1348
+ return await (
1349
+ self._client.queries.submit(payload, timeout=timeout)
1350
+ if mode == "async"
1351
+ else self._client.queries.realtime(payload, timeout=timeout)
1352
+ )
1353
+
1354
+ @overload
1355
+ async def news(
1356
+ self,
1357
+ query: str,
1358
+ *,
1359
+ mode: Literal["realtime"] = "realtime",
1360
+ callback_url: None = None,
1361
+ timeout: float | None = None,
1362
+ **params: Unpack[GoogleNewsParams],
1363
+ ) -> GoogleNewsResponse: ...
1364
+ @overload
1365
+ async def news(
1366
+ self,
1367
+ query: str,
1368
+ *,
1369
+ mode: Literal["async"],
1370
+ callback_url: str | None = None,
1371
+ timeout: float | None = None,
1372
+ **params: Unpack[GoogleNewsParams],
1373
+ ) -> AsyncSubmission: ...
1374
+ async def news(
1375
+ self,
1376
+ query: str,
1377
+ *,
1378
+ mode: Literal["realtime", "async"] = "realtime",
1379
+ callback_url: str | None = None,
1380
+ timeout: float | None = None,
1381
+ **params: Unpack[GoogleNewsParams],
1382
+ ) -> Any:
1383
+ """google_news: https://flashdata.dev/docs/sources/google_news"""
1384
+ if mode not in ("realtime", "async"):
1385
+ raise ValidationError("mode must be realtime or async.")
1386
+ if mode == "realtime" and callback_url is not None:
1387
+ raise ValidationError("Callbacks apply only to background queries.")
1388
+ payload: Any = {"source": "google_news", "query": query}
1389
+ if params:
1390
+ payload["params"] = params
1391
+ if callback_url is not None:
1392
+ payload["callback_url"] = callback_url
1393
+ return await (
1394
+ self._client.queries.submit(payload, timeout=timeout)
1395
+ if mode == "async"
1396
+ else self._client.queries.realtime(payload, timeout=timeout)
1397
+ )
1398
+
1399
+ @overload
1400
+ async def shopping(
1401
+ self,
1402
+ query: str,
1403
+ *,
1404
+ mode: Literal["realtime"] = "realtime",
1405
+ callback_url: None = None,
1406
+ timeout: float | None = None,
1407
+ **params: Unpack[GoogleShoppingParams],
1408
+ ) -> GoogleShoppingResponse: ...
1409
+ @overload
1410
+ async def shopping(
1411
+ self,
1412
+ query: str,
1413
+ *,
1414
+ mode: Literal["async"],
1415
+ callback_url: str | None = None,
1416
+ timeout: float | None = None,
1417
+ **params: Unpack[GoogleShoppingParams],
1418
+ ) -> AsyncSubmission: ...
1419
+ async def shopping(
1420
+ self,
1421
+ query: str,
1422
+ *,
1423
+ mode: Literal["realtime", "async"] = "realtime",
1424
+ callback_url: str | None = None,
1425
+ timeout: float | None = None,
1426
+ **params: Unpack[GoogleShoppingParams],
1427
+ ) -> Any:
1428
+ """google_shopping: https://flashdata.dev/docs/sources/google_shopping"""
1429
+ if mode not in ("realtime", "async"):
1430
+ raise ValidationError("mode must be realtime or async.")
1431
+ if mode == "realtime" and callback_url is not None:
1432
+ raise ValidationError("Callbacks apply only to background queries.")
1433
+ payload: Any = {"source": "google_shopping", "query": query}
1434
+ if params:
1435
+ payload["params"] = params
1436
+ if callback_url is not None:
1437
+ payload["callback_url"] = callback_url
1438
+ return await (
1439
+ self._client.queries.submit(payload, timeout=timeout)
1440
+ if mode == "async"
1441
+ else self._client.queries.realtime(payload, timeout=timeout)
1442
+ )
1443
+
1444
+ @overload
1445
+ async def videos(
1446
+ self,
1447
+ query: str,
1448
+ *,
1449
+ mode: Literal["realtime"] = "realtime",
1450
+ callback_url: None = None,
1451
+ timeout: float | None = None,
1452
+ **params: Unpack[GoogleVideosParams],
1453
+ ) -> GoogleVideosResponse: ...
1454
+ @overload
1455
+ async def videos(
1456
+ self,
1457
+ query: str,
1458
+ *,
1459
+ mode: Literal["async"],
1460
+ callback_url: str | None = None,
1461
+ timeout: float | None = None,
1462
+ **params: Unpack[GoogleVideosParams],
1463
+ ) -> AsyncSubmission: ...
1464
+ async def videos(
1465
+ self,
1466
+ query: str,
1467
+ *,
1468
+ mode: Literal["realtime", "async"] = "realtime",
1469
+ callback_url: str | None = None,
1470
+ timeout: float | None = None,
1471
+ **params: Unpack[GoogleVideosParams],
1472
+ ) -> Any:
1473
+ """google_videos: https://flashdata.dev/docs/sources/google_videos"""
1474
+ if mode not in ("realtime", "async"):
1475
+ raise ValidationError("mode must be realtime or async.")
1476
+ if mode == "realtime" and callback_url is not None:
1477
+ raise ValidationError("Callbacks apply only to background queries.")
1478
+ payload: Any = {"source": "google_videos", "query": query}
1479
+ if params:
1480
+ payload["params"] = params
1481
+ if callback_url is not None:
1482
+ payload["callback_url"] = callback_url
1483
+ return await (
1484
+ self._client.queries.submit(payload, timeout=timeout)
1485
+ if mode == "async"
1486
+ else self._client.queries.realtime(payload, timeout=timeout)
1487
+ )
1488
+
1489
+ @overload
1490
+ async def places(
1491
+ self,
1492
+ query: str,
1493
+ *,
1494
+ mode: Literal["realtime"] = "realtime",
1495
+ callback_url: None = None,
1496
+ timeout: float | None = None,
1497
+ **params: Unpack[GooglePlacesParams],
1498
+ ) -> GooglePlacesResponse: ...
1499
+ @overload
1500
+ async def places(
1501
+ self,
1502
+ query: str,
1503
+ *,
1504
+ mode: Literal["async"],
1505
+ callback_url: str | None = None,
1506
+ timeout: float | None = None,
1507
+ **params: Unpack[GooglePlacesParams],
1508
+ ) -> AsyncSubmission: ...
1509
+ async def places(
1510
+ self,
1511
+ query: str,
1512
+ *,
1513
+ mode: Literal["realtime", "async"] = "realtime",
1514
+ callback_url: str | None = None,
1515
+ timeout: float | None = None,
1516
+ **params: Unpack[GooglePlacesParams],
1517
+ ) -> Any:
1518
+ """google_places: https://flashdata.dev/docs/sources/google_places"""
1519
+ if mode not in ("realtime", "async"):
1520
+ raise ValidationError("mode must be realtime or async.")
1521
+ if mode == "realtime" and callback_url is not None:
1522
+ raise ValidationError("Callbacks apply only to background queries.")
1523
+ payload: Any = {"source": "google_places", "query": query}
1524
+ if params:
1525
+ payload["params"] = params
1526
+ if callback_url is not None:
1527
+ payload["callback_url"] = callback_url
1528
+ return await (
1529
+ self._client.queries.submit(payload, timeout=timeout)
1530
+ if mode == "async"
1531
+ else self._client.queries.realtime(payload, timeout=timeout)
1532
+ )
1533
+
1534
+ async def pages(
1535
+ self,
1536
+ source: Source,
1537
+ query: str,
1538
+ *,
1539
+ max_pages: int,
1540
+ start_page: int = 1,
1541
+ timeout: float | None = None,
1542
+ **params: Any,
1543
+ ):
1544
+ """Fetch at most max_pages paid Google pages, stopping on an empty result list."""
1545
+ keys = {
1546
+ "google_search": "organic",
1547
+ "google_images": "images",
1548
+ "google_news": "news",
1549
+ "google_shopping": "shopping",
1550
+ "google_videos": "videos",
1551
+ "google_places": "places",
1552
+ }
1553
+ if not isinstance(source, str) or source not in keys or "page" in params:
1554
+ raise ValidationError("Choose a Google source and use start_page for pagination.")
1555
+ integer(max_pages, "max_pages", 1, 100)
1556
+ integer(start_page, "start_page", 1, 100)
1557
+ if start_page + max_pages > 101:
1558
+ raise ValidationError("Requested pagination exceeds page 100.")
1559
+ for page in range(start_page, start_page + max_pages):
1560
+ payload: Any = {"source": source, "query": query, "params": {**params, "page": page}}
1561
+ response = await self._client.queries.realtime(payload, timeout=timeout)
1562
+ yield response
1563
+ if not any(isinstance(item, dict) and item.get(keys[source]) for item in response.get("results", [])):
1564
+ break
1565
+
1566
+
1567
+ class AsyncYouTube(AsyncResource):
1568
+ @overload
1569
+ async def search(
1570
+ self,
1571
+ query: str,
1572
+ *,
1573
+ mode: Literal["realtime"] = "realtime",
1574
+ callback_url: None = None,
1575
+ timeout: float | None = None,
1576
+ **params: Unpack[YoutubeSearchParams],
1577
+ ) -> YoutubeSearchResponse: ...
1578
+ @overload
1579
+ async def search(
1580
+ self,
1581
+ query: str,
1582
+ *,
1583
+ mode: Literal["async"],
1584
+ callback_url: str | None = None,
1585
+ timeout: float | None = None,
1586
+ **params: Unpack[YoutubeSearchParams],
1587
+ ) -> AsyncSubmission: ...
1588
+ async def search(
1589
+ self,
1590
+ query: str,
1591
+ *,
1592
+ mode: Literal["realtime", "async"] = "realtime",
1593
+ callback_url: str | None = None,
1594
+ timeout: float | None = None,
1595
+ **params: Unpack[YoutubeSearchParams],
1596
+ ) -> Any:
1597
+ """youtube_search: https://flashdata.dev/docs/sources/youtube_search"""
1598
+ if mode not in ("realtime", "async"):
1599
+ raise ValidationError("mode must be realtime or async.")
1600
+ if mode == "realtime" and callback_url is not None:
1601
+ raise ValidationError("Callbacks apply only to background queries.")
1602
+ payload: Any = {"source": "youtube_search", "query": query}
1603
+ if params:
1604
+ payload["params"] = params
1605
+ if callback_url is not None:
1606
+ payload["callback_url"] = callback_url
1607
+ return await (
1608
+ self._client.queries.submit(payload, timeout=timeout)
1609
+ if mode == "async"
1610
+ else self._client.queries.realtime(payload, timeout=timeout)
1611
+ )
1612
+
1613
+ @overload
1614
+ async def search_extended(
1615
+ self,
1616
+ query: str,
1617
+ *,
1618
+ mode: Literal["realtime"] = "realtime",
1619
+ callback_url: None = None,
1620
+ timeout: float | None = None,
1621
+ **params: Unpack[YoutubeSearchExtendedParams],
1622
+ ) -> YoutubeSearchExtendedResponse: ...
1623
+ @overload
1624
+ async def search_extended(
1625
+ self,
1626
+ query: str,
1627
+ *,
1628
+ mode: Literal["async"],
1629
+ callback_url: str | None = None,
1630
+ timeout: float | None = None,
1631
+ **params: Unpack[YoutubeSearchExtendedParams],
1632
+ ) -> AsyncSubmission: ...
1633
+ async def search_extended(
1634
+ self,
1635
+ query: str,
1636
+ *,
1637
+ mode: Literal["realtime", "async"] = "realtime",
1638
+ callback_url: str | None = None,
1639
+ timeout: float | None = None,
1640
+ **params: Unpack[YoutubeSearchExtendedParams],
1641
+ ) -> Any:
1642
+ """youtube_search_extended: https://flashdata.dev/docs/sources/youtube_search_extended"""
1643
+ if mode not in ("realtime", "async"):
1644
+ raise ValidationError("mode must be realtime or async.")
1645
+ if mode == "realtime" and callback_url is not None:
1646
+ raise ValidationError("Callbacks apply only to background queries.")
1647
+ payload: Any = {"source": "youtube_search_extended", "query": query}
1648
+ if params:
1649
+ payload["params"] = params
1650
+ if callback_url is not None:
1651
+ payload["callback_url"] = callback_url
1652
+ return await (
1653
+ self._client.queries.submit(payload, timeout=timeout)
1654
+ if mode == "async"
1655
+ else self._client.queries.realtime(payload, timeout=timeout)
1656
+ )
1657
+
1658
+ @overload
1659
+ async def metadata(
1660
+ self,
1661
+ video_id: str,
1662
+ *,
1663
+ mode: Literal["realtime"] = "realtime",
1664
+ callback_url: None = None,
1665
+ timeout: float | None = None,
1666
+ **params: Unpack[YoutubeMetadataParams],
1667
+ ) -> YoutubeMetadataResponse: ...
1668
+ @overload
1669
+ async def metadata(
1670
+ self,
1671
+ video_id: str,
1672
+ *,
1673
+ mode: Literal["async"],
1674
+ callback_url: str | None = None,
1675
+ timeout: float | None = None,
1676
+ **params: Unpack[YoutubeMetadataParams],
1677
+ ) -> AsyncSubmission: ...
1678
+ async def metadata(
1679
+ self,
1680
+ video_id: str,
1681
+ *,
1682
+ mode: Literal["realtime", "async"] = "realtime",
1683
+ callback_url: str | None = None,
1684
+ timeout: float | None = None,
1685
+ **params: Unpack[YoutubeMetadataParams],
1686
+ ) -> Any:
1687
+ """youtube_metadata: https://flashdata.dev/docs/sources/youtube_metadata"""
1688
+ if mode not in ("realtime", "async"):
1689
+ raise ValidationError("mode must be realtime or async.")
1690
+ if mode == "realtime" and callback_url is not None:
1691
+ raise ValidationError("Callbacks apply only to background queries.")
1692
+ payload: Any = {"source": "youtube_metadata", "video_id": video_id}
1693
+ if params:
1694
+ payload["params"] = params
1695
+ if callback_url is not None:
1696
+ payload["callback_url"] = callback_url
1697
+ return await (
1698
+ self._client.queries.submit(payload, timeout=timeout)
1699
+ if mode == "async"
1700
+ else self._client.queries.realtime(payload, timeout=timeout)
1701
+ )
1702
+
1703
+ @overload
1704
+ async def transcript(
1705
+ self,
1706
+ video_id: str,
1707
+ *,
1708
+ mode: Literal["realtime"] = "realtime",
1709
+ callback_url: None = None,
1710
+ timeout: float | None = None,
1711
+ **params: Unpack[YoutubeTranscriptParams],
1712
+ ) -> YoutubeTranscriptResponse: ...
1713
+ @overload
1714
+ async def transcript(
1715
+ self,
1716
+ video_id: str,
1717
+ *,
1718
+ mode: Literal["async"],
1719
+ callback_url: str | None = None,
1720
+ timeout: float | None = None,
1721
+ **params: Unpack[YoutubeTranscriptParams],
1722
+ ) -> AsyncSubmission: ...
1723
+ async def transcript(
1724
+ self,
1725
+ video_id: str,
1726
+ *,
1727
+ mode: Literal["realtime", "async"] = "realtime",
1728
+ callback_url: str | None = None,
1729
+ timeout: float | None = None,
1730
+ **params: Unpack[YoutubeTranscriptParams],
1731
+ ) -> Any:
1732
+ """youtube_transcript: https://flashdata.dev/docs/sources/youtube_transcript"""
1733
+ if mode not in ("realtime", "async"):
1734
+ raise ValidationError("mode must be realtime or async.")
1735
+ if mode == "realtime" and callback_url is not None:
1736
+ raise ValidationError("Callbacks apply only to background queries.")
1737
+ payload: Any = {"source": "youtube_transcript", "video_id": video_id}
1738
+ if params:
1739
+ payload["params"] = params
1740
+ if callback_url is not None:
1741
+ payload["callback_url"] = callback_url
1742
+ return await (
1743
+ self._client.queries.submit(payload, timeout=timeout)
1744
+ if mode == "async"
1745
+ else self._client.queries.realtime(payload, timeout=timeout)
1746
+ )
1747
+
1748
+ @overload
1749
+ async def captions(
1750
+ self,
1751
+ video_id: str,
1752
+ *,
1753
+ mode: Literal["realtime"] = "realtime",
1754
+ callback_url: None = None,
1755
+ timeout: float | None = None,
1756
+ **params: Unpack[YoutubeCaptionsParams],
1757
+ ) -> YoutubeCaptionsResponse: ...
1758
+ @overload
1759
+ async def captions(
1760
+ self,
1761
+ video_id: str,
1762
+ *,
1763
+ mode: Literal["async"],
1764
+ callback_url: str | None = None,
1765
+ timeout: float | None = None,
1766
+ **params: Unpack[YoutubeCaptionsParams],
1767
+ ) -> AsyncSubmission: ...
1768
+ async def captions(
1769
+ self,
1770
+ video_id: str,
1771
+ *,
1772
+ mode: Literal["realtime", "async"] = "realtime",
1773
+ callback_url: str | None = None,
1774
+ timeout: float | None = None,
1775
+ **params: Unpack[YoutubeCaptionsParams],
1776
+ ) -> Any:
1777
+ """youtube_captions: https://flashdata.dev/docs/sources/youtube_captions"""
1778
+ if mode not in ("realtime", "async"):
1779
+ raise ValidationError("mode must be realtime or async.")
1780
+ if mode == "realtime" and callback_url is not None:
1781
+ raise ValidationError("Callbacks apply only to background queries.")
1782
+ payload: Any = {"source": "youtube_captions", "video_id": video_id}
1783
+ if params:
1784
+ payload["params"] = params
1785
+ if callback_url is not None:
1786
+ payload["callback_url"] = callback_url
1787
+ return await (
1788
+ self._client.queries.submit(payload, timeout=timeout)
1789
+ if mode == "async"
1790
+ else self._client.queries.realtime(payload, timeout=timeout)
1791
+ )
1792
+
1793
+ @overload
1794
+ async def license_check(
1795
+ self,
1796
+ video_id: str,
1797
+ *,
1798
+ mode: Literal["realtime"] = "realtime",
1799
+ callback_url: None = None,
1800
+ timeout: float | None = None,
1801
+ **params: Unpack[YoutubeTrainabilityParams],
1802
+ ) -> YoutubeTrainabilityResponse: ...
1803
+ @overload
1804
+ async def license_check(
1805
+ self,
1806
+ video_id: str,
1807
+ *,
1808
+ mode: Literal["async"],
1809
+ callback_url: str | None = None,
1810
+ timeout: float | None = None,
1811
+ **params: Unpack[YoutubeTrainabilityParams],
1812
+ ) -> AsyncSubmission: ...
1813
+ async def license_check(
1814
+ self,
1815
+ video_id: str,
1816
+ *,
1817
+ mode: Literal["realtime", "async"] = "realtime",
1818
+ callback_url: str | None = None,
1819
+ timeout: float | None = None,
1820
+ **params: Unpack[YoutubeTrainabilityParams],
1821
+ ) -> Any:
1822
+ """youtube_trainability: https://flashdata.dev/docs/sources/youtube_trainability"""
1823
+ if mode not in ("realtime", "async"):
1824
+ raise ValidationError("mode must be realtime or async.")
1825
+ if mode == "realtime" and callback_url is not None:
1826
+ raise ValidationError("Callbacks apply only to background queries.")
1827
+ payload: Any = {"source": "youtube_trainability", "video_id": video_id}
1828
+ if params:
1829
+ payload["params"] = params
1830
+ if callback_url is not None:
1831
+ payload["callback_url"] = callback_url
1832
+ return await (
1833
+ self._client.queries.submit(payload, timeout=timeout)
1834
+ if mode == "async"
1835
+ else self._client.queries.realtime(payload, timeout=timeout)
1836
+ )
1837
+
1838
+ @overload
1839
+ async def channel(
1840
+ self,
1841
+ handle: str,
1842
+ *,
1843
+ mode: Literal["realtime"] = "realtime",
1844
+ callback_url: None = None,
1845
+ timeout: float | None = None,
1846
+ **params: Unpack[YoutubeChannelParams],
1847
+ ) -> YoutubeChannelResponse: ...
1848
+ @overload
1849
+ async def channel(
1850
+ self,
1851
+ handle: str,
1852
+ *,
1853
+ mode: Literal["async"],
1854
+ callback_url: str | None = None,
1855
+ timeout: float | None = None,
1856
+ **params: Unpack[YoutubeChannelParams],
1857
+ ) -> AsyncSubmission: ...
1858
+ async def channel(
1859
+ self,
1860
+ handle: str,
1861
+ *,
1862
+ mode: Literal["realtime", "async"] = "realtime",
1863
+ callback_url: str | None = None,
1864
+ timeout: float | None = None,
1865
+ **params: Unpack[YoutubeChannelParams],
1866
+ ) -> Any:
1867
+ """youtube_channel: https://flashdata.dev/docs/sources/youtube_channel"""
1868
+ if mode not in ("realtime", "async"):
1869
+ raise ValidationError("mode must be realtime or async.")
1870
+ if mode == "realtime" and callback_url is not None:
1871
+ raise ValidationError("Callbacks apply only to background queries.")
1872
+ payload: Any = {"source": "youtube_channel", "handle": handle}
1873
+ if params:
1874
+ payload["params"] = params
1875
+ if callback_url is not None:
1876
+ payload["callback_url"] = callback_url
1877
+ return await (
1878
+ self._client.queries.submit(payload, timeout=timeout)
1879
+ if mode == "async"
1880
+ else self._client.queries.realtime(payload, timeout=timeout)
1881
+ )
1882
+
1883
+ @overload
1884
+ async def suggestions(
1885
+ self,
1886
+ query: str,
1887
+ *,
1888
+ mode: Literal["realtime"] = "realtime",
1889
+ callback_url: None = None,
1890
+ timeout: float | None = None,
1891
+ **params: Unpack[YoutubeSuggestionsParams],
1892
+ ) -> YoutubeSuggestionsResponse: ...
1893
+ @overload
1894
+ async def suggestions(
1895
+ self,
1896
+ query: str,
1897
+ *,
1898
+ mode: Literal["async"],
1899
+ callback_url: str | None = None,
1900
+ timeout: float | None = None,
1901
+ **params: Unpack[YoutubeSuggestionsParams],
1902
+ ) -> AsyncSubmission: ...
1903
+ async def suggestions(
1904
+ self,
1905
+ query: str,
1906
+ *,
1907
+ mode: Literal["realtime", "async"] = "realtime",
1908
+ callback_url: str | None = None,
1909
+ timeout: float | None = None,
1910
+ **params: Unpack[YoutubeSuggestionsParams],
1911
+ ) -> Any:
1912
+ """youtube_suggestions: https://flashdata.dev/docs/sources/youtube_suggestions"""
1913
+ if mode not in ("realtime", "async"):
1914
+ raise ValidationError("mode must be realtime or async.")
1915
+ if mode == "realtime" and callback_url is not None:
1916
+ raise ValidationError("Callbacks apply only to background queries.")
1917
+ payload: Any = {"source": "youtube_suggestions", "query": query}
1918
+ if params:
1919
+ payload["params"] = params
1920
+ if callback_url is not None:
1921
+ payload["callback_url"] = callback_url
1922
+ return await (
1923
+ self._client.queries.submit(payload, timeout=timeout)
1924
+ if mode == "async"
1925
+ else self._client.queries.realtime(payload, timeout=timeout)
1926
+ )
1927
+
1928
+ async def download(
1929
+ self,
1930
+ video_id: str,
1931
+ *,
1932
+ mode: Literal["async"] = "async",
1933
+ callback_url: str | None = None,
1934
+ timeout: float | None = None,
1935
+ **params: Unpack[YoutubeDownloadParams],
1936
+ ) -> AsyncSubmission:
1937
+ """Submit cloud media delivery. Downloads always run in the background."""
1938
+ if mode != "async":
1939
+ raise ValidationError("Downloads support mode=async only.")
1940
+ payload: Any = {"source": "youtube_download", "video_id": video_id}
1941
+ if params:
1942
+ payload["params"] = params
1943
+ if callback_url is not None:
1944
+ payload["callback_url"] = callback_url
1945
+ return await self._client.queries.submit(payload, timeout=timeout)