browserless-bap 0.2.0__tar.gz → 0.3.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 (116) hide show
  1. browserless_bap-0.3.0/.release-please-manifest.json +3 -0
  2. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/AGENTS.md +12 -3
  3. browserless_bap-0.3.0/CHANGELOG.md +24 -0
  4. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/CONTRIBUTING.md +47 -8
  5. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/PKG-INFO +81 -10
  6. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/README.md +80 -9
  7. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/llms.txt +47 -1
  8. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/pyproject.toml +3 -0
  9. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/schema.lock +3 -0
  10. browserless_bap-0.3.0/scripts/bap_ts_parity.py +124 -0
  11. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/check_public_text.py +9 -0
  12. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/config/client_only.py +10 -2
  13. browserless_bap-0.3.0/scripts/codegen/config/docs.py +55 -0
  14. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/config/methods.py +0 -2
  15. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/config/schema_map.py +5 -9
  16. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/emit_operations.py +13 -7
  17. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/emit_page.py +30 -8
  18. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/emit_responses.py +13 -2
  19. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/generate.py +12 -0
  20. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/model.py +9 -0
  21. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/schema.py +34 -7
  22. browserless_bap-0.3.0/scripts/sync_schema.py +366 -0
  23. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/__init__.py +0 -6
  24. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/_page_generated.py +80 -3
  25. browserless_bap-0.3.0/src/browserless_bap/_version.py +1 -0
  26. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/browser.py +17 -7
  27. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/browserless.py +7 -1
  28. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/element_handle.py +36 -30
  29. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/errors.py +20 -11
  30. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/graphql/__init__.py +4 -2
  31. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/graphql/builder.py +19 -2
  32. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/graphql/mutations.py +15 -4
  33. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/page.py +58 -38
  34. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/sync_api/_bridge.py +38 -14
  35. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/sync_api/_page_generated.py +54 -0
  36. browserless_bap-0.3.0/src/browserless_bap/sync_api/browser.py +85 -0
  37. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/sync_api/browserless.py +9 -4
  38. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/sync_api/element_handle.py +11 -5
  39. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/sync_api/page.py +60 -26
  40. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/transport.py +114 -53
  41. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/types/options.py +3 -0
  42. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/types/responses.py +1 -1
  43. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/e2e/test_config.py +1 -1
  44. browserless_bap-0.3.0/tests/e2e/test_live.py +320 -0
  45. browserless_bap-0.3.0/tests/fixtures/bap_ts_parity.json +520 -0
  46. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/sync/_server.py +4 -1
  47. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/sync/test_bridge.py +39 -0
  48. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/sync/test_sync_events.py +1 -3
  49. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/sync/test_sync_page.py +38 -7
  50. browserless_bap-0.3.0/tests/sync/test_wrappers.py +701 -0
  51. browserless_bap-0.3.0/tests/test_bap_ts_parity_script.py +123 -0
  52. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_browser.py +30 -3
  53. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_check_public_text.py +39 -0
  54. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_codegen_operations.py +10 -8
  55. browserless_bap-0.3.0/tests/test_codegen_parity.py +202 -0
  56. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_codegen_schema.py +30 -1
  57. browserless_bap-0.3.0/tests/test_element_handle.py +60 -0
  58. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_errors.py +19 -8
  59. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_graphql_builder.py +19 -0
  60. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_live_complete.py +22 -21
  61. browserless_bap-0.3.0/tests/test_operation_timeouts.py +70 -0
  62. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_package.py +13 -2
  63. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_page_overrides.py +162 -17
  64. browserless_bap-0.3.0/tests/test_public_api.py +88 -0
  65. browserless_bap-0.3.0/tests/test_readme_typecheck.py +34 -0
  66. browserless_bap-0.3.0/tests/test_sync_schema.py +384 -0
  67. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_transport.py +46 -4
  68. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_transport_protocol.py +366 -6
  69. browserless_bap-0.2.0/scripts/codegen/config/docs.py +0 -11
  70. browserless_bap-0.2.0/scripts/sync_schema.py +0 -223
  71. browserless_bap-0.2.0/src/browserless_bap/_version.py +0 -1
  72. browserless_bap-0.2.0/src/browserless_bap/sync_api/browser.py +0 -48
  73. browserless_bap-0.2.0/tests/e2e/test_live.py +0 -166
  74. browserless_bap-0.2.0/tests/sync/test_wrappers.py +0 -364
  75. browserless_bap-0.2.0/tests/test_codegen_parity.py +0 -45
  76. browserless_bap-0.2.0/tests/test_sync_schema.py +0 -93
  77. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/.gitignore +0 -0
  78. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/LICENSE +0 -0
  79. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/__init__.py +0 -0
  80. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/__init__.py +0 -0
  81. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/config/__init__.py +0 -0
  82. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/config/naming.py +0 -0
  83. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/emit_docs.py +0 -0
  84. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/emit_enums.py +0 -0
  85. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/emit_events.py +0 -0
  86. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/emit_inputs.py +0 -0
  87. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/emit_options.py +0 -0
  88. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/emit_types_init.py +0 -0
  89. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen/writer.py +0 -0
  90. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/codegen.py +0 -0
  91. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/scripts/docs.py +0 -0
  92. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/_codec.py +0 -0
  93. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/_io.py +0 -0
  94. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/_unset.py +0 -0
  95. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/async_api.py +0 -0
  96. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/emitter.py +0 -0
  97. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/graphql/subscriptions.py +0 -0
  98. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/mutations.graphql +0 -0
  99. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/py.typed +0 -0
  100. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/sync_api/__init__.py +0 -0
  101. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/sync_api/_base.py +0 -0
  102. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/types/__init__.py +0 -0
  103. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/types/enums.py +0 -0
  104. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/types/events.py +0 -0
  105. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/src/browserless_bap/types/inputs.py +0 -0
  106. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/e2e/__init__.py +0 -0
  107. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/e2e/config.py +0 -0
  108. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/e2e/conftest.py +0 -0
  109. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/sync/__init__.py +0 -0
  110. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/sync/test_parity.py +0 -0
  111. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_codegen_docs.py +0 -0
  112. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_codegen_drift.py +0 -0
  113. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_codegen_edge_cases.py +0 -0
  114. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_emitter.py +0 -0
  115. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_io.py +0 -0
  116. {browserless_bap-0.2.0 → browserless_bap-0.3.0}/tests/test_page_events.py +0 -0
