browserless-bap 0.2.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. browserless_bap-0.4.0/.release-please-manifest.json +3 -0
  2. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/AGENTS.md +12 -3
  3. browserless_bap-0.4.0/CHANGELOG.md +31 -0
  4. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/CONTRIBUTING.md +61 -8
  5. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/PKG-INFO +114 -10
  6. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/README.md +113 -9
  7. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/llms.txt +47 -1
  8. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/pyproject.toml +3 -0
  9. browserless_bap-0.4.0/schema.lock +5 -0
  10. browserless_bap-0.4.0/scripts/bap_ts_parity.py +124 -0
  11. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/check_public_text.py +9 -0
  12. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/config/client_only.py +10 -2
  13. browserless_bap-0.4.0/scripts/codegen/config/docs.py +61 -0
  14. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/config/methods.py +0 -2
  15. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/config/schema_map.py +7 -9
  16. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/emit_docs.py +5 -0
  17. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/emit_operations.py +21 -8
  18. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/emit_page.py +32 -8
  19. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/emit_responses.py +13 -2
  20. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/generate.py +12 -0
  21. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/model.py +11 -0
  22. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/schema.py +47 -7
  23. browserless_bap-0.4.0/scripts/sync_schema.py +366 -0
  24. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/__init__.py +0 -6
  25. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/_page_generated.py +87 -3
  26. browserless_bap-0.4.0/src/browserless_bap/_version.py +1 -0
  27. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/browser.py +17 -7
  28. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/browserless.py +7 -1
  29. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/element_handle.py +36 -30
  30. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/errors.py +20 -11
  31. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/graphql/__init__.py +4 -2
  32. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/graphql/builder.py +19 -2
  33. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/graphql/mutations.py +20 -5
  34. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/mutations.graphql +26 -1
  35. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/page.py +57 -38
  36. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/sync_api/_bridge.py +38 -14
  37. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/sync_api/_page_generated.py +56 -0
  38. browserless_bap-0.4.0/src/browserless_bap/sync_api/browser.py +85 -0
  39. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/sync_api/browserless.py +9 -4
  40. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/sync_api/element_handle.py +13 -5
  41. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/sync_api/page.py +59 -26
  42. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/transport.py +114 -53
  43. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/types/options.py +4 -0
  44. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/types/responses.py +2 -1
  45. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/e2e/test_config.py +1 -1
  46. browserless_bap-0.4.0/tests/e2e/test_live.py +320 -0
  47. browserless_bap-0.4.0/tests/fixtures/bap_ts_parity.json +524 -0
  48. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/sync/_server.py +15 -1
  49. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/sync/test_bridge.py +39 -0
  50. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/sync/test_sync_events.py +1 -3
  51. browserless_bap-0.4.0/tests/sync/test_sync_page.py +124 -0
  52. browserless_bap-0.4.0/tests/sync/test_wrappers.py +701 -0
  53. browserless_bap-0.4.0/tests/test_bap_ts_parity_script.py +123 -0
  54. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_browser.py +30 -3
  55. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_check_public_text.py +39 -0
  56. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_codegen_docs.py +10 -0
  57. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_codegen_operations.py +50 -8
  58. browserless_bap-0.4.0/tests/test_codegen_parity.py +202 -0
  59. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_codegen_schema.py +31 -2
  60. browserless_bap-0.4.0/tests/test_element_handle.py +60 -0
  61. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_errors.py +19 -8
  62. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_graphql_builder.py +19 -0
  63. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_live_complete.py +22 -21
  64. browserless_bap-0.4.0/tests/test_operation_timeouts.py +70 -0
  65. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_package.py +13 -2
  66. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_page_overrides.py +214 -17
  67. browserless_bap-0.4.0/tests/test_public_api.py +88 -0
  68. browserless_bap-0.4.0/tests/test_readme_typecheck.py +34 -0
  69. browserless_bap-0.4.0/tests/test_sync_schema.py +384 -0
  70. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_transport.py +46 -4
  71. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_transport_protocol.py +366 -6
  72. browserless_bap-0.2.0/schema.lock +0 -5
  73. browserless_bap-0.2.0/scripts/codegen/config/docs.py +0 -11
  74. browserless_bap-0.2.0/scripts/sync_schema.py +0 -223
  75. browserless_bap-0.2.0/src/browserless_bap/_version.py +0 -1
  76. browserless_bap-0.2.0/src/browserless_bap/sync_api/browser.py +0 -48
  77. browserless_bap-0.2.0/tests/e2e/test_live.py +0 -166
  78. browserless_bap-0.2.0/tests/sync/test_sync_page.py +0 -67
  79. browserless_bap-0.2.0/tests/sync/test_wrappers.py +0 -364
  80. browserless_bap-0.2.0/tests/test_codegen_parity.py +0 -45
  81. browserless_bap-0.2.0/tests/test_sync_schema.py +0 -93
  82. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/.gitignore +0 -0
  83. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/LICENSE +0 -0
  84. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/__init__.py +0 -0
  85. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/__init__.py +0 -0
  86. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/config/__init__.py +0 -0
  87. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/config/naming.py +0 -0
  88. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/emit_enums.py +0 -0
  89. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/emit_events.py +0 -0
  90. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/emit_inputs.py +0 -0
  91. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/emit_options.py +0 -0
  92. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/emit_types_init.py +0 -0
  93. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen/writer.py +0 -0
  94. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/codegen.py +0 -0
  95. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/scripts/docs.py +0 -0
  96. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/_codec.py +0 -0
  97. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/_io.py +0 -0
  98. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/_unset.py +0 -0
  99. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/async_api.py +0 -0
  100. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/emitter.py +0 -0
  101. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/graphql/subscriptions.py +0 -0
  102. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/py.typed +0 -0
  103. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/sync_api/__init__.py +0 -0
  104. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/sync_api/_base.py +0 -0
  105. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/types/__init__.py +0 -0
  106. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/types/enums.py +0 -0
  107. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/types/events.py +0 -0
  108. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/src/browserless_bap/types/inputs.py +0 -0
  109. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/e2e/__init__.py +0 -0
  110. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/e2e/config.py +0 -0
  111. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/e2e/conftest.py +0 -0
  112. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/sync/__init__.py +0 -0
  113. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/sync/test_parity.py +0 -0
  114. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_codegen_drift.py +0 -0
  115. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_codegen_edge_cases.py +0 -0
  116. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_emitter.py +0 -0
  117. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_io.py +0 -0
  118. {browserless_bap-0.2.0 → browserless_bap-0.4.0}/tests/test_page_events.py +0 -0
