browserless-bap 0.2.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.
Files changed (37) hide show
  1. browserless_bap/__init__.py +35 -0
  2. browserless_bap/_codec.py +29 -0
  3. browserless_bap/_io.py +27 -0
  4. browserless_bap/_page_generated.py +1322 -0
  5. browserless_bap/_unset.py +12 -0
  6. browserless_bap/_version.py +1 -0
  7. browserless_bap/async_api.py +3 -0
  8. browserless_bap/browser.py +108 -0
  9. browserless_bap/browserless.py +30 -0
  10. browserless_bap/element_handle.py +120 -0
  11. browserless_bap/emitter.py +134 -0
  12. browserless_bap/errors.py +64 -0
  13. browserless_bap/graphql/__init__.py +11 -0
  14. browserless_bap/graphql/builder.py +37 -0
  15. browserless_bap/graphql/mutations.py +417 -0
  16. browserless_bap/graphql/subscriptions.py +47 -0
  17. browserless_bap/page.py +771 -0
  18. browserless_bap/py.typed +1 -0
  19. browserless_bap/sync_api/__init__.py +24 -0
  20. browserless_bap/sync_api/_base.py +32 -0
  21. browserless_bap/sync_api/_bridge.py +419 -0
  22. browserless_bap/sync_api/_page_generated.py +979 -0
  23. browserless_bap/sync_api/browser.py +48 -0
  24. browserless_bap/sync_api/browserless.py +33 -0
  25. browserless_bap/sync_api/element_handle.py +70 -0
  26. browserless_bap/sync_api/page.py +383 -0
  27. browserless_bap/transport.py +522 -0
  28. browserless_bap/types/__init__.py +7 -0
  29. browserless_bap/types/enums.py +717 -0
  30. browserless_bap/types/events.py +121 -0
  31. browserless_bap/types/inputs.py +71 -0
  32. browserless_bap/types/options.py +367 -0
  33. browserless_bap/types/responses.py +314 -0
  34. browserless_bap-0.2.0.dist-info/METADATA +264 -0
  35. browserless_bap-0.2.0.dist-info/RECORD +37 -0
  36. browserless_bap-0.2.0.dist-info/WHEEL +4 -0
  37. browserless_bap-0.2.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,771 @@