@@ -0,0 +1,3 @@
1
+ {
2
+ ".": "0.3.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,24 @@
1
+ # Changelog
2
+
3
+ ## [0.3.0](https://github.com/browserless/bap-py/compare/v0.2.0...v0.3.0) (2026-11-13)
4
+
5
+
6
+ ### ⚠ BREAKING CHANGES
7
+
8
+ * `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`).
9
+ * 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.
10
+
11
+ ### Features
12
+
13
+ * 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))
14
+ * 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))
15
+
16
+
17
+ ### Bug Fixes
18
+
19
+ * 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))
20
+ * 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))
21
+
22
+ ## 0.2.0 (2026-11-13)
23
+
24
+ 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,25 @@ 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. Do not edit `_version.py`,
129
+ `.release-please-manifest.json` or `CHANGELOG.md` by hand.
130
+
92
131
  ## Public repository rules
93
132
 
94
133
  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.3.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,39 @@ 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
+ ## Logging
94
+
95
+ The SDK uses Python's `logging` module with the `browserless_bap` logger.
96
+ WebSocket frame logs use its child logger, `browserless_bap.websockets`;
97
+ setting the parent to `DEBUG` enables both SDK diagnostics and frame logs.
98
+
99
+ ```python
100
+ import logging
101
+
102
+ logging.basicConfig(level=logging.INFO)
103
+ logging.getLogger("browserless_bap").setLevel(logging.DEBUG)
104
+ ```
105
+
106
+ The `browserless_bap.websockets` logger redacts tokens and `Authorization` header
107
+ values. Frame logs can still contain page content and other application data;
108
+ review them before sharing.
109
+
110
+ ## Timeouts
111
+
112
+ Timeout values are in milliseconds. The default per-step `timeout` is `30000`.
113
+ For mutations with a server-side timeout, the client adds `5000` ms of headroom
114
+ once, allowing the server to return its timeout response before the client deadline.
115
+
116
+ `connect_timeout` defaults to `timeout` and bounds the entire WebSocket dial,
117
+ including connection setup and handshake. A value of `0` or less disables that
118
+ connection deadline. Connection timeouts raise the SDK's `browserless_bap.BAPTimeoutError`
119
+ with `operation == "connect"`.
120
+
121
+ A connect deadline expiring is terminal for that page's connection. To retry,
122
+ create a new page rather than reusing the timed-out page. These rules apply to
123
+ both the async and sync APIs. Live URL completion waits have their own timeout
124
+ behavior, described below.
125
+
93
126
  ## API methods