@@ -0,0 +1,3 @@
1
+ {
2
+ ".": "0.4.0"
3
+ }
@@ -22,8 +22,10 @@ To change generated output:
22
22
  2. Run `python scripts/codegen.py`.
23
23
  3. Run the drift check and commit the inputs and outputs together.
24
24
 
25
- `src/browserless_bap/_version.py` is hand-written. Hatch reads the package version from
26
- that file so installed wheels never need `pyproject.toml`.
25
+ `src/browserless_bap/_version.py` is the single version source. Hatch reads the package
26
+ version from that file so installed wheels never need `pyproject.toml`. release-please
27
+ bumps it (with `.release-please-manifest.json` and `CHANGELOG.md`) in its release pull
28
+ request; never edit the version or the changelog by hand.
27
29
 
28
30
  ## Runtime constraints
29
31
 
@@ -33,9 +35,16 @@ that file so installed wheels never need `pyproject.toml`.
33
35
  dictionaries retain GraphQL field names.
34
36
  - Transport clients must use `max_size=None`, `ping_interval=20`,
35
37
  `ping_timeout=None`, `open_timeout=None`, and `close_timeout=5`.
38
+ - Bound the whole WebSocket dial in `Transport._connect` with `asyncio.timeout`;
39
+ keep `open_timeout=None`. Use `connect_timeout` (defaulting to `timeout`) in
40
+ milliseconds; values at or below zero disable the deadline. Translate expiry
41
+ to the SDK `TimeoutError` with `operation == "connect"`.
42
+ - Apply the single 5000 ms client headroom for server-timeout mutations in
43
+ `Page._execute_operation`, not in individual methods. A connect deadline
44
+ expiring is terminal for that page's connection; retries require a new page.
36
45
  - Never block the asyncio loop with file I/O.
37
46
  - Keep strong references to background tasks until completion.
38
- - Sync callbacks run on the callback dispatcher, never the bridge loop.
47
+ - Sync callbacks run on their page's callback dispatcher, never the bridge loop.
39
48
 
40
49
  ## Commands
41
50
 