1
+ """Concrete BAP page runtime and handwritten ergonomic methods."""
2
+
3
+ # Remote-operation timeouts are intentional public API parameters.
4
+ # ruff: noqa: ASYNC109
5
+
6
+ from __future__ import annotations
7
+
8
+ import asyncio
9
+ import math
10
+ import re
11
+ from collections.abc import Callable, Coroutine, Mapping, Sequence
12
+ from dataclasses import dataclass, field
13
+ from pathlib import Path
14
+ from typing import Any, Self, cast
15
+
16
+ from ._codec import drop_unset as _drop_unset
17
+ from ._io import read_text_file
18
+ from ._page_generated import PageGenerated
19
+ from ._unset import UNSET, UnsetType
20
+ from .emitter import EventEmitter, Listener
21
+ from .errors import ConnectionError, SchemaMismatchError, ValueError
22
+ from .errors import TimeoutError as BAPTimeoutError
23
+ from .graphql.builder import build_operation
24
+ from .graphql.mutations import ARG_TYPES, RESPONSE_FIELDS
25
+ from .graphql.subscriptions import SUBSCRIPTIONS
26
+ from .transport import Subscriber, Transport, Unsubscribe
27
+ from .types.enums import (
28
+ Method,
29
+ OperatorType,
30
+ ResourceType,
31
+ WaitForFunctionPolling,
32
+ WaitUntilGoto,
33
+ )
34
+ from .types.events import PageEventsMixin
35
+ from .types.inputs import CookieInput
36
+ from .types.responses import (
37
+ AddScriptTagResponse,
38
+ AddStyleTagResponse,
39
+ CookieResponse,
40
+ HTTPHeadersResponse,
41
+ HTTPResponse,
42
+ LiveURLCompleteEvent,
43
+ ResponseResponse,
44
+ SelectResponse,
45
+ WaitForEvent,
46
+ WaitForFunction,
47
+ WaitForRequestResponse,
48
+ WaitForResponseResponse,
49
+ )
50
+
51
+
52
+ @dataclass
53
+ class _LiveHandoff:
54
+ future: asyncio.Future[LiveURLCompleteEvent]
55
+ id: str | None = None
56
+ waiters: int = 0
57
+ early: dict[str, LiveURLCompleteEvent] = field(default_factory=dict)
58
+
59
+ @property
60
+ def rejected(self) -> bool:
61
+ return self.future.done() and (
62
+ self.future.cancelled() or self.future.exception() is not None
63
+ )
64
+
65
+
66
+ def _live_handoff() -> _LiveHandoff:
67
+ future: asyncio.Future[LiveURLCompleteEvent] = (
68
+ asyncio.get_running_loop().create_future()
69
+ )
70
+ # Retrieve errors even when completion precedes the caller's wait.
71
+ future.add_done_callback(
72
+ lambda done: None if done.cancelled() else done.exception()
73
+ )
74
+ return _LiveHandoff(future)
75
+
76
+
77
+ class Page(PageGenerated, PageEventsMixin):
78
+ """A BAP page with generated methods and an event lifecycle."""
79
+
80
+ def __init__(self, transport: Transport) -> None:
81
+ self._transport = transport
82
+ self._closed_flag = False
83
+ self._live: _LiveHandoff | None = None
84
+ self._previous_live: list[_LiveHandoff] = []
85
+ self._minting = False
86
+ self._events = EventEmitter(self._on_listener_count_change)
87
+ self._unsubscribes: dict[str, Unsubscribe] = {}
88
+ self._starting: set[str] = set()
89
+ self._restart_after_start: set[str] = set()
90
+ self._subscription_ready: dict[str, asyncio.Event] = {}
91
+ self._tasks: set[asyncio.Task[None]] = set()
92
+ self._detach_transport = transport.on_message(
93
+ lambda message: self._events.emit("message", message)
94
+ )
95
+
96
+ @property
97
+ def closed(self) -> bool:
98
+ return self._closed_flag or self._transport.closed
99
+
100
+ def subscribe(self, listener: Listener) -> Callable[[], None]:
101
+ """Listen to every non-handshake raw transport frame."""
102
+
103
+ self._events.on("message", listener)
104
+
105
+ def unsubscribe() -> None:
106
+ self._events.off("message", listener)
107
+
108
+ return unsubscribe
109
+
110
+ def _on(self, event: str, listener: Listener) -> None:
111
+ self._events.on(event, listener)
112
+
113
+ def _once(self, event: str, listener: Listener) -> None:
114
+ self._events.once(event, listener)
115
+
116
+ def _off(self, event: str, listener: Listener) -> None:
117
+ self._events.off(event, listener)
118
+
119
+ def emit(self, event: str, payload: object) -> bool:
120
+ return self._events.emit(event, payload)
121
+
122
+ def listener_count(self, event: str) -> int:
123
+ return self._events.listener_count(event)
124
+
125
+ def remove_all_listeners(self, event: str | None = None) -> Self:
126
+ self._events.remove_all_listeners(event)
127
+ return self
128
+
129
+ async def _execute(
130
+ self,
131
+ mutation_name: str,
132
+ args: Mapping[str, Any] | None,
133
+ response_type: str,
134
+ *,
135
+ timeout: float | UnsetType | None = None,
136
+ ) -> Any:
137
+ if mutation_name != "liveURL":
138
+ return await self._execute_operation(
139
+ mutation_name, args, response_type, timeout=timeout
140
+ )
141
+ if self._minting:
142
+ raise ValueError(
143
+ "Await the previous live_url() call before minting another link"
144
+ )
145
+ self._minting = True
146
+ if self._live and self._live.id and not self._live.future.done():
147
+ self._previous_live.append(self._live)
148
+ state = (
149
+ self._live
150
+ if self._live and not self._live.id and not self._live.future.done()
151
+ else _live_handoff()
152
+ )
153
+ self._live = state
154
+ try:
155
+ self._on_listener_count_change("liveComplete", 1)
156
+ await self._wait_subscription_started("liveComplete")
157
+ if "liveComplete" not in self._unsubscribes:
158
+ raise ConnectionError("Live completion subscription unavailable")
159
+ result = await self._execute_operation(
160
+ mutation_name, args, response_type, timeout=timeout
161
+ )
162
+ state.id = result.get("liveURLId") if isinstance(result, Mapping) else None
163
+ if not state.id:
164
+ raise ValueError("live_url returned no liveURLId")
165
+ if state.id in state.early and not state.future.done():
166
+ state.future.set_result(state.early[state.id])
167
+ return result
168
+ except BaseException as error:
169
+ if not state.future.done():
170
+ state.future.set_exception(
171
+ error
172
+ if isinstance(error, Exception)
173
+ else ConnectionError("live_url() was cancelled or interrupted")
174
+ )
175
+ raise
176
+ finally:
177
+ state.early.clear()
178
+ self._minting = False
179
+ self._on_listener_count_change(
180
+ "liveComplete", self.listener_count("liveComplete")
181
+ )
182
+
183
+ async def _execute_operation(
184
+ self,
185
+ mutation_name: str,
186
+ args: Mapping[str, Any] | None,
187
+ response_type: str,
188
+ *,
189
+ timeout: float | UnsetType | None = None,
190
+ ) -> Any:
191
+ fields = RESPONSE_FIELDS.get(response_type)
192
+ if fields is None:
193
+ raise SchemaMismatchError(f"Unknown response type: {response_type}")
194
+ operation = build_operation(
195
+ mutation_name,
196
+ args,
197
+ fields,
198
+ ARG_TYPES.get(mutation_name),
199
+ )
200
+ query, variables = operation
201
+ result: Any = await self._transport.send(
202
+ query,
203
+ variables,
204
+ _timeout_value(timeout),
205
+ )
206
+ if not isinstance(result, Mapping):
207
+ return None
208
+ return result.get(mutation_name)
209
+
210
+ async def wait_for_live_complete(
211
+ self, *, timeout: float | None = None
212
+ ) -> LiveURLCompleteEvent:
213
+ """Wait for the current handoff or next mint.
214
+
215
+ Timeout is in ms; None or 0 disables the client deadline.
216
+
217
+ Completion or failure is retained until the next live_url() call.
218
+ """
219
+ if self.closed:
220
+ raise ConnectionError("Page is closed")
221
+ deadline = 0 if timeout is None else timeout
222
+ if not math.isfinite(deadline) or deadline < 0:
223
+ raise ValueError("timeout must be a finite non-negative number")
224
+ if self._live is None or (
225
+ self._live.rejected and not self._live.id and not self._minting
226
+ ):
227
+ self._live = _live_handoff()
228
+ state = self._live
229
+ state.waiters += 1
230
+ if not state.future.done():
231
+ self._on_listener_count_change("liveComplete", 1)
232
+ try:
233
+ # Each waiter has its own deadline; cancellation must not cancel
234
+ # the retained completion or another caller's wait.
235
+ async with asyncio.timeout(deadline / 1000 if deadline else None):
236
+ return await asyncio.shield(state.future)
237
+ except BAPTimeoutError:
238
+ raise
239
+ except TimeoutError as error:
240
+ raise BAPTimeoutError("wait_for_live_complete", deadline) from error
241
+ finally:
242
+ state.waiters -= 1
243
+ if (
244
+ self._live is state
245
+ and not state.id
246
+ and not state.future.done()
247
+ and not state.waiters
248
+ and not self._minting
249
+ ):
250
+ self._live = None
251
+ self._on_listener_count_change(
252
+ "liveComplete", self.listener_count("liveComplete")
253
+ )
254
+
255
+ def _fail_live(self, error: BaseException) -> None:
256
+ for state in (self._live, *self._previous_live):
257
+ if state is not None and not state.future.done():
258
+ state.future.set_exception(error)
259
+ self._previous_live.clear()
260
+
261
+ def _deliver_subscription(self, event: str, data: Mapping[str, Any]) -> None:
262
+ if event == "liveComplete":
263
+ completion = cast(LiveURLCompleteEvent, data[event])
264
+ # Reused IDs complete the oldest pending handoff first.
265
+ state = next(
266
+ (
267
+ previous
268
+ for previous in self._previous_live
269
+ if previous.id == completion["liveURLId"]
270
+ ),
271
+ self._live,
272
+ )
273
+ if (
274
+ state
275
+ and not state.future.done()
276
+ and state.id == completion["liveURLId"]
277
+ ):
278
+ state.future.set_result(completion)
279
+ elif state and not state.id and self._minting:
280
+ completion_id = completion["liveURLId"]
281
+ if completion_id is not None:
282
+ state.early[completion_id] = completion
283
+ self._previous_live = [
284
+ state for state in self._previous_live if not state.future.done()
285
+ ]
286
+ self._events.emit(event, data.get(event))
287
+ if event == "liveComplete":
288
+ self._on_listener_count_change(event, self.listener_count(event))
289
+
290
+ async def goto(
291
+ self,
292
+ url: str,
293
+ *,
294
+ timeout: float | UnsetType = UNSET,
295
+ wait_until: WaitUntilGoto | UnsetType = UNSET,
296
+ wait_until_all: list[WaitUntilGoto] | UnsetType = UNSET,
297
+ referer: str | UnsetType = UNSET,
298
+ referrer_policy: str | UnsetType = UNSET,
299
+ remote_response_metadata: bool | UnsetType = UNSET,
300
+ ) -> HTTPResponse | None:
301
+ args = _drop_unset(
302
+ {
303
+ "url": url,
304
+ "timeout": timeout,
305
+ "waitUntil": wait_until,
306
+ "waitUntilAll": wait_until_all,
307
+ "referer": referer,
308
+ "referrerPolicy": referrer_policy,
309
+ }
310
+ )
311
+ response_type = (
312
+ "HTTPResponseWithRemoteMetadata"
313
+ if remote_response_metadata is True
314
+ else "HTTPResponse"
315
+ )
316
+ return cast(
317
+ HTTPResponse | None,
318
+ await self._execute("goto", args, response_type, timeout=timeout),
319
+ )
320
+
321
+ async def response(
322
+ self,
323
+ *,
324
+ status: list[int] | UnsetType = UNSET,
325
+ method: list[Method] | UnsetType = UNSET,
326
+ operator: OperatorType | UnsetType = UNSET,
327
+ timeout: float | UnsetType = UNSET,
328
+ type: list[ResourceType] | UnsetType = UNSET,
329
+ url: list[str] | UnsetType = UNSET,
330
+ wait: bool | UnsetType = UNSET,
331
+ body_encoding: bool | UnsetType = UNSET,
332
+ ) -> list[ResponseResponse]:
333
+ args = _drop_unset(
334
+ {
335
+ "status": status,
336
+ "method": method,
337
+ "operator": operator,
338
+ "timeout": timeout,
339
+ "type": type,
340
+ "url": url,
341
+ "wait": wait,
342
+ }
343
+ )
344
+ response_type = (
345
+ "ResponseResponseWithBodyEncoding"
346
+ if body_encoding is True
347
+ else "ResponseResponse"
348
+ )
349
+ result = await self._execute("response", args, response_type, timeout=timeout)
350
+ return cast(list[ResponseResponse], list(result or ()))
351
+
352
+ async def select_option(
353
+ self, selector: str, value: str | Sequence[str]
354
+ ) -> SelectResponse:
355
+ return cast(
356
+ SelectResponse,
357
+ await self._execute(
358
+ "select",
359
+ {"selector": selector, "value": value},
360
+ "SelectResponse",
361
+ ),
362
+ )
363
+
364
+ async def add_cookies(self, cookies: Sequence[CookieInput]) -> CookieResponse:
365
+ return cast(
366
+ CookieResponse,
367
+ await self._execute(
368
+ "cookies", {"cookies": list(cookies)}, "CookieResponse"
369
+ ),
370
+ )
371
+
372
+ async def set_extra_http_headers(
373
+ self, headers: Mapping[str, str]
374
+ ) -> HTTPHeadersResponse:
375
+ values = [{"name": name, "value": value} for name, value in headers.items()]
376
+ return cast(
377
+ HTTPHeadersResponse,
378
+ await self._execute(
379
+ "setExtraHTTPHeaders",
380
+ {"headers": values},
381
+ "HTTPHeadersResponse",
382
+ ),
383
+ )
384
+
385
+ async def evaluate(
386
+ self,
387
+ expression: str,
388
+ *,
389
+ timeout: float | UnsetType = UNSET,
390
+ url: str | UnsetType = UNSET,
391
+ ) -> str | None:
392
+ result = await self._execute(
393
+ "evaluate",
394
+ _drop_unset({"content": expression, "timeout": timeout, "url": url}),
395
+ "EvaluateResponse",
396
+ timeout=timeout,
397
+ )
398
+ if not isinstance(result, Mapping):
399
+ return None
400
+ value = result.get("value")
401
+ return None if value is None else str(value)
402
+
403
+ async def wait_for_function(
404
+ self,
405
+ expression: str,
406
+ *,
407
+ polling: float | UnsetType = UNSET,
408
+ polling_type: WaitForFunctionPolling | UnsetType = UNSET,
409
+ timeout: float | UnsetType = UNSET,
410
+ complete_on_promise_resolution: bool | UnsetType = UNSET,
411
+ ) -> WaitForFunction:
412
+ predicate = expression
413
+ if complete_on_promise_resolution is True:
414
+ predicate = f"async () => {{ await ({expression})(); return true; }}"
415
+ args = _drop_unset(
416
+ {
417
+ "fn": predicate,
418
+ "polling": polling,
419
+ "pollingType": polling_type,
420
+ "timeout": timeout,
421
+ }
422
+ )
423
+ return cast(
424
+ WaitForFunction,
425
+ await self._execute(
426
+ "waitForFunction",
427
+ args,
428
+ "WaitForFunction",
429
+ timeout=self._transport.operation_timeout(
430
+ _timeout_value(timeout), 5_000
431
+ ),
432
+ ),
433
+ )
434
+
435
+ async def wait_for_event(
436
+ self,
437
+ event: str,
438
+ *,
439
+ timeout: float | UnsetType = UNSET,
440
+ ) -> WaitForEvent:
441
+ """Wait for the next event payload, bounded by `timeout` when provided."""
442
+
443
+ return cast(
444
+ WaitForEvent,
445
+ await self._execute(
446
+ "waitForEvent",
447
+ _drop_unset({"event": event, "timeout": timeout}),
448
+ "WaitForEvent",
449
+ timeout=self._transport.operation_timeout(
450
+ _timeout_value(timeout), 5_000
451
+ ),
452
+ ),
453
+ )
454
+
455
+ async def add_script_tag(
456
+ self,
457
+ *,
458
+ url: str | UnsetType = UNSET,
459
+ path: str | Path | UnsetType = UNSET,
460
+ content: str | UnsetType = UNSET,
461
+ id: str | UnsetType = UNSET,
462
+ type: str | UnsetType = UNSET,
463
+ ) -> AddScriptTagResponse:
464
+ _require_one_source(url=url, path=path, content=content)
465
+ resolved_content = content
466
+ if path is not UNSET:
467
+ raw_path = str(path)
468
+ resolved_content = await read_text_file(raw_path)
469
+ safe_path = re.sub(r"[\r\n\u2028\u2029]", "", raw_path)
470
+ resolved_content += f"//# sourceURL={safe_path}"
471
+ args = _drop_unset(
472
+ {
473
+ "url": url,
474
+ "content": resolved_content,
475
+ "id": id,
476
+ "type": "text/javascript" if type is UNSET else type,
477
+ }
478
+ )
479
+ return cast(
480
+ AddScriptTagResponse,
481
+ await self._execute("addScriptTag", args, "AddScriptTagResponse"),
482
+ )
483
+
484
+ async def add_style_tag(
485
+ self,
486
+ *,
487
+ url: str | UnsetType = UNSET,
488
+ path: str | Path | UnsetType = UNSET,
489
+ content: str | UnsetType = UNSET,
490
+ ) -> AddStyleTagResponse:
491
+ _require_one_source(url=url, path=path, content=content)
492
+ resolved_content = content
493
+ if path is not UNSET:
494
+ raw_path = str(path)
495
+ resolved_content = await read_text_file(raw_path)
496
+ safe_path = raw_path.replace("*/", "")
497
+ resolved_content += f"/*# sourceURL={safe_path}*/"
498
+ return cast(
499
+ AddStyleTagResponse,
500
+ await self._execute(
501
+ "addStyleTag",
502
+ _drop_unset({"url": url, "content": resolved_content}),
503
+ "AddStyleTagResponse",
504
+ ),
505
+ )
506
+
507
+ async def wait_for_request(
508
+ self,
509
+ url: str | UnsetType = UNSET,
510
+ *,
511
+ method: Method | UnsetType = UNSET,
512
+ operator: OperatorType | UnsetType = UNSET,
513
+ timeout: float | UnsetType = UNSET,
514
+ ) -> WaitForRequestResponse:
515
+ return cast(
516
+ WaitForRequestResponse,
517
+ await self._execute(
518
+ "waitForRequest",
519
+ _drop_unset(
520
+ {
521
+ "url": url,
522
+ "method": method,
523
+ "operator": operator,
524
+ "timeout": timeout,
525
+ }
526
+ ),
527
+ "WaitForRequestResponse",
528
+ timeout=timeout,
529
+ ),
530
+ )
531
+
532
+ async def wait_for_response(
533
+ self,
534
+ url: str | UnsetType = UNSET,
535
+ *,
536
+ statuses: Sequence[int] | UnsetType = UNSET,
537
+ codes: Sequence[int] | UnsetType = UNSET,
538
+ operator: OperatorType | UnsetType = UNSET,
539
+ timeout: float | UnsetType = UNSET,
540
+ ) -> WaitForResponseResponse:
541
+ return cast(
542
+ WaitForResponseResponse,
543
+ await self._execute(
544
+ "waitForResponse",
545
+ _drop_unset(
546
+ {
547
+ "url": url,
548
+ "statuses": statuses,
549
+ "codes": codes,
550
+ "operator": operator,
551
+ }
552
+ ),
553
+ "WaitForResponseResponse",
554
+ timeout=timeout,
555
+ ),
556
+ )
557
+
558
+ async def wait_for_timeout(self, ms: float) -> None:
559
+ await self._execute(
560
+ "waitForTimeout",
561
+ {"time": ms},
562
+ "WaitForTimeoutResponse",
563
+ timeout=ms + 5_000,
564
+ )
565
+
566
+ async def send(
567
+ self,
568
+ query: str,
569
+ *,
570
+ variables: Mapping[str, Any] | None = None,
571
+ timeout: float | None = None,
572
+ ) -> Any:
573
+ return await self._transport.send(query, variables, timeout)
574
+
575
+ async def close(self) -> None:
576
+ if self._closed_flag:
577
+ return
578
+ self._closed_flag = True
579
+ self._fail_live(ConnectionError("Page is closed"))
580
+ for ready in self._subscription_ready.values():
581
+ ready.set()
582
+ self._detach_transport()
583
+ self._events.remove_all_listeners()
584
+ unsubscribes = tuple(self._unsubscribes.values())
585
+ self._unsubscribes.clear()
586
+ try:
587
+ async with asyncio.timeout(5):
588
+ await asyncio.gather(
589
+ *(unsubscribe() for unsubscribe in unsubscribes),
590
+ *tuple(self._tasks),
591
+ return_exceptions=True,
592
+ )
593
+ except TimeoutError:
594
+ for task in tuple(self._tasks):
595
+ task.cancel()
596
+ await self._transport.close()
597
+
598
+ async def __aenter__(self) -> Page:
599
+ return self
600
+
601
+ async def __aexit__(
602
+ self,
603
+ exc_type: type[BaseException] | None,
604
+ exc: BaseException | None,
605
+ traceback: object | None,
606
+ ) -> None:
607
+ await self.close()
608
+
609
+ @property
610
+ def _has_pending_live(self) -> bool:
611
+ return self._minting or bool(
612
+ (
613
+ self._live
614
+ and not self._live.future.done()
615
+ and (self._live.id or self._live.waiters)
616
+ )
617
+ or self._previous_live
618
+ )
619
+
620
+ def _on_listener_count_change(self, event: str, count: int) -> None:
621
+ if self._closed_flag or event not in SUBSCRIPTIONS:
622
+ return
623
+ if count > 0:
624
+ if event in self._unsubscribes:
625
+ self._subscription_ready.setdefault(event, asyncio.Event()).set()
626
+ elif event not in self._starting:
627
+ self._starting.add(event)
628
+ self._subscription_ready[event] = asyncio.Event()
629
+ self._spawn(self._start_subscription(event))
630
+ elif count == 1:
631
+ self._restart_after_start.add(event)
632
+ else:
633
+ if event == "liveComplete" and self._has_pending_live:
634
+ return
635
+ self._restart_after_start.discard(event)
636
+ self._spawn(self._stop_subscription(event))
637
+
638
+ async def _wait_subscription_started(self, event: str) -> None:
639
+ """Wait until a lazy subscription start attempt reaches a terminal state."""
640
+
641
+ if (
642
+ self._closed_flag
643
+ or (
644
+ self._events.listener_count(event) == 0
645
+ and not (event == "liveComplete" and self._has_pending_live)
646
+ )
647
+ or event in self._unsubscribes
648
+ ):
649
+ return
650
+ ready = self._subscription_ready.get(event)
651
+ if ready is not None:
652
+ await ready.wait()
653
+
654
+ async def _start_subscription(self, event: str) -> None:
655
+ if event in self._unsubscribes or self._closed_flag:
656
+ self._starting.discard(event)
657
+ ready = self._subscription_ready.get(event)
658
+ if ready is not None:
659
+ ready.set()
660
+ return
661
+ own_handle: Unsubscribe | None = None
662
+ terminated = False
663
+
664
+ def clear_if_own() -> None:
665
+ nonlocal terminated
666
+ terminated = True
667
+ if own_handle is not None and self._unsubscribes.get(event) is own_handle:
668
+ self._unsubscribes.pop(event, None)
669
+
670
+ def on_error(error: Exception) -> None:
671
+ clear_if_own()
672
+ if event == "liveComplete":
673
+ self._fail_live(error)
674
+ self._events.emit("error", error)
675
+
676
+ def on_complete() -> None:
677
+ clear_if_own()
678
+ if event == "liveComplete":
679
+ self._fail_live(ConnectionError("Live completion stream ended"))
680
+
681
+ try:
682
+ spec = SUBSCRIPTIONS[event]
683
+ operation = build_operation(
684
+ event,
685
+ None,
686
+ spec["fields"],
687
+ spec["arg_types"],
688
+ "subscription",
689
+ )
690
+ query, variables = operation
691
+ unsubscribe = await self._transport.subscribe(
692
+ query,
693
+ variables,
694
+ Subscriber(
695
+ next=lambda data: self._deliver_subscription(event, data),
696
+ error=on_error,
697
+ complete=on_complete,
698
+ ),
699
+ )
700
+ own_handle = unsubscribe
701
+ if (
702
+ terminated
703
+ or self._closed_flag
704
+ or (
705
+ self._events.listener_count(event) == 0
706
+ and not (event == "liveComplete" and self._has_pending_live)
707
+ )
708
+ ):
709
+ await unsubscribe()
710
+ return
711
+ self._unsubscribes[event] = unsubscribe
712
+ except BaseException as exc:
713
+ if event == "liveComplete":
714
+ self._fail_live(exc)
715
+ if not self._closed_flag:
716
+ self._events.emit("error", exc)
717
+ finally:
718
+ self._starting.discard(event)
719
+ ready = self._subscription_ready.get(event)
720
+ if ready is not None:
721
+ ready.set()
722
+ restart = event in self._restart_after_start
723
+ self._restart_after_start.discard(event)
724
+ if (
725
+ restart
726
+ and not self._closed_flag
727
+ and self._events.listener_count(event) > 0
728
+ and event not in self._unsubscribes
729
+ ):
730
+ self._starting.add(event)
731
+ self._subscription_ready[event] = asyncio.Event()
732
+ self._spawn(self._start_subscription(event))
733
+
734
+ async def _stop_subscription(self, event: str) -> None:
735
+ if self._events.listener_count(event) > 0 or (
736
+ event == "liveComplete" and self._has_pending_live
737
+ ):
738
+ return
739
+ unsubscribe = self._unsubscribes.pop(event, None)
740
+ if unsubscribe is not None:
741
+ await unsubscribe()
742
+
743
+ def _spawn(self, coroutine: Coroutine[Any, Any, None]) -> None:
744
+ task = asyncio.create_task(coroutine)
745
+ self._tasks.add(task)
746
+ task.add_done_callback(self._task_done)
747
+
748
+ def _task_done(self, task: asyncio.Task[None]) -> None:
749
+ self._tasks.discard(task)
750
+ if task.cancelled():
751
+ return
752
+ error = task.exception()
753
+ if error is not None and not self._closed_flag:
754
+ self._events.emit("error", error)
755
+
756
+
757
+ def _timeout_value(value: float | UnsetType | None) -> float | None:
758
+ return None if value is UNSET else value
759
+
760
+
761
+ def _require_one_source(
762
+ *,
763
+ url: str | UnsetType,
764
+ path: str | Path | UnsetType,
765
+ content: str | UnsetType,
766
+ ) -> None:
767
+ values = (url, path, content)
768
+ if sum(value is not UNSET for value in values) != 1:
769
+ raise ValueError(
770
+ "Exactly one of `url`, `path`, or `content` must be specified."
771
+ )