94
127
 
95
128
  This table is generated from the vendored GraphQL schema. Do not edit the
@@ -110,8 +143,8 @@ contents between the markers by hand.
110
143
  | `content` | `html` | `str` | ✅ |
111
144
  | `cookies` | `cookies` | `list[StandardCookie]` | ✅ |
112
145
  | `emulate_media` | `emulateMediaType` | `EmulateMediaTypeResponse` | ✅ |
113
- | `eval_on_selector` | `text` | `str` | ✅ |
114
- | `eval_on_selector_all` | `mapSelector` | `list[MapSelectorResponse]` | ✅ |
146
+ | `eval_on_selector` | `text` | `str` | — |
147
+ | `eval_on_selector_all` | `mapSelector` | `list[MapSelectorResponse]` | — |
115
148
  | `evaluate` | `evaluate` | `str \| None` | ✅ |
116
149
  | `fulfill` | `fulfill` | `FulfillResponse` | — |
117
150
  | `go_back` | `back` | `HTTPResponse \| None` | ✅ |
@@ -164,6 +197,26 @@ contents between the markers by hand.
164
197
 
165
198
  <!-- AUTOGEN:method-table END -->
166
199
 
200
+ ## Response keys and optional fields
201
+
202
+ Options and keyword arguments use `snake_case`; returned dictionaries keep the
203
+ server's field names (`liveURLId`, `httpOnly`, `childElementCount`), as Playwright
204
+ for Python does for cookies.
205
+
206
+ `query_selector()` and `query_selector_all()` fetch element HTML only with
207
+ `html=True`. Reading a handle's `inner_html` or `outer_html` without requesting it
208
+ raises `BAPValueError` with a hint. This also applies to element-scoped queries.
209
+ `response()` omits bodies by default; pass `body=True` to fetch them, or
210
+ `body_encoding=True` to fetch both the body and its `base64Encoded` flag.
211
+
212
+ `eval_on_selector()` returns the first matching element's text, and
213
+ `eval_on_selector_all()` returns element details. Unlike Playwright's methods,
214
+ neither accepts a page function.
215
+
216
+ SDK exceptions are `BAPTimeoutError`, `BAPConnectionError` and `BAPValueError`.
217
+ They still subclass Python's matching built-in exceptions; the builtin-named SDK
218
+ exports have been removed.
219
+
167
220
  ## Schema and generated code
168
221
 
169
222
  `src/browserless_bap/mutations.graphql` is the vendored GraphQL schema. Its full digest,
@@ -174,14 +227,21 @@ vendored schema without requiring any sibling checkout:
174
227
  python scripts/sync_schema.py --check
175
228
  ```
176
229
 
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:
230
+ Syncing downloads `src/mutations.graphql` from a named `@browserless.io/bap-ts`
231
+ npm release (version 2.2.0 or later), verifies npm's integrity hash, and records
232
+ the resolved version and integrity hash in `schema.lock`. No Node.js or private
233
+ checkout is required:
181
234
 
182
235
  ```bash