@@ -0,0 +1,31 @@
1
+ # Changelog
2
+
3
+ ## [0.4.0](https://github.com/browserless/bap-py/compare/v0.3.0...v0.4.0) (2026-11-19)
4
+
5
+
6
+ ### Features
7
+
8
+ * pair clicks with navigation waits ([#15](https://github.com/browserless/bap-py/issues/15)) ([ae7617e](https://github.com/browserless/bap-py/commit/ae7617e0409a1ac373b9cf434057b56a89aa76ea))
9
+
10
+ ## [0.3.0](https://github.com/browserless/bap-py/compare/v0.2.0...v0.3.0) (2026-11-13)
11
+
12
+
13
+ ### ⚠ BREAKING CHANGES
14
+
15
+ * `Page.query_selector()` and `Page.query_selector_all()` no longer fetch `innerHTML`/`outerHTML`; pass `html=True`. Reading `ElementHandle.inner_html` or `outer_html` on a handle queried without it raises `BAPValueError`. `Page.response()` no longer returns `body`; pass `body=True` (or `body_encoding=True`, which implies it). the exceptions `TimeoutError`, `ConnectionError` and `ValueError` are removed from `browserless_bap` and `browserless_bap.errors`; use `BAPTimeoutError`, `BAPConnectionError` and `BAPValueError` (they still subclass the matching built-in exceptions). `browserless_bap.graphql.RESPONSE_FIELDS` no longer has the `HTTPResponseWithRemoteMetadata` and `ResponseResponseWithBodyEncoding` keys; use `OPTIONAL_FIELDS` with `selection_for()`. `QuerySelectorResponse["childElementCount"]` is typed `int` (was `float`), and `browserless_bap.sync_api.Browserless.connect(transport=...)` is typed `TransportFactory | None` (was `Any`).
16
+ * Opening a page now times out after `connect_timeout` (default: the `timeout` value, 30000 ms). Pass `connect_timeout=0` to restore the previous unbounded wait.
17
+
18
+ ### Features
19
+
20
+ * bound connection time and harden the transport ([#9](https://github.com/browserless/bap-py/issues/9)) ([1689f3b](https://github.com/browserless/bap-py/commit/1689f3b77015edfad3a01f36e171955125cf9dc2))
21
+ * make element HTML and response bodies opt-in and rename builtin-shadowing errors ([#8](https://github.com/browserless/bap-py/issues/8)) ([bc80671](https://github.com/browserless/bap-py/commit/bc8067120d6fb981edee39862859a898cb070c9b))
22
+
23
+
24
+ ### Bug Fixes
25
+
26
+ * encode element handle selectors so nested and special-character queries work ([#6](https://github.com/browserless/bap-py/issues/6)) ([f22f12b](https://github.com/browserless/bap-py/commit/f22f12b0ec13fa3d993e9ff0f9ae4757931484a0))
27
+ * sync API listener delivery, wait_for_function predicates and parity checks ([#7](https://github.com/browserless/bap-py/issues/7)) ([e5a106d](https://github.com/browserless/bap-py/commit/e5a106d0dc4414284b912e28593aebef1dab4351))
28
+
29
+ ## 0.2.0 (2026-11-13)
30
+
31
+ First release on PyPI: `pip install browserless-bap`.
@@ -35,6 +35,8 @@ python -m venv /tmp/bap-wheel-smoke
35
35
  The live suite (`pytest -m e2e`) connects to a real Browserless BrowserQL
36
36
  endpoint and uses your account. It runs only when selected with `-m e2e` and is
37
37
  skipped when `BROWSERLESS_TOKEN` is unset.
38
+ The "Live E2E" workflow runs this suite nightly with a token stored on the
39
+ `live-e2e` environment.
38
40
  `BROWSERLESS_URL` defaults to `wss://production-sfo.browserless.io/chromium/bql`
39
41
  and may be any `ws://` or `wss://` BrowserQL endpoint, for example another
40
42
  region or a self-hosted server:
@@ -55,25 +57,43 @@ The integrity check is self-contained and needs no sibling repository:
55
57
  python scripts/sync_schema.py --check
56
58
  ```
57
59
 
58
- By default, syncing reads `../bap-ts/src/mutations.graphql` from a sibling
59
- checkout of the TypeScript SDK:
60
+ Syncing downloads `src/mutations.graphql` from a named `@browserless.io/bap-ts`
61
+ npm release (version 2.2.0 or later), verifies npm's integrity hash, and records
62
+ the resolved version and integrity hash in `schema.lock`. No Node.js or private
63
+ checkout is required:
60
64
 
61
65
  ```bash
62
- python scripts/sync_schema.py
66
+ python scripts/sync_schema.py --from-npm 2.2.0
67
+ python scripts/sync_schema.py --from-npm latest
63
68
  ```
64
69
 
65
- Contributors without that checkout can pass any schema file with `--schema`,
66
- for example `src/mutations.graphql` from the published `@browserless.io/bap-ts`
67
- npm package (version 2.2.0 or later):
70
+ For an unreleased schema, pass a schema file with `--schema`; its provenance
71
+ records only the file name:
68
72
 
69
73
  ```bash
70
- python scripts/sync_schema.py --from-bap-ts
71
- python scripts/sync_schema.py --schema /path/to/mutations.graphql
74
+ python scripts/sync_schema.py --schema mutations.graphql
72
75
  ```
73
76
 
77
+ A daily workflow opens a sync pull request when a newer npm release changes
78
+ the schema.
79
+
74
80
  Schema and codegen changes must include `schema.lock` and all regenerated
75
81
  files. Generated files and AUTOGEN regions must not be edited manually.
76
82
 
83
+ Code generation formats the generated Page modules with Ruff from the active
84
+ Python environment, so install the development dependencies before running it.
85
+ Ruff has a minimum version rather than an exact pin; use the same version when
86
+ comparing generated output across environments, and run the formatting and
87
+ codegen drift checks above before submitting changes.
88
+
89
+ Refresh the offline parity snapshot from the same published package version as
90
+ the schema, and commit `tests/fixtures/bap_ts_parity.json` with the schema:
91
+
92
+ ```bash
93
+ npm pack @browserless.io/bap-ts@<version>
94
+ python scripts/bap_ts_parity.py --package browserless.io-bap-ts-<version>.tgz
95
+ ```
96
+
77
97
  ## API reference
78
98
 
79
99
  The generated Python API reference is published at
@@ -89,6 +109,39 @@ with `python scripts/docs.py --output <directory>`, which writes Docusaurus
89
109
  - Include tests for behavior changes.
90
110
  - Do not publish packages or create release tags from a pull request branch.
91
111
 
112
+ ## Releases
113
+
114
+ Releases are automated with [release-please](https://github.com/googleapis/release-please).
115
+ Pull requests are squash-merged, so each PR title becomes one commit on `main`, and its
116
+ Conventional Commits type decides the next version and the changelog entry:
117
+
118
+ - `fix:` → patch release, listed under "Bug Fixes".
119
+ - `feat:` → minor release, listed under "Features".
120
+ - `feat!:`, or a `BREAKING CHANGE:` footer → while the version is `0.x`, a minor
121
+ release; from `1.0.0`, a major one.
122
+ - `docs:`, `test:`, `ci:`, `build:`, `chore:`, `refactor:`, `style:` → no release on
123
+ their own and hidden from the changelog.
124
+
125
+ release-please keeps one draft release pull request open against `main` with the next
126
+ version and changelog. A maintainer marks it ready and merges it; that creates the
127
+ GitHub Release and the `vX.Y.Z` tag, which runs `publish.yml` to upload to PyPI after a
128
+ maintainer approves the `pypi` deployment. After the upload, `publish.yml` posts the
129
+ release to the team's release channel through the `SLACK_RELEASES_WEBHOOK` secret; a
130
+ failed post does not fail the release. Do not edit `_version.py`,
131
+ `.release-please-manifest.json` or `CHANGELOG.md` by hand.
132
+
133
+ ### The `browserless` alias package
134
+
135
+ `meta/browserless` builds the `browserless` package on PyPI. It contains no code
136
+ and depends on `browserless-bap` without a version pin, so `pip install browserless`
137
+ installs the latest SDK when none is installed. Like any unpinned dependency, an
138
+ installed `browserless-bap` is kept as is; upgrade it with
139
+ `pip install --upgrade browserless-bap`. The alias does not need a release when the
140
+ SDK does. To
141
+ publish a change to it, bump its `version` in `meta/browserless/pyproject.toml`,
142
+ merge, then run the "Publish browserless alias" workflow from `main`; it uploads
143
+ after a maintainer approves the `pypi-alias` deployment.
144
+
92
145
  ## Public repository rules
93
146
 
94
147
  PR titles, descriptions, commit messages and review comments must not contain
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: browserless-bap
3
- Version: 0.2.0
3
+ Version: 0.4.0
4
4
  Summary: Python async and sync client for Browserless's Browser Automation Protocol
5
5
  Project-URL: Homepage, https://github.com/browserless/bap-py
6
6
  Project-URL: Documentation, https://docs.browserless.io/bap/python/reference
@@ -90,6 +90,72 @@ with bap.Browserless.connect(
90
90
  > there and replace `asyncio.run(run())` with `await run()`. The sync API
91
91
  > raises `RuntimeError` inside a running event loop.
92
92
 
93
+ ## Click-triggered navigation
94
+
95
+ For a click that loads a new document, pass `wait_until` to the click itself:
96
+
97
+ ```python
98
+ # Async API, using an existing page
99
+ result = await page.click("a", wait_until="networkIdle", timeout=30_000)
100
+ navigation = result.get("navigation")
101
+ if navigation is not None:
102
+ print(navigation["status"], navigation["url"])
103
+ ```
104
+
105
+ ```python
106
+ # Sync API, using an existing sync page
107
+ result = page.click("a", wait_until="networkIdle", timeout=30_000)
108
+ navigation = result.get("navigation")
109
+ if navigation is not None:
110
+ print(navigation["status"], navigation["url"])
111
+ ```
112
+
113
+ `wait_until` accepts `"load"`, `"domContentLoaded"`, or `"networkIdle"` and has no
114
+ default. The server starts waiting before pressing and shares one `timeout`
115
+ budget across finding the element and waiting for navigation. If the click does
116
+ not navigate, it fails with a timeout error. Do not pair a click with a separate
117
+ `wait_for_navigation()` call: a fast navigation can be missed between operations.
118
+
119
+ Omit `wait_until` for an ordinary click. The SDK then sends the same query as
120
+ before, without selecting `navigation`, and remains compatible with older servers.
121
+ Paired navigation requires a server supporting `click(waitUntil:)`; the optional
122
+ `navigation` response may be `None`. Same-document navigation (`pushState` or hash
123
+ changes) is not detected. For those interactions, click without `wait_until` and
124
+ wait for a destination element instead.
125
+
126
+ ## Logging
127
+
128
+ The SDK uses Python's `logging` module with the `browserless_bap` logger.
129
+ WebSocket frame logs use its child logger, `browserless_bap.websockets`;
130
+ setting the parent to `DEBUG` enables both SDK diagnostics and frame logs.
131
+
132
+ ```python
133
+ import logging
134
+
135
+ logging.basicConfig(level=logging.INFO)
136
+ logging.getLogger("browserless_bap").setLevel(logging.DEBUG)
137
+ ```
138
+
139
+ The `browserless_bap.websockets` logger redacts tokens and `Authorization` header
140
+ values. Frame logs can still contain page content and other application data;
141
+ review them before sharing.
142
+
143
+ ## Timeouts
144
+
145
+ Timeout values are in milliseconds. The default per-step `timeout` is `30000`.
146
+ For mutations with a server-side timeout, the client adds `5000` ms of headroom
147
+ once, allowing the server to return its timeout response before the client deadline.
148
+
149
+ `connect_timeout` defaults to `timeout` and bounds the entire WebSocket dial,
150
+ including connection setup and handshake. A value of `0` or less disables that
151
+ connection deadline. Connection timeouts raise the SDK's `browserless_bap.BAPTimeoutError`
152
+ with `operation == "connect"`.
153
+
154
+ A connect deadline expiring is terminal for that page's connection. To retry,
155
+ create a new page rather than reusing the timed-out page. These rules apply to
156
+ both the async and sync APIs. Live URL completion waits have their own timeout
157
+ behavior, described below.
158
+
93
159
  ## API methods
94
160
 
95
161
  This table is generated from the vendored GraphQL schema. Do not edit the
@@ -110,8 +176,8 @@ contents between the markers by hand.
110
176
  | `content` | `html` | `str` | ✅ |
111
177
  | `cookies` | `cookies` | `list[StandardCookie]` | ✅ |
112
178
  | `emulate_media` | `emulateMediaType` | `EmulateMediaTypeResponse` | ✅ |
113
- | `eval_on_selector` | `text` | `str` | ✅ |
114
- | `eval_on_selector_all` | `mapSelector` | `list[MapSelectorResponse]` | ✅ |
179
+ | `eval_on_selector` | `text` | `str` | — |
180
+ | `eval_on_selector_all` | `mapSelector` | `list[MapSelectorResponse]` | — |
115
181
  | `evaluate` | `evaluate` | `str \| None` | ✅ |
116
182
  | `fulfill` | `fulfill` | `FulfillResponse` | — |
117
183
  | `go_back` | `back` | `HTTPResponse \| None` | ✅ |
@@ -164,6 +230,26 @@ contents between the markers by hand.
164
230
 
165
231
  <!-- AUTOGEN:method-table END -->
166
232
 
233
+ ## Response keys and optional fields
234
+
235
+ Options and keyword arguments use `snake_case`; returned dictionaries keep the
236
+ server's field names (`liveURLId`, `httpOnly`, `childElementCount`), as Playwright
237
+ for Python does for cookies.
238
+
239
+ `query_selector()` and `query_selector_all()` fetch element HTML only with
240
+ `html=True`. Reading a handle's `inner_html` or `outer_html` without requesting it
241
+ raises `BAPValueError` with a hint. This also applies to element-scoped queries.
242
+ `response()` omits bodies by default; pass `body=True` to fetch them, or
243
+ `body_encoding=True` to fetch both the body and its `base64Encoded` flag.
244
+
245
+ `eval_on_selector()` returns the first matching element's text, and
246
+ `eval_on_selector_all()` returns element details. Unlike Playwright's methods,
247
+ neither accepts a page function.
248
+
249
+ SDK exceptions are `BAPTimeoutError`, `BAPConnectionError` and `BAPValueError`.
250
+ They still subclass Python's matching built-in exceptions; the builtin-named SDK
251
+ exports have been removed.
252
+
167
253
  ## Schema and generated code
168
254
 
169
255
  `src/browserless_bap/mutations.graphql` is the vendored GraphQL schema. Its full digest,
@@ -174,14 +260,21 @@ vendored schema without requiring any sibling checkout:
174
260
  python scripts/sync_schema.py --check
175
261
  ```
176
262
 
177
- By default, syncing reads the schema from a sibling checkout of the TypeScript
178
- SDK (`../bap-ts/src/mutations.graphql`). Any schema file can be selected with
179
- `--schema`, for example `src/mutations.graphql` from the `@browserless.io/bap-ts`
180
- npm package:
263
+ Syncing downloads `src/mutations.graphql` from a named `@browserless.io/bap-ts`
264
+ npm release (version 2.2.0 or later), verifies npm's integrity hash, and records
265
+ the resolved version and integrity hash in `schema.lock`. No Node.js or private
266
+ checkout is required:
267
+
268
+ ```bash
269
+ python scripts/sync_schema.py --from-npm 2.2.0
270
+ python scripts/sync_schema.py --from-npm latest
271
+ ```
272
+
273
+ For an unreleased schema, pass a schema file with `--schema`; its provenance
274
+ records only the file name:
181
275
 
182
276
  ```bash
183
- python scripts/sync_schema.py --from-bap-ts
184
- python scripts/sync_schema.py --schema /path/to/mutations.graphql
277
+ python scripts/sync_schema.py --schema mutations.graphql
185
278
  ```
186
279
 
187
280
  Generated Python modules are committed to git. Update the schema or generator,
@@ -232,7 +325,7 @@ card, import `LiveURLInstructions` from `browserless_bap.types`.
232
325
 
233
326
  The SDK subscribes before minting and retains completion until the next mint,
234
327
  so a quick completion is not lost between `live_url()` and `wait_for_live_complete()`.
235
- Wait timeouts are in milliseconds and raise the SDK `TimeoutError`. By default
328
+ Wait timeouts are in milliseconds and raise `BAPTimeoutError`. By default
236
329
  there is no client wait deadline; pass a positive timeout to bound the wait.
237
330
  `timeout=0` also disables the wait deadline. Timing out or cancelling a wait does
238
331
  not close the live URL.
@@ -262,3 +355,14 @@ resuming handoffs. Handoffs remain unavailable during this cutover. To roll back
262
355
  pause and drain again and restore both the previous server and previous clients;
263
356
  rolling back only one side leaves an incompatible pair. No mixed-version
264
357
  compatibility path is provided by this SDK.
358
+
359
+ ## Sync API events
360
+
361
+ Callbacks run on a background thread per page, in event order for that page.
362
+ A slow callback delays only its own page. Each page buffers up to 1,024 pending
363
+ callbacks; beyond that it drops the newest callback with a logged warning.
364
+ A `once` listener stays registered until one event is actually queued.
365
+ `browser.get_pages()` returns the same page objects, so `off()` works through any
366
+ reference to that page.
367
+ Register listeners before closing the page or browser; registering on a closed
368
+ object does not restart callback delivery.
@@ -55,6 +55,72 @@ with bap.Browserless.connect(
55
55
  > there and replace `asyncio.run(run())` with `await run()`. The sync API
56
56
  > raises `RuntimeError` inside a running event loop.
57
57
 
58
+ ## Click-triggered navigation
59
+
60
+ For a click that loads a new document, pass `wait_until` to the click itself:
61
+
62
+ ```python
63
+ # Async API, using an existing page
64
+ result = await page.click("a", wait_until="networkIdle", timeout=30_000)
65
+ navigation = result.get("navigation")
66
+ if navigation is not None:
67
+ print(navigation["status"], navigation["url"])
68
+ ```
69
+
70
+ ```python
71
+ # Sync API, using an existing sync page
72
+ result = page.click("a", wait_until="networkIdle", timeout=30_000)
73
+ navigation = result.get("navigation")
74
+ if navigation is not None:
75
+ print(navigation["status"], navigation["url"])
76
+ ```
77
+
78
+ `wait_until` accepts `"load"`, `"domContentLoaded"`, or `"networkIdle"` and has no
79
+ default. The server starts waiting before pressing and shares one `timeout`
80
+ budget across finding the element and waiting for navigation. If the click does
81
+ not navigate, it fails with a timeout error. Do not pair a click with a separate
82
+ `wait_for_navigation()` call: a fast navigation can be missed between operations.
83
+
84
+ Omit `wait_until` for an ordinary click. The SDK then sends the same query as
85
+ before, without selecting `navigation`, and remains compatible with older servers.
86
+ Paired navigation requires a server supporting `click(waitUntil:)`; the optional
87
+ `navigation` response may be `None`. Same-document navigation (`pushState` or hash
88
+ changes) is not detected. For those interactions, click without `wait_until` and
89
+ wait for a destination element instead.
90
+
91
+ ## Logging
92
+
93
+ The SDK uses Python's `logging` module with the `browserless_bap` logger.
94
+ WebSocket frame logs use its child logger, `browserless_bap.websockets`;
95
+ setting the parent to `DEBUG` enables both SDK diagnostics and frame logs.
96
+
97
+ ```python
98
+ import logging
99
+
100
+ logging.basicConfig(level=logging.INFO)
101
+ logging.getLogger("browserless_bap").setLevel(logging.DEBUG)
102
+ ```
103
+
104
+ The `browserless_bap.websockets` logger redacts tokens and `Authorization` header
105
+ values. Frame logs can still contain page content and other application data;
106
+ review them before sharing.
107
+
108
+ ## Timeouts
109
+
110
+ Timeout values are in milliseconds. The default per-step `timeout` is `30000`.
111
+ For mutations with a server-side timeout, the client adds `5000` ms of headroom
112
+ once, allowing the server to return its timeout response before the client deadline.
113
+
114
+ `connect_timeout` defaults to `timeout` and bounds the entire WebSocket dial,
115
+ including connection setup and handshake. A value of `0` or less disables that
116
+ connection deadline. Connection timeouts raise the SDK's `browserless_bap.BAPTimeoutError`
117
+ with `operation == "connect"`.
118
+
119
+ A connect deadline expiring is terminal for that page's connection. To retry,
120
+ create a new page rather than reusing the timed-out page. These rules apply to
121
+ both the async and sync APIs. Live URL completion waits have their own timeout
122
+ behavior, described below.
123
+
58
124
  ## API methods
59
125
 
60
126
  This table is generated from the vendored GraphQL schema. Do not edit the
@@ -75,8 +141,8 @@ contents between the markers by hand.
75
141
  | `content` | `html` | `str` | ✅ |
76
142
  | `cookies` | `cookies` | `list[StandardCookie]` | ✅ |
77
143
  | `emulate_media` | `emulateMediaType` | `EmulateMediaTypeResponse` | ✅ |
78
- | `eval_on_selector` | `text` | `str` | ✅ |
79
- | `eval_on_selector_all` | `mapSelector` | `list[MapSelectorResponse]` | ✅ |
144
+ | `eval_on_selector` | `text` | `str` | — |
145
+ | `eval_on_selector_all` | `mapSelector` | `list[MapSelectorResponse]` | — |
80
146
  | `evaluate` | `evaluate` | `str \| None` | ✅ |
81
147
  | `fulfill` | `fulfill` | `FulfillResponse` | — |
82
148
  | `go_back` | `back` | `HTTPResponse \| None` | ✅ |
@@ -129,6 +195,26 @@ contents between the markers by hand.
129
195
 
130
196
  <!-- AUTOGEN:method-table END -->
131
197
 
198
+ ## Response keys and optional fields
199
+
200
+ Options and keyword arguments use `snake_case`; returned dictionaries keep the
201
+ server's field names (`liveURLId`, `httpOnly`, `childElementCount`), as Playwright
202
+ for Python does for cookies.
203
+
204
+ `query_selector()` and `query_selector_all()` fetch element HTML only with
205
+ `html=True`. Reading a handle's `inner_html` or `outer_html` without requesting it
206
+ raises `BAPValueError` with a hint. This also applies to element-scoped queries.
207
+ `response()` omits bodies by default; pass `body=True` to fetch them, or
208
+ `body_encoding=True` to fetch both the body and its `base64Encoded` flag.
209
+
210
+ `eval_on_selector()` returns the first matching element's text, and
211
+ `eval_on_selector_all()` returns element details. Unlike Playwright's methods,
212
+ neither accepts a page function.
213
+
214
+ SDK exceptions are `BAPTimeoutError`, `BAPConnectionError` and `BAPValueError`.
215
+ They still subclass Python's matching built-in exceptions; the builtin-named SDK
216
+ exports have been removed.
217
+
132
218
  ## Schema and generated code
133
219
 
134
220
  `src/browserless_bap/mutations.graphql` is the vendored GraphQL schema. Its full digest,
@@ -139,14 +225,21 @@ vendored schema without requiring any sibling checkout:
139
225
  python scripts/sync_schema.py --check
140
226
  ```
141
227
 
142
- By default, syncing reads the schema from a sibling checkout of the TypeScript
143
- SDK (`../bap-ts/src/mutations.graphql`). Any schema file can be selected with
144
- `--schema`, for example `src/mutations.graphql` from the `@browserless.io/bap-ts`
145
- npm package:
228
+ Syncing downloads `src/mutations.graphql` from a named `@browserless.io/bap-ts`
229
+ npm release (version 2.2.0 or later), verifies npm's integrity hash, and records
230
+ the resolved version and integrity hash in `schema.lock`. No Node.js or private
231
+ checkout is required:
232
+
233
+ ```bash
234
+ python scripts/sync_schema.py --from-npm 2.2.0
235
+ python scripts/sync_schema.py --from-npm latest
236
+ ```
237
+
238
+ For an unreleased schema, pass a schema file with `--schema`; its provenance
239
+ records only the file name:
146
240
 
147
241
  ```bash
148
- python scripts/sync_schema.py --from-bap-ts
149
- python scripts/sync_schema.py --schema /path/to/mutations.graphql
242
+ python scripts/sync_schema.py --schema mutations.graphql
150
243
  ```
151
244
 
152
245
  Generated Python modules are committed to git. Update the schema or generator,
@@ -197,7 +290,7 @@ card, import `LiveURLInstructions` from `browserless_bap.types`.
197
290
 
198
291
  The SDK subscribes before minting and retains completion until the next mint,
199
292
  so a quick completion is not lost between `live_url()` and `wait_for_live_complete()`.
200
- Wait timeouts are in milliseconds and raise the SDK `TimeoutError`. By default
293
+ Wait timeouts are in milliseconds and raise `BAPTimeoutError`. By default
201
294
  there is no client wait deadline; pass a positive timeout to bound the wait.
202
295
  `timeout=0` also disables the wait deadline. Timing out or cancelling a wait does
203
296
  not close the live URL.
@@ -227,3 +320,14 @@ resuming handoffs. Handoffs remain unavailable during this cutover. To roll back
227
320
  pause and drain again and restore both the previous server and previous clients;
228
321
  rolling back only one side leaves an incompatible pair. No mixed-version
229
322
  compatibility path is provided by this SDK.
323
+
324
+ ## Sync API events
325
+
326
+ Callbacks run on a background thread per page, in event order for that page.
327
+ A slow callback delays only its own page. Each page buffers up to 1,024 pending
328
+ callbacks; beyond that it drops the newest callback with a logged warning.
329
+ A `once` listener stays registered until one event is actually queued.
330
+ `browser.get_pages()` returns the same page objects, so `off()` works through any
331
+ reference to that page.
332
+ Register listeners before closing the page or browser; registering on a closed
333
+ object does not restart callback delivery.
@@ -8,6 +8,35 @@
8
8
  - Browserless documentation: https://docs.browserless.io
9
9
  - GraphQL schema: `src/browserless_bap/mutations.graphql`
10
10
 
11
+ ## Logging
12
+
13
+ Use the Python logger `browserless_bap` for SDK diagnostics and its child
14
+ `browserless_bap.websockets` for WebSocket frame logs. Setting the parent to
15
+ `DEBUG` enables child frame logs too.
16
+
17
+ ```python
18
+ import logging
19
+ logging.basicConfig(level=logging.INFO)
20
+ logging.getLogger("browserless_bap").setLevel(logging.DEBUG)
21
+ ```
22
+
23
+ The `browserless_bap.websockets` logger redacts tokens and `Authorization` header
24
+ values. Frame logs can still contain page content and other application data;
25
+ review them before sharing.
26
+
27
+ ## Timeouts
28
+
29
+ All timeout values are milliseconds; the default per-step `timeout` is `30000`.
30
+ Mutations with server-side timeouts get `5000` ms of client headroom once.
31
+ `connect_timeout` defaults to `timeout`, bounds the entire WebSocket dial
32
+ (including setup and handshake), and is disabled by values of `0` or less.
33
+ Connection timeouts raise the SDK's `browserless_bap.BAPTimeoutError` with
34
+ `operation == "connect"`.
35
+
36
+ A connect deadline expiring is terminal for that page's connection; create a
37
+ new page to retry. These rules apply to both async and sync APIs. Live URL
38
+ completion waits have their own timeout behavior, described below.
39
+
11
40
  ## API methods
12
41
 
13
42
  <!-- AUTOGEN:method-list START -->
@@ -16,6 +45,23 @@ Generated Page methods: `add_cookies`, `add_script_tag`, `add_style_tag`, `authe
16
45
 
17
46
  <!-- AUTOGEN:method-list END -->
18
47
 
48
+ ## Response keys and optional fields
49
+
50
+ Options and keyword arguments use `snake_case`; returned dictionaries keep the
51
+ server's field names (`liveURLId`, `httpOnly`, `childElementCount`), as Playwright
52
+ for Python does for cookies.
53
+
54
+ `query_selector()` and `query_selector_all()` fetch element HTML only with
55
+ `html=True`, including element-scoped queries. Reading `inner_html` or
56
+ `outer_html` without requesting it raises `BAPValueError` with a fix hint.
57
+ `response()` omits bodies unless `body=True` or `body_encoding=True` (which implies
58
+ the body and adds `base64Encoded`).
59
+
60
+ `eval_on_selector()` returns text; `eval_on_selector_all()` returns element
61
+ details. Unlike Playwright's methods, neither accepts a page function.
62
+ SDK errors are `BAPTimeoutError`, `BAPConnectionError` and `BAPValueError`, still
63
+ subclassing the matching builtins; the builtin-named SDK exports are removed.
64
+
19
65
  ## Live URL handoffs
20
66
 
21
67
  ```python
@@ -55,7 +101,7 @@ card, import `LiveURLInstructions` from `browserless_bap.types`.
55
101
 
56
102
  The SDK subscribes before minting and retains completion until the next mint,
57
103
  so a quick completion is not lost between `live_url()` and `wait_for_live_complete()`.
58
- Wait timeouts are in milliseconds and raise the SDK `TimeoutError`. By default
104
+ Wait timeouts are in milliseconds and raise `BAPTimeoutError`. By default
59
105
  there is no client wait deadline; pass a positive timeout to bound the wait.
60
106
  `timeout=0` also disables the wait deadline. Timing out or cancelling a wait does
61
107
  not close the live URL.
@@ -49,7 +49,9 @@ path = "src/browserless_bap/_version.py"
49
49
 
50
50
  [tool.hatch.build.targets.sdist]
51
51
  include = [
52
+ "/.release-please-manifest.json",
52
53
  "/AGENTS.md",
54
+ "/CHANGELOG.md",
53
55
  "/CONTRIBUTING.md",
54
56
  "/LICENSE",
55
57
  "/README.md",
@@ -71,6 +73,7 @@ exclude = ["src/browserless_bap/mutations.graphql"]
71
73
  [tool.pytest.ini_options]
72
74
  addopts = "--timeout=60 --timeout-method=thread"
73
75
  asyncio_mode = "auto"
76
+ asyncio_default_fixture_loop_scope = "function"
74
77
  filterwarnings = ["error::RuntimeWarning"]
75
78
  markers = ["e2e: tests that require a live Browserless service"]
76
79
 
@@ -0,0 +1,5 @@
1
+ source_repo = "external"
2
+ source_path = "mutations.graphql"
3
+ source_commit = "external"
4
+ line_count = 5585
5
+ sha256 = "a4137d2366094a4f2c2b4042d0cc54c0799e4e6df494e11822cad3a722ee094d"