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,12 @@
1
+ """Sentinel separating an omitted GraphQL argument from an explicit null."""
2
+
3
+ from enum import Enum
4
+
5
+
6
+ class UnsetType(Enum):
7
+ UNSET = "<UNSET>"
8
+
9
+
10
+ UNSET = UnsetType.UNSET
11
+
12
+ __all__ = ["UNSET", "UnsetType"]
@@ -0,0 +1 @@
1
+ __version__ = "0.2.0"
@@ -0,0 +1,3 @@
1
+ """Playwright-style async API alias."""
2
+
3
+ from . import * # noqa: F403
@@ -0,0 +1,108 @@
1
+ """Browser lifecycle for BAP-backed pages."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import logging
7
+ from collections.abc import AsyncIterator
8
+ from contextlib import asynccontextmanager
9
+ from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
10
+
11
+ from .errors import ValueError
12
+ from .page import Page
13
+ from .transport import Transport, TransportFactory
14
+
15
+ logger = logging.getLogger("browserless_bap")
16
+
17
+
18
+ class Browser:
19
+ """Owns the pages opened against one Browserless configuration."""
20
+
21
+ def __init__(
22
+ self,
23
+ *,
24
+ browser_ws_endpoint: str | None = None,
25
+ token: str | None = None,
26
+ timeout: float = 30_000,
27
+ transport: TransportFactory | None = None,
28
+ ) -> None:
29
+ if browser_ws_endpoint is None and transport is None:
30
+ raise ValueError(
31
+ "Either `browser_ws_endpoint` or `transport` must be provided"
32
+ )
33
+ self._base_url = browser_ws_endpoint
34
+ self._token = token
35
+ self._timeout = timeout
36
+ self._transport_factory = transport
37
+ self._pages: list[Page] = []
38
+ self._closed = False
39
+
40
+ async def new_page(self) -> Page:
41
+ """Open a new page with its own BAP WebSocket."""
42
+
43
+ if self._closed:
44
+ raise ValueError("Browser is closed")
45
+ self._pages = [page for page in self._pages if not page.closed]
46
+ url = _with_token(self._base_url, self._token)
47
+ transport = Transport(url, self._timeout, self._transport_factory)
48
+ await transport.connect()
49
+ if self._closed:
50
+ await transport.close()
51
+ raise ValueError("Browser is closed")
52
+ page = Page(transport)
53
+ self._pages.append(page)
54
+ return page
55
+
56
+ @asynccontextmanager
57
+ async def page(self) -> AsyncIterator[Page]:
58
+ """Open a page and close it when the context exits."""
59
+
60
+ page = await self.new_page()
61
+ try:
62
+ yield page
63
+ finally:
64
+ await page.close()
65
+
66
+ def get_pages(self) -> list[Page]:
67
+ """Return pages whose transports remain open."""
68
+
69
+ return [page for page in self._pages if not page.closed]
70
+
71
+ async def close(self) -> None:
72
+ """Close every page opened by this browser."""
73
+
74
+ if self._closed:
75
+ return
76
+ self._closed = True
77
+ results = await asyncio.gather(
78
+ *(page.close() for page in self._pages if not page.closed),
79
+ return_exceptions=True,
80
+ )
81
+ for result in results:
82
+ if isinstance(result, BaseException):
83
+ logger.error(
84
+ "Failed to close a bap page",
85
+ exc_info=(type(result), result, result.__traceback__),
86
+ )
87
+
88
+ async def __aenter__(self) -> Browser:
89
+ return self
90
+
91
+ async def __aexit__(
92
+ self,
93
+ exc_type: type[BaseException] | None,
94
+ exc: BaseException | None,
95
+ traceback: object | None,
96
+ ) -> None:
97
+ await self.close()
98
+
99
+
100
+ def _with_token(url: str | None, token: str | None) -> str | None:
101
+ if url is None or token is None:
102
+ return url
103
+ parts = urlsplit(url)
104
+ query = parse_qsl(parts.query, keep_blank_values=True)
105
+ query.append(("token", token))
106
+ return urlunsplit(
107
+ (parts.scheme, parts.netloc, parts.path, urlencode(query), parts.fragment)
108
+ )
@@ -0,0 +1,30 @@
1
+ """Public entry point for creating BAP-backed browser sessions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from .browser import Browser
6
+ from .transport import TransportFactory
7
+
8
+
9
+ class Browserless:
10
+ """Factory namespace matching the Browserless SDKs."""
11
+
12
+ def __new__(cls) -> Browserless:
13
+ raise TypeError("Browserless is a factory and cannot be instantiated")
14
+
15
+ @staticmethod
16
+ def connect(
17
+ *,
18
+ browser_ws_endpoint: str | None = None,
19
+ token: str | None = None,
20
+ timeout: float = 30_000,
21
+ transport: TransportFactory | None = None,
22
+ ) -> Browser:
23
+ """Create a browser configured for a BAP-compatible WebSocket endpoint."""
24
+
25
+ return Browser(
26
+ browser_ws_endpoint=browser_ws_endpoint,
27
+ token=token,
28
+ timeout=timeout,
29
+ transport=transport,
30
+ )
@@ -0,0 +1,120 @@
1
+ """Snapshot-backed element handle with live page actions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from collections.abc import Mapping, Sequence
7
+ from typing import TYPE_CHECKING, Any, Unpack
8
+
9
+ from .types.options import ClickOptions, TypeOptions
10
+ from .types.responses import ClickResponse, HoverResponse, SelectResponse, TypeResponse
11
+
12
+ if TYPE_CHECKING:
13
+ from .page import Page
14
+
15
+
16
+ def _resolve_selector(selector: str, *, all_matches: bool = False) -> str:
17
+ method = "querySelectorAll" if all_matches else "querySelector"
18
+ fallback = "[]" if all_matches else "null"
19
+ encoded = json.dumps(selector)
20
+ return (
21
+ "(() => { try { return document."
22
+ f"{method}({encoded}); "
23
+ f"}} catch {{ return eval({encoded}) ?? {fallback}; }} }})()"
24
+ )
25
+
26
+
27
+ def _selector_at(selector: str, index: int) -> str:
28
+ resolved = _resolve_selector(selector, all_matches=True)
29
+ return f"({resolved})[{index}] ?? null"
30
+
31
+
32
+ def _scoped_selector(parent: str, selector: str, *, all_matches: bool = False) -> str:
33
+ resolved_parent = _resolve_selector(parent)
34
+ method = "querySelectorAll" if all_matches else "querySelector"
35
+ fallback = "[]" if all_matches else "null"
36
+ encoded = json.dumps(selector)
37
+ return (
38
+ "(() => { "
39
+ f"const root = {resolved_parent}; "
40
+ f"if (!root) return {fallback}; "
41
+ f"return root.{method}({encoded}); "
42
+ "})()"
43
+ )
44
+
45
+
46
+ class ElementHandle:
47
+ """A matched element's properties plus selector-scoped actions."""
48
+
49
+ def __init__(
50
+ self,
51
+ page: Page,
52
+ selector: str,
53
+ properties: Mapping[str, Any],
54
+ ) -> None:
55
+ self._page = page
56
+ self._selector = selector
57
+ self._properties = properties
58
+
59
+ @property
60
+ def inner_html(self) -> str | None:
61
+ return self._properties.get("innerHTML")
62
+
63
+ @property
64
+ def inner_text(self) -> str | None:
65
+ return self._properties.get("innerText")
66
+
67
+ @property
68
+ def id(self) -> str | None:
69
+ return self._properties.get("id")
70
+
71
+ @property
72
+ def class_name(self) -> str | None:
73
+ return self._properties.get("className")
74
+
75
+ @property
76
+ def local_name(self) -> str | None:
77
+ return self._properties.get("localName")
78
+
79
+ @property
80
+ def outer_html(self) -> str | None:
81
+ return self._properties.get("outerHTML")
82
+
83
+ @property
84
+ def child_element_count(self) -> int | None:
85
+ return self._properties.get("childElementCount")
86
+
87
+ @property
88
+ def selector(self) -> str:
89
+ return self._selector
90
+
91
+ async def click(self, **options: Unpack[ClickOptions]) -> ClickResponse:
92
+ return await self._page.click(self._selector, **options)
93
+
94
+ async def hover(self) -> HoverResponse:
95
+ return await self._page.hover(self._selector)
96
+
97
+ async def type(self, text: str, **options: Unpack[TypeOptions]) -> TypeResponse:
98
+ return await self._page.type(self._selector, text, **options)
99
+
100
+ async def select_option(self, value: str | Sequence[str]) -> SelectResponse:
101
+ return await self._page.select_option(self._selector, value)
102
+
103
+ async def screenshot(self, *, path: str | None = None) -> bytes:
104
+ options: dict[str, Any] = {"selector": self._selector}
105
+ if path is not None:
106
+ options["path"] = path
107
+ return await self._page.screenshot(**options)
108
+
109
+ async def text_content(self) -> str:
110
+ return await self._page.eval_on_selector(self._selector)
111
+
112
+ async def query_selector(self, selector: str) -> ElementHandle | None:
113
+ return await self._page.query_selector(
114
+ _scoped_selector(self._selector, selector)
115
+ )
116
+
117
+ async def query_selector_all(self, selector: str) -> list[ElementHandle]:
118
+ return await self._page.query_selector_all(
119
+ _scoped_selector(self._selector, selector, all_matches=True)
120
+ )
@@ -0,0 +1,134 @@
1
+ """Small insertion-ordered event emitter used by :class:`browserless_bap.Page`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import inspect
7
+ import logging
8
+ from collections.abc import Awaitable, Callable
9
+ from typing import Any, TypeAlias
10
+
11
+ Listener: TypeAlias = Callable[[Any], object]
12
+ CountChangeHook: TypeAlias = Callable[[str, int], None]
13
+ logger = logging.getLogger("browserless_bap")
14
+
15
+
16
+ class EventEmitter:
17
+ """An ordered, deduplicating emitter with async-listener support."""
18
+
19
+ def __init__(self, on_count_change: CountChangeHook | None = None) -> None:
20
+ self._listeners: dict[str, dict[Listener, None]] = {}
21
+ self._once_originals: dict[Listener, Listener] = {}
22
+ self._on_count_change = on_count_change
23
+ self._tasks: set[asyncio.Task[None]] = set()
24
+
25
+ def on(self, event: str, listener: Listener) -> EventEmitter:
26
+ listeners = self._listeners.setdefault(event, {})
27
+ previous = len(listeners)
28
+ listeners[listener] = None
29
+ if len(listeners) != previous:
30
+ self._notify_count(event, len(listeners))
31
+ return self
32
+
33
+ def off(self, event: str, listener: Listener) -> EventEmitter:
34
+ listeners = self._listeners.get(event)
35
+ if listeners is None:
36
+ return self
37
+ targets = [
38
+ candidate
39
+ for candidate in listeners
40
+ if candidate is listener or self._once_originals.get(candidate) is listener
41
+ ]
42
+ if not targets:
43
+ return self
44
+ for target in targets:
45
+ del listeners[target]
46
+ self._once_originals.pop(target, None)
47
+ count = len(listeners)
48
+ if not listeners:
49
+ del self._listeners[event]
50
+ self._notify_count(event, count)
51
+ return self
52
+
53
+ def once(self, event: str, listener: Listener) -> EventEmitter:
54
+ if any(
55
+ self._once_originals.get(candidate) is listener
56
+ for candidate in self._listeners.get(event, ())
57
+ ):
58
+ return self
59
+
60
+ def wrapper(payload: object) -> object:
61
+ # Remove before invocation so a re-entrant emit cannot fire twice.
62
+ self.off(event, wrapper)
63
+ return listener(payload)
64
+
65
+ self._once_originals[wrapper] = listener
66
+ return self.on(event, wrapper)
67
+
68
+ def emit(self, event: str, payload: object) -> bool:
69
+ listeners = self._listeners.get(event)
70
+ if not listeners:
71
+ return False
72
+ for listener in tuple(listeners):
73
+ try:
74
+ result = listener(payload)
75
+ except BaseException as exc:
76
+ self._route_listener_error(event, exc)
77
+ continue
78
+ if inspect.isawaitable(result):
79
+ self._schedule_listener(event, result)
80
+ return True
81
+
82
+ def listener_count(self, event: str) -> int:
83
+ return len(self._listeners.get(event, ()))
84
+
85
+ def remove_all_listeners(self, event: str | None = None) -> EventEmitter:
86
+ events = (event,) if event is not None else tuple(self._listeners)
87
+ for current in events:
88
+ if current in self._listeners:
89
+ for listener in self._listeners[current]:
90
+ self._once_originals.pop(listener, None)
91
+ del self._listeners[current]
92
+ self._notify_count(current, 0)
93
+ return self
94
+
95
+ def _notify_count(self, event: str, count: int) -> None:
96
+ if self._on_count_change is not None:
97
+ self._on_count_change(event, count)
98
+
99
+ def _schedule_listener(self, event: str, awaitable: Awaitable[object]) -> None:
100
+ async def run() -> None:
101
+ try:
102
+ await awaitable
103
+ except asyncio.CancelledError:
104
+ raise
105
+ except BaseException as exc:
106
+ self._route_listener_error(event, exc)
107
+
108
+ scheduled = run()
109
+ try:
110
+ task = asyncio.create_task(scheduled)
111
+ except RuntimeError:
112
+ scheduled.close()
113
+ if inspect.iscoroutine(awaitable):
114
+ awaitable.close()
115
+ self._route_listener_error(
116
+ event,
117
+ RuntimeError("Async event listener requires a running event loop"),
118
+ )
119
+ return
120
+ self._tasks.add(task)
121
+ task.add_done_callback(self._tasks.discard)
122
+
123
+ def _route_listener_error(self, source_event: str, error: BaseException) -> None:
124
+ if source_event == "error":
125
+ logger.error(
126
+ "Unhandled exception in bap error event listener",
127
+ exc_info=(type(error), error, error.__traceback__),
128
+ )
129
+ return
130
+ if not self.emit("error", error):
131
+ logger.error(
132
+ "Unhandled bap event listener exception",
133
+ exc_info=(type(error), error, error.__traceback__),
134
+ )
@@ -0,0 +1,64 @@
1
+ """Typed public exceptions raised by :mod:`browserless_bap`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import builtins
6
+ from collections.abc import Mapping, Sequence
7
+ from typing import ClassVar, Literal
8
+
9
+ ErrorCode = Literal["BQL", "CONNECTION", "TIMEOUT", "CLIENT"]
10
+
11
+
12
+ class BAPError(Exception):
13
+ """Base class for errors produced by the SDK."""
14
+
15
+ code: ClassVar[ErrorCode] = "CLIENT"
16
+
17
+
18
+ class BrowserQLError(BAPError):
19
+ """The GraphQL operation returned one or more errors."""
20
+
21
+ code = "BQL"
22
+
23
+ def __init__(self, errors: Sequence[Mapping[str, object]]) -> None:
24
+ self.errors = [dict(error) for error in errors]
25
+ message = "; ".join(
26
+ str(error.get("message", "Unknown BrowserQL error")) for error in errors
27
+ )
28
+ super().__init__(message or "Unknown BrowserQL error")
29
+
30
+
31
+ class ConnectionError(BAPError, builtins.ConnectionError):
32
+ """The BAP transport could not connect or disconnected."""
33
+
34
+ code = "CONNECTION"
35
+
36
+
37
+ class TimeoutError(BAPError, builtins.TimeoutError):
38
+ """A BAP operation exceeded its transport deadline."""
39
+
40
+ code = "TIMEOUT"
41
+
42
+ def __init__(self, operation: str, timeout_ms: float) -> None:
43
+ self.operation = operation
44
+ self.timeout_ms = timeout_ms
45
+ super().__init__(
46
+ f"Operation timed out after {timeout_ms:g}ms: {operation[:50]}"
47
+ )
48
+
49
+
50
+ class SchemaMismatchError(BAPError):
51
+ """The generated schema metadata and runtime call site disagree."""
52
+
53
+ code = "CLIENT"
54
+
55
+
56
+ class ValueError(BAPError, builtins.ValueError):
57
+ """A public SDK argument failed client-side validation."""
58
+
59
+ code = "CLIENT"
60
+
61
+
62
+ BAPConnectionError = ConnectionError
63
+ BAPTimeoutError = TimeoutError
64
+ BAPValueError = ValueError
@@ -0,0 +1,11 @@
1
+ from .builder import build_operation
2
+ from .mutations import ARG_TYPES, RESPONSE_FIELDS
3
+ from .subscriptions import SUBSCRIPTIONS, SubscriptionSpec
4
+
5
+ __all__ = [
6
+ "ARG_TYPES",
7
+ "RESPONSE_FIELDS",
8
+ "SUBSCRIPTIONS",
9
+ "SubscriptionSpec",
10
+ "build_operation",
11
+ ]
@@ -0,0 +1,37 @@
1
+ """Build parameterized GraphQL-over-WebSocket operations."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping
6
+ from typing import Literal
7
+
8
+ from ..errors import SchemaMismatchError
9
+
10
+
11
+ def build_operation(
12
+ name: str,
13
+ args: Mapping[str, object] | None,
14
+ fields: str,
15
+ arg_types: Mapping[str, str] | None = None,
16
+ operation: Literal["mutation", "subscription"] = "mutation",
17
+ ) -> tuple[str, dict[str, object]]:
18
+ provided = dict(args or {})
19
+ if not provided:
20
+ return f"{operation} {{ {name} {{ {fields} }} }}", {}
21
+
22
+ types = arg_types or {}
23
+ definitions: list[str] = []
24
+ for key in provided:
25
+ type_name = types.get(key)
26
+ if type_name is None:
27
+ raise SchemaMismatchError(
28
+ f'Missing GraphQL type for argument "{key}" of {operation} "{name}"'
29
+ )
30
+ definitions.append(f"${key}: {type_name}")
31
+ variables = ", ".join(definitions)
32
+ arguments = ", ".join(f"{key}: ${key}" for key in provided)
33
+ query = f"{operation}({variables}) {{ {name}({arguments}) {{ {fields} }} }}"
34
+ return query, provided
35
+
36
+
37
+ __all__ = ["build_operation"]