183
- python scripts/sync_schema.py --from-bap-ts
184
- python scripts/sync_schema.py --schema /path/to/mutations.graphql
236
+ python scripts/sync_schema.py --from-npm 2.2.0
237
+ python scripts/sync_schema.py --from-npm latest
238
+ ```
239
+
240
+ For an unreleased schema, pass a schema file with `--schema`; its provenance
241
+ records only the file name:
242
+
243
+ ```bash
244
+ python scripts/sync_schema.py --schema mutations.graphql
185
245
  ```
186
246
 
187
247
  Generated Python modules are committed to git. Update the schema or generator,
@@ -232,7 +292,7 @@ card, import `LiveURLInstructions` from `browserless_bap.types`.
232
292
 
233
293
  The SDK subscribes before minting and retains completion until the next mint,
234
294
  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
295
+ Wait timeouts are in milliseconds and raise `BAPTimeoutError`. By default
236
296
  there is no client wait deadline; pass a positive timeout to bound the wait.
237
297
  `timeout=0` also disables the wait deadline. Timing out or cancelling a wait does
238
298
  not close the live URL.
@@ -262,3 +322,14 @@ resuming handoffs. Handoffs remain unavailable during this cutover. To roll back
262
322
  pause and drain again and restore both the previous server and previous clients;
263
323
  rolling back only one side leaves an incompatible pair. No mixed-version
264
324
  compatibility path is provided by this SDK.
325
+
326
+ ## Sync API events
327
+
328
+ Callbacks run on a background thread per page, in event order for that page.
329
+ A slow callback delays only its own page. Each page buffers up to 1,024 pending
330
+ callbacks; beyond that it drops the newest callback with a logged warning.
331
+ A `once` listener stays registered until one event is actually queued.
332
+ `browser.get_pages()` returns the same page objects, so `off()` works through any
333
+ reference to that page.
334
+ Register listeners before closing the page or browser; registering on a closed
335
+ object does not restart callback delivery.
@@ -55,6 +55,39 @@ 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
+ ## Logging
59
+
60
+ The SDK uses Python's `logging` module with the `browserless_bap` logger.
61
+ WebSocket frame logs use its child logger, `browserless_bap.websockets`;
62
+ setting the parent to `DEBUG` enables both SDK diagnostics and frame logs.
63
+
64
+ ```python
65
+ import logging
66
+
67
+ logging.basicConfig(level=logging.INFO)
68
+ logging.getLogger("browserless_bap").setLevel(logging.DEBUG)
69
+ ```
70
+
71
+ The `browserless_bap.websockets` logger redacts tokens and `Authorization` header
72
+ values. Frame logs can still contain page content and other application data;
73
+ review them before sharing.
74
+
75
+ ## Timeouts
76
+
77
+ Timeout values are in milliseconds. The default per-step `timeout` is `30000`.
78
+ For mutations with a server-side timeout, the client adds `5000` ms of headroom
79
+ once, allowing the server to return its timeout response before the client deadline.
80
+
81
+ `connect_timeout` defaults to `timeout` and bounds the entire WebSocket dial,
82
+ including connection setup and handshake. A value of `0` or less disables that
83
+ connection deadline. Connection timeouts raise the SDK's `browserless_bap.BAPTimeoutError`
84
+ with `operation == "connect"`.
85
+
86
+ A connect deadline expiring is terminal for that page's connection. To retry,
87
+ create a new page rather than reusing the timed-out page. These rules apply to
88
+ both the async and sync APIs. Live URL completion waits have their own timeout
89
+ behavior, described below.
90
+
58
91
  ## API methods
59
92
 
60
93
  This table is generated from the vendored GraphQL schema. Do not edit the
@@ -75,8 +108,8 @@ contents between the markers by hand.
75
108
  | `content` | `html` | `str` | ✅ |
76
109
  | `cookies` | `cookies` | `list[StandardCookie]` | ✅ |
77
110
  | `emulate_media` | `emulateMediaType` | `EmulateMediaTypeResponse` | ✅ |
78
- | `eval_on_selector` | `text` | `str` | ✅ |
79
- | `eval_on_selector_all` | `mapSelector` | `list[MapSelectorResponse]` | ✅ |
111
+ | `eval_on_selector` | `text` | `str` | — |
112
+ | `eval_on_selector_all` | `mapSelector` | `list[MapSelectorResponse]` | — |
80
113
  | `evaluate` | `evaluate` | `str \| None` | ✅ |
81
114
  | `fulfill` | `fulfill` | `FulfillResponse` | — |
82
115
  | `go_back` | `back` | `HTTPResponse \| None` | ✅ |
@@ -129,6 +162,26 @@ contents between the markers by hand.
129
162
 
130
163
  <!-- AUTOGEN:method-table END -->
131
164
 
165
+ ## Response keys and optional fields
166
+
167
+ Options and keyword arguments use `snake_case`; returned dictionaries keep the
168
+ server's field names (`liveURLId`, `httpOnly`, `childElementCount`), as Playwright
169
+ for Python does for cookies.
170
+
171
+ `query_selector()` and `query_selector_all()` fetch element HTML only with
172
+ `html=True`. Reading a handle's `inner_html` or `outer_html` without requesting it
173
+ raises `BAPValueError` with a hint. This also applies to element-scoped queries.
174
+ `response()` omits bodies by default; pass `body=True` to fetch them, or
175
+ `body_encoding=True` to fetch both the body and its `base64Encoded` flag.
176
+
177
+ `eval_on_selector()` returns the first matching element's text, and
178
+ `eval_on_selector_all()` returns element details. Unlike Playwright's methods,
179
+ neither accepts a page function.
180
+
181
+ SDK exceptions are `BAPTimeoutError`, `BAPConnectionError` and `BAPValueError`.
182
+ They still subclass Python's matching built-in exceptions; the builtin-named SDK
183
+ exports have been removed.
184
+
132
185
  ## Schema and generated code
133
186
 
134
187
  `src/browserless_bap/mutations.graphql` is the vendored GraphQL schema. Its full digest,
@@ -139,14 +192,21 @@ vendored schema without requiring any sibling checkout:
139
192
  python scripts/sync_schema.py --check
140
193
  ```
141
194
 
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:
195
+ Syncing downloads `src/mutations.graphql` from a named `@browserless.io/bap-ts`
196
+ npm release (version 2.2.0 or later), verifies npm's integrity hash, and records
197
+ the resolved version and integrity hash in `schema.lock`. No Node.js or private
198
+ checkout is required:
146
199
 
147
200
  ```bash
148
- python scripts/sync_schema.py --from-bap-ts
149
- python scripts/sync_schema.py --schema /path/to/mutations.graphql
201
+ python scripts/sync_schema.py --from-npm 2.2.0
202
+ python scripts/sync_schema.py --from-npm latest
203
+ ```
204
+
205
+ For an unreleased schema, pass a schema file with `--schema`; its provenance
206
+ records only the file name:
207
+
208
+ ```bash
209
+ python scripts/sync_schema.py --schema mutations.graphql
150
210
  ```
151
211
 
152
212
  Generated Python modules are committed to git. Update the schema or generator,
@@ -197,7 +257,7 @@ card, import `LiveURLInstructions` from `browserless_bap.types`.
197
257
 
198
258
  The SDK subscribes before minting and retains completion until the next mint,
199
259
  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
260
+ Wait timeouts are in milliseconds and raise `BAPTimeoutError`. By default
201
261
  there is no client wait deadline; pass a positive timeout to bound the wait.
202
262
  `timeout=0` also disables the wait deadline. Timing out or cancelling a wait does
203
263
  not close the live URL.
@@ -227,3 +287,14 @@ resuming handoffs. Handoffs remain unavailable during this cutover. To roll back
227
287
  pause and drain again and restore both the previous server and previous clients;
228
288
  rolling back only one side leaves an incompatible pair. No mixed-version
229
289
  compatibility path is provided by this SDK.
290
+
291
+ ## Sync API events
292
+
293
+ Callbacks run on a background thread per page, in event order for that page.
294
+ A slow callback delays only its own page. Each page buffers up to 1,024 pending
295
+ callbacks; beyond that it drops the newest callback with a logged warning.
296
+ A `once` listener stays registered until one event is actually queued.
297
+ `browser.get_pages()` returns the same page objects, so `off()` works through any
298
+ reference to that page.
299
+ Register listeners before closing the page or browser; registering on a closed
300
+ 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
 
@@ -1,5 +1,8 @@
1
1
  source_repo = "browserless/bap-ts"
2
2
  source_path = "src/mutations.graphql"
3
3
  source_commit = "7feae20db98f226b2db7be28a2cd43f32e67dde7"
4
+ npm_package = "@browserless.io/bap-ts"
5
+ npm_version = "2.2.0"
6
+ npm_integrity = "sha512-0UJD0uVTp05s34BHEXNMFtJNvZqPn1IpqmgWvj3dbQWYIEWFGhZXF/YcgsyioG39rJY+5LFAXcDneo8X56NBYg=="
4
7
  line_count = 5560
5
8
  sha256 = "56c404249f64c9e3f781e7b5035c0ff98f9437c42541660b4f2dc7f8f42bdbde"
@@ -0,0 +1,124 @@
1
+ #!/usr/bin/env python3
2
+ """Extract an offline parity snapshot from the published bap-ts npm package."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import difflib
8
+ import json
9
+ import re
10
+ import sys
11
+ import tarfile
12
+ from collections.abc import Callable
13
+ from hashlib import sha256
14
+ from pathlib import Path
15
+ from typing import Any
16
+
17
+ TARGET = Path(__file__).resolve().parents[1] / "tests/fixtures/bap_ts_parity.json"
18
+ PACKAGE = "@browserless.io/bap-ts"
19
+
20
+
21
+ def extract(read: Callable[[str], bytes]) -> dict[str, Any]:
22
+ metadata = json.loads(read("package.json"))
23
+ if metadata.get("name") != PACKAGE:
24
+ raise ValueError(f"Expected package {PACKAGE}")
25
+ js = read("dist/graphql/mutations.js").decode("utf-8")
26
+
27
+ def table(name: str, *, nested: bool = False) -> dict[str, Any]:
28
+ block = re.search(rf"export const {name.upper()} = {{(.*?)\n}};", js, re.S)
29
+ if not block:
30
+ raise ValueError(f"Missing table: {name}")
31
+ if nested:
32
+ result = {
33
+ key: dict(re.findall(r"(\w+): '([^']*)'", values))
34
+ for key, values in re.findall(r"^\s+(\w+): \{(.*)\},?$", block[1], re.M)
35
+ }
36
+ else:
37
+ result = dict(re.findall(r"^\s+(\w+): '([^']*)',", block[1], re.M))
38
+ if not result:
39
+ raise ValueError(f"Empty table: {name}")
40
+ return result
41
+
42
+ readme = read("README.md").decode("utf-8")
43
+ block = re.search(
44
+ r"<!-- AUTOGEN:method-table START -->(.*?)<!-- AUTOGEN:method-table END -->",
45
+ readme,
46
+ re.S,
47
+ )
48
+ methods = sorted(re.findall(r"^\| `([^`]+)` \|", block[1] if block else "", re.M))
49
+ if not methods:
50
+ raise ValueError("Empty table: methods")
51
+ cushioned = sorted(
52
+ {
53
+ name
54
+ for file in ("dist/page-generated.js", "dist/page.js")
55
+ for name, remainder in re.findall(
56
+ r"this\.execute\(\s*'(\w+)'(.*?)\);\n",
57
+ read(file).decode("utf-8"),
58
+ re.S,
59
+ )
60
+ if "this.transportTimeout(" in remainder
61
+ }
62
+ )
63
+ if not cushioned:
64
+ raise ValueError("Empty table: cushioned_mutations")
65
+ return {
66
+ "package": metadata["name"],
67
+ "version": metadata["version"],
68
+ "schema_sha256": sha256(read("src/mutations.graphql")).hexdigest(),
69
+ "methods": methods,
70
+ "response_fields": table("response_fields"),
71
+ "optional_fields": table("optional_fields", nested=True),
72
+ "arg_types": table("arg_types", nested=True),
73
+ "cushioned_mutations": cushioned,
74
+ }
75
+
76
+
77
+ def snapshot(package: Path) -> dict[str, Any]:
78
+ if package.is_dir():
79
+ return extract(lambda name: (package / name).read_bytes())
80
+ with tarfile.open(package, "r:*") as archive:
81
+
82
+ def read(name: str) -> bytes:
83
+ member = archive.extractfile(f"package/{name}")
84
+ if member is None:
85
+ raise ValueError(f"Missing package file: {name}")
86
+ with member:
87
+ return member.read()
88
+
89
+ return extract(read)
90
+
91
+
92
+ def main() -> int:
93
+ parser = argparse.ArgumentParser(description=__doc__)
94
+ parser.add_argument("--package", type=Path, required=True)
95
+ parser.add_argument("--check", action="store_true")
96
+ args = parser.parse_args()
97
+ try:
98
+ rendered = json.dumps(snapshot(args.package), sort_keys=True, indent=2) + "\n"
99
+ if args.check:
100
+ current = TARGET.read_text(encoding="utf-8") if TARGET.exists() else ""
101
+ if current != rendered:
102
+ print(
103
+ "".join(
104
+ difflib.unified_diff(
105
+ current.splitlines(keepends=True),
106
+ rendered.splitlines(keepends=True),
107
+ fromfile="committed snapshot",
108
+ tofile="package snapshot",
109
+ )
110
+ ),
111
+ end="",
112
+ )
113
+ return 1
114
+ else:
115
+ TARGET.parent.mkdir(parents=True, exist_ok=True)
116
+ TARGET.write_text(rendered, encoding="utf-8")
117
+ except (OSError, ValueError, KeyError, tarfile.TarError) as error:
118
+ print(f"Parity extraction failed: {error}", file=sys.stderr)
119
+ return 1
120
+ return 0
121
+
122
+
123
+ if __name__ == "__main__":
124
+ raise SystemExit(main())
@@ -17,10 +17,19 @@ INTERNAL_HOST = re.compile(
17
17
  r"linear\.app\b|ampcode\.com/threads|slack\.com|devin\.ai|usepylon\.com",
18
18
  re.IGNORECASE,
19
19
  )
20
+ # The code review bot adds a badge to every PR description. Only the badge's exact
21
+ # review link and image URLs are exempt; anything else on that host still fails,
22
+ # and nothing may follow them (no query strings or extra path segments).
23
+ PUBLIC_BOT_LINK = re.compile(
24
+ r"https://app\.devin\.ai/review/browserless/bap-py/pull/\d+(?![\w/.?#&=%-])"
25
+ r"|https://static\.devin\.ai/assets/gh-devin-review-(?:dark|light)\.svg"
26
+ r"(?:\?v=\d+)?(?![\w/.?#&=%-])"
27
+ )
20
28
  TITLE_ONLY_AUTHORS: frozenset[str] = frozenset({"dependabot[bot]"})
21
29
 
22
30
 
23
31
  def find_violations(text: str) -> list[str]:
32
+ text = PUBLIC_BOT_LINK.sub("", text)
24
33
  tickets = [
25
34
  match.group(0)
26
35
  for match in TICKET_ID.finditer(text)