browserless-bap 0.2.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.
- browserless_bap-0.2.0/.gitignore +26 -0
- browserless_bap-0.2.0/AGENTS.md +69 -0
- browserless_bap-0.2.0/CONTRIBUTING.md +118 -0
- browserless_bap-0.2.0/LICENSE +21 -0
- browserless_bap-0.2.0/PKG-INFO +264 -0
- browserless_bap-0.2.0/README.md +229 -0
- browserless_bap-0.2.0/llms.txt +87 -0
- browserless_bap-0.2.0/pyproject.toml +97 -0
- browserless_bap-0.2.0/schema.lock +5 -0
- browserless_bap-0.2.0/scripts/__init__.py +1 -0
- browserless_bap-0.2.0/scripts/check_public_text.py +68 -0
- browserless_bap-0.2.0/scripts/codegen/__init__.py +5 -0
- browserless_bap-0.2.0/scripts/codegen/config/__init__.py +1 -0
- browserless_bap-0.2.0/scripts/codegen/config/client_only.py +45 -0
- browserless_bap-0.2.0/scripts/codegen/config/docs.py +11 -0
- browserless_bap-0.2.0/scripts/codegen/config/methods.py +199 -0
- browserless_bap-0.2.0/scripts/codegen/config/naming.py +44 -0
- browserless_bap-0.2.0/scripts/codegen/config/schema_map.py +46 -0
- browserless_bap-0.2.0/scripts/codegen/emit_docs.py +396 -0
- browserless_bap-0.2.0/scripts/codegen/emit_enums.py +37 -0
- browserless_bap-0.2.0/scripts/codegen/emit_events.py +153 -0
- browserless_bap-0.2.0/scripts/codegen/emit_inputs.py +45 -0
- browserless_bap-0.2.0/scripts/codegen/emit_operations.py +47 -0
- browserless_bap-0.2.0/scripts/codegen/emit_options.py +57 -0
- browserless_bap-0.2.0/scripts/codegen/emit_page.py +262 -0
- browserless_bap-0.2.0/scripts/codegen/emit_responses.py +49 -0
- browserless_bap-0.2.0/scripts/codegen/emit_types_init.py +20 -0
- browserless_bap-0.2.0/scripts/codegen/generate.py +64 -0
- browserless_bap-0.2.0/scripts/codegen/model.py +189 -0
- browserless_bap-0.2.0/scripts/codegen/schema.py +280 -0
- browserless_bap-0.2.0/scripts/codegen/writer.py +35 -0
- browserless_bap-0.2.0/scripts/codegen.py +30 -0
- browserless_bap-0.2.0/scripts/docs.py +24 -0
- browserless_bap-0.2.0/scripts/sync_schema.py +223 -0
- browserless_bap-0.2.0/src/browserless_bap/__init__.py +35 -0
- browserless_bap-0.2.0/src/browserless_bap/_codec.py +29 -0
- browserless_bap-0.2.0/src/browserless_bap/_io.py +27 -0
- browserless_bap-0.2.0/src/browserless_bap/_page_generated.py +1322 -0
- browserless_bap-0.2.0/src/browserless_bap/_unset.py +12 -0
- browserless_bap-0.2.0/src/browserless_bap/_version.py +1 -0
- browserless_bap-0.2.0/src/browserless_bap/async_api.py +3 -0
- browserless_bap-0.2.0/src/browserless_bap/browser.py +108 -0
- browserless_bap-0.2.0/src/browserless_bap/browserless.py +30 -0
- browserless_bap-0.2.0/src/browserless_bap/element_handle.py +120 -0
- browserless_bap-0.2.0/src/browserless_bap/emitter.py +134 -0
- browserless_bap-0.2.0/src/browserless_bap/errors.py +64 -0
- browserless_bap-0.2.0/src/browserless_bap/graphql/__init__.py +11 -0
- browserless_bap-0.2.0/src/browserless_bap/graphql/builder.py +37 -0
- browserless_bap-0.2.0/src/browserless_bap/graphql/mutations.py +417 -0
- browserless_bap-0.2.0/src/browserless_bap/graphql/subscriptions.py +47 -0
- browserless_bap-0.2.0/src/browserless_bap/mutations.graphql +5560 -0
- browserless_bap-0.2.0/src/browserless_bap/page.py +771 -0
- browserless_bap-0.2.0/src/browserless_bap/py.typed +1 -0
- browserless_bap-0.2.0/src/browserless_bap/sync_api/__init__.py +24 -0
- browserless_bap-0.2.0/src/browserless_bap/sync_api/_base.py +32 -0
- browserless_bap-0.2.0/src/browserless_bap/sync_api/_bridge.py +419 -0
- browserless_bap-0.2.0/src/browserless_bap/sync_api/_page_generated.py +979 -0
- browserless_bap-0.2.0/src/browserless_bap/sync_api/browser.py +48 -0
- browserless_bap-0.2.0/src/browserless_bap/sync_api/browserless.py +33 -0
- browserless_bap-0.2.0/src/browserless_bap/sync_api/element_handle.py +70 -0
- browserless_bap-0.2.0/src/browserless_bap/sync_api/page.py +383 -0
- browserless_bap-0.2.0/src/browserless_bap/transport.py +522 -0
- browserless_bap-0.2.0/src/browserless_bap/types/__init__.py +7 -0
- browserless_bap-0.2.0/src/browserless_bap/types/enums.py +717 -0
- browserless_bap-0.2.0/src/browserless_bap/types/events.py +121 -0
- browserless_bap-0.2.0/src/browserless_bap/types/inputs.py +71 -0
- browserless_bap-0.2.0/src/browserless_bap/types/options.py +367 -0
- browserless_bap-0.2.0/src/browserless_bap/types/responses.py +314 -0
- browserless_bap-0.2.0/tests/e2e/__init__.py +1 -0
- browserless_bap-0.2.0/tests/e2e/config.py +61 -0
- browserless_bap-0.2.0/tests/e2e/conftest.py +26 -0
- browserless_bap-0.2.0/tests/e2e/test_config.py +135 -0
- browserless_bap-0.2.0/tests/e2e/test_live.py +166 -0
- browserless_bap-0.2.0/tests/sync/__init__.py +1 -0
- browserless_bap-0.2.0/tests/sync/_server.py +165 -0
- browserless_bap-0.2.0/tests/sync/test_bridge.py +290 -0
- browserless_bap-0.2.0/tests/sync/test_parity.py +23 -0
- browserless_bap-0.2.0/tests/sync/test_sync_events.py +38 -0
- browserless_bap-0.2.0/tests/sync/test_sync_page.py +67 -0
- browserless_bap-0.2.0/tests/sync/test_wrappers.py +364 -0
- browserless_bap-0.2.0/tests/test_browser.py +118 -0
- browserless_bap-0.2.0/tests/test_check_public_text.py +158 -0
- browserless_bap-0.2.0/tests/test_codegen_docs.py +112 -0
- browserless_bap-0.2.0/tests/test_codegen_drift.py +26 -0
- browserless_bap-0.2.0/tests/test_codegen_edge_cases.py +63 -0
- browserless_bap-0.2.0/tests/test_codegen_operations.py +120 -0
- browserless_bap-0.2.0/tests/test_codegen_parity.py +45 -0
- browserless_bap-0.2.0/tests/test_codegen_schema.py +84 -0
- browserless_bap-0.2.0/tests/test_emitter.py +146 -0
- browserless_bap-0.2.0/tests/test_errors.py +50 -0
- browserless_bap-0.2.0/tests/test_graphql_builder.py +33 -0
- browserless_bap-0.2.0/tests/test_io.py +44 -0
- browserless_bap-0.2.0/tests/test_live_complete.py +418 -0
- browserless_bap-0.2.0/tests/test_package.py +23 -0
- browserless_bap-0.2.0/tests/test_page_events.py +313 -0
- browserless_bap-0.2.0/tests/test_page_overrides.py +301 -0
- browserless_bap-0.2.0/tests/test_sync_schema.py +93 -0
- browserless_bap-0.2.0/tests/test_transport.py +125 -0
- browserless_bap-0.2.0/tests/test_transport_protocol.py +560 -0
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.egg-info/
|
|
5
|
+
.coverage
|
|
6
|
+
.mypy_cache/
|
|
7
|
+
.pytest_cache/
|
|
8
|
+
.ruff_cache/
|
|
9
|
+
|
|
10
|
+
# Environments and local secrets
|
|
11
|
+
.venv/
|
|
12
|
+
venv/
|
|
13
|
+
.env
|
|
14
|
+
.env.*
|
|
15
|
+
|
|
16
|
+
# Build output
|
|
17
|
+
build/
|
|
18
|
+
dist/
|
|
19
|
+
site/
|
|
20
|
+
|
|
21
|
+
# Editors and operating systems
|
|
22
|
+
.DS_Store
|
|
23
|
+
.idea/
|
|
24
|
+
.vscode/
|
|
25
|
+
|
|
26
|
+
# Generated SDK modules are intentionally committed. Do not ignore src/browserless_bap.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Guidance for coding agents working in this repository. Humans should start
|
|
4
|
+
with [CONTRIBUTING.md](./CONTRIBUTING.md); SDK users should read
|
|
5
|
+
[README.md](./README.md) and [llms.txt](./llms.txt).
|
|
6
|
+
|
|
7
|
+
## What this is
|
|
8
|
+
|
|
9
|
+
`browserless-bap` is the Python SDK for Browserless's Browser Automation Protocol. It
|
|
10
|
+
is a GraphQL-over-WebSocket client, not a CDP client. It offers equivalent
|
|
11
|
+
async and sync APIs with Playwright-style Python names.
|
|
12
|
+
|
|
13
|
+
## Source of truth
|
|
14
|
+
|
|
15
|
+
The vendored schema is `src/browserless_bap/mutations.graphql`. Generated modules and the
|
|
16
|
+
README/llms method lists come from `scripts/codegen.py` and are committed.
|
|
17
|
+
Never hand-edit generated output or content inside AUTOGEN markers.
|
|
18
|
+
|
|
19
|
+
To change generated output:
|
|
20
|
+
|
|
21
|
+
1. Update the schema with `scripts/sync_schema.py` or change generator inputs.
|
|
22
|
+
2. Run `python scripts/codegen.py`.
|
|
23
|
+
3. Run the drift check and commit the inputs and outputs together.
|
|
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`.
|
|
27
|
+
|
|
28
|
+
## Runtime constraints
|
|
29
|
+
|
|
30
|
+
- Python 3.11 or newer.
|
|
31
|
+
- `websockets` is the only runtime dependency.
|
|
32
|
+
- Keep GraphQL wire dictionaries zero-conversion; generated input/response
|
|
33
|
+
dictionaries retain GraphQL field names.
|
|
34
|
+
- Transport clients must use `max_size=None`, `ping_interval=20`,
|
|
35
|
+
`ping_timeout=None`, `open_timeout=None`, and `close_timeout=5`.
|
|
36
|
+
- Never block the asyncio loop with file I/O.
|
|
37
|
+
- Keep strong references to background tasks until completion.
|
|
38
|
+
- Sync callbacks run on the callback dispatcher, never the bridge loop.
|
|
39
|
+
|
|
40
|
+
## Commands
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
python -m pip install -e ".[dev]"
|
|
44
|
+
ruff format --check .
|
|
45
|
+
ruff check .
|
|
46
|
+
mypy
|
|
47
|
+
pytest -m "not e2e"
|
|
48
|
+
python scripts/codegen.py
|
|
49
|
+
python scripts/sync_schema.py --check
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Live tests are selected with `pytest -m e2e`, need `BROWSERLESS_TOKEN`, and use
|
|
53
|
+
`BROWSERLESS_URL` (default `wss://production-sfo.browserless.io/chromium/bql`).
|
|
54
|
+
Do not put tokens in source, tests, logs, screenshots, or recorded evidence.
|
|
55
|
+
|
|
56
|
+
## Before opening a PR
|
|
57
|
+
|
|
58
|
+
The offline suite, lint, strict typing, codegen drift check, and wheel smoke
|
|
59
|
+
must pass. Follow the pull request and public repository rules in
|
|
60
|
+
CONTRIBUTING.md. Publishing and deploying are human-owned; never create a
|
|
61
|
+
release, tag, or PyPI upload unless explicitly authorized.
|
|
62
|
+
|
|
63
|
+
## Public repository rules
|
|
64
|
+
|
|
65
|
+
Never write internal ticket IDs, internal tool links (issue tracker, chat,
|
|
66
|
+
coding-agent threads, support desk), private repository names or customer
|
|
67
|
+
details into PR titles, PR descriptions, commit messages, code comments, test
|
|
68
|
+
names, docs or review replies. CI enforces the title, description and commit
|
|
69
|
+
part. Link from the internal tracker to the PR, never the reverse.
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Contributing to browserless-bap
|
|
2
|
+
|
|
3
|
+
## Setup
|
|
4
|
+
|
|
5
|
+
Create a Python 3.11-or-newer virtual environment and install the editable
|
|
6
|
+
development dependencies:
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
python -m venv .venv
|
|
10
|
+
source .venv/bin/activate
|
|
11
|
+
python -m pip install -e ".[dev]"
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Development checks
|
|
15
|
+
|
|
16
|
+
Run these before opening a pull request:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
ruff format --check .
|
|
20
|
+
ruff check .
|
|
21
|
+
mypy
|
|
22
|
+
pytest -m "not e2e"
|
|
23
|
+
python scripts/codegen.py
|
|
24
|
+
git diff --exit-code -- README.md llms.txt src/browserless_bap
|
|
25
|
+
python -m build
|
|
26
|
+
python -m venv /tmp/bap-wheel-smoke
|
|
27
|
+
/tmp/bap-wheel-smoke/bin/python -m pip install dist/*.whl
|
|
28
|
+
/tmp/bap-wheel-smoke/bin/python -c \
|
|
29
|
+
"import browserless_bap, browserless_bap.sync_api; assert not hasattr(browserless_bap, 'schema_source')"
|
|
30
|
+
! python -m zipfile -l dist/*.whl | grep -q 'mutations.graphql'
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
### Live tests
|
|
34
|
+
|
|
35
|
+
The live suite (`pytest -m e2e`) connects to a real Browserless BrowserQL
|
|
36
|
+
endpoint and uses your account. It runs only when selected with `-m e2e` and is
|
|
37
|
+
skipped when `BROWSERLESS_TOKEN` is unset.
|
|
38
|
+
`BROWSERLESS_URL` defaults to `wss://production-sfo.browserless.io/chromium/bql`
|
|
39
|
+
and may be any `ws://` or `wss://` BrowserQL endpoint, for example another
|
|
40
|
+
region or a self-hosted server:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
BROWSERLESS_TOKEN=your-api-token pytest -m e2e
|
|
44
|
+
BROWSERLESS_URL=wss://production-lon.browserless.io/chromium/bql BROWSERLESS_TOKEN=your-api-token pytest -m e2e
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Never commit tokens or paste them into issues, pull requests, logs or
|
|
48
|
+
screenshots.
|
|
49
|
+
|
|
50
|
+
## Updating the BrowserQL schema
|
|
51
|
+
|
|
52
|
+
The integrity check is self-contained and needs no sibling repository:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
python scripts/sync_schema.py --check
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
By default, syncing reads `../bap-ts/src/mutations.graphql` from a sibling
|
|
59
|
+
checkout of the TypeScript SDK:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
python scripts/sync_schema.py
|
|
63
|
+
```
|
|
64
|
+
|
|
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):
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
python scripts/sync_schema.py --from-bap-ts
|
|
71
|
+
python scripts/sync_schema.py --schema /path/to/mutations.graphql
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Schema and codegen changes must include `schema.lock` and all regenerated
|
|
75
|
+
files. Generated files and AUTOGEN regions must not be edited manually.
|
|
76
|
+
|
|
77
|
+
## API reference
|
|
78
|
+
|
|
79
|
+
The generated Python API reference is published at
|
|
80
|
+
<https://docs.browserless.io/bap/python/reference>. Maintainers regenerate it
|
|
81
|
+
with `python scripts/docs.py --output <directory>`, which writes Docusaurus
|
|
82
|
+
`.mdx` files, and publish the output to the documentation site.
|
|
83
|
+
|
|
84
|
+
## Pull requests
|
|
85
|
+
|
|
86
|
+
- Branch from `main` and keep changes focused.
|
|
87
|
+
- Use Conventional Commits-compatible titles and reference related GitHub
|
|
88
|
+
issues (for example `Closes #123`).
|
|
89
|
+
- Include tests for behavior changes.
|
|
90
|
+
- Do not publish packages or create release tags from a pull request branch.
|
|
91
|
+
|
|
92
|
+
## Public repository rules
|
|
93
|
+
|
|
94
|
+
PR titles, descriptions, commit messages and review comments must not contain
|
|
95
|
+
internal ticket IDs (text like `ABC-123`), links to internal tools (issue
|
|
96
|
+
tracker, chat, coding-agent or support-desk links), private repository names,
|
|
97
|
+
or customer details. PR titles matter most: they become squash-commit subjects
|
|
98
|
+
and changelog entries.
|
|
99
|
+
|
|
100
|
+
CI (`Public PR rules`) rejects titles, descriptions and commit messages that
|
|
101
|
+
match these patterns; harmless technical identifiers such as `UTF-8`,
|
|
102
|
+
`SHA-256` and `CVE-2025-1234` are allowed. Maintainers link from the internal
|
|
103
|
+
tracker to the public PR, never the reverse.
|
|
104
|
+
|
|
105
|
+
PR titles also follow [Conventional Commits](https://www.conventionalcommits.org/):
|
|
106
|
+
`type: summary` or `type(scope): summary`, with type one of `feat`, `fix`,
|
|
107
|
+
`perf`, `revert`, `build`, `chore`, `ci`, `docs`, `style`, `refactor` or
|
|
108
|
+
`test`. The `PR title` check enforces this.
|
|
109
|
+
|
|
110
|
+
## Reporting security issues
|
|
111
|
+
|
|
112
|
+
Please report vulnerabilities privately as described in
|
|
113
|
+
[SECURITY.md](./SECURITY.md).
|
|
114
|
+
|
|
115
|
+
## Code of conduct
|
|
116
|
+
|
|
117
|
+
Everyone taking part in this project is expected to follow the
|
|
118
|
+
[Code of Conduct](./CODE_OF_CONDUCT.md).
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 browserless.io
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: browserless-bap
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Python async and sync client for Browserless's Browser Automation Protocol
|
|
5
|
+
Project-URL: Homepage, https://github.com/browserless/bap-py
|
|
6
|
+
Project-URL: Documentation, https://docs.browserless.io/bap/python/reference
|
|
7
|
+
Project-URL: Source, https://github.com/browserless/bap-py
|
|
8
|
+
Project-URL: Changelog, https://github.com/browserless/bap-py/releases
|
|
9
|
+
Project-URL: Issues, https://github.com/browserless/bap-py/issues
|
|
10
|
+
Author-email: Browserless <eng@browserless.io>
|
|
11
|
+
License-Expression: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: browser-automation,browserless,browserql,playwright
|
|
14
|
+
Classifier: Development Status :: 3 - Alpha
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Typing :: Typed
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Requires-Dist: websockets>=14.0
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: build>=1.2; extra == 'dev'
|
|
26
|
+
Requires-Dist: graphql-core>=3.2; extra == 'dev'
|
|
27
|
+
Requires-Dist: griffe>=1.0; extra == 'dev'
|
|
28
|
+
Requires-Dist: mypy>=1.14; extra == 'dev'
|
|
29
|
+
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
|
|
30
|
+
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
|
|
31
|
+
Requires-Dist: pytest>=8.3; extra == 'dev'
|
|
32
|
+
Requires-Dist: ruff>=0.9; extra == 'dev'
|
|
33
|
+
Requires-Dist: twine>=6.0; extra == 'dev'
|
|
34
|
+
Description-Content-Type: text/markdown
|
|
35
|
+
|
|
36
|
+
# browserless-bap
|
|
37
|
+
|
|
38
|
+
The Python client for Browserless's Browser Automation Protocol (BAP).
|
|
39
|
+
`browserless-bap` provides Playwright-style async and sync APIs over Browserless's
|
|
40
|
+
GraphQL-over-WebSocket transport.
|
|
41
|
+
|
|
42
|
+
## Requirements
|
|
43
|
+
|
|
44
|
+
- Python 3.11 or newer
|
|
45
|
+
- A Browserless API token for live use
|
|
46
|
+
|
|
47
|
+
## Install
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
pip install browserless-bap
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Quick start
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
import asyncio
|
|
57
|
+
|
|
58
|
+
import browserless_bap as bap
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
async def run() -> None:
|
|
62
|
+
async with bap.Browserless.connect(
|
|
63
|
+
browser_ws_endpoint="wss://production-sfo.browserless.io/chromium/bql",
|
|
64
|
+
token="your-api-token",
|
|
65
|
+
) as browser:
|
|
66
|
+
async with browser.page() as page:
|
|
67
|
+
await page.goto("https://example.com")
|
|
68
|
+
print(await page.title())
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
asyncio.run(run())
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The same script with the sync API, from `browserless_bap.sync_api`:
|
|
75
|
+
|
|
76
|
+
```python
|
|
77
|
+
import browserless_bap.sync_api as bap
|
|
78
|
+
|
|
79
|
+
with bap.Browserless.connect(
|
|
80
|
+
browser_ws_endpoint="wss://production-sfo.browserless.io/chromium/bql",
|
|
81
|
+
token="your-api-token",
|
|
82
|
+
) as browser:
|
|
83
|
+
with browser.page() as page:
|
|
84
|
+
page.goto("https://example.com")
|
|
85
|
+
print(page.title())
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
> [!TIP]
|
|
89
|
+
> Jupyter notebooks already run an asyncio event loop, so use the async API
|
|
90
|
+
> there and replace `asyncio.run(run())` with `await run()`. The sync API
|
|
91
|
+
> raises `RuntimeError` inside a running event loop.
|
|
92
|
+
|
|
93
|
+
## API methods
|
|
94
|
+
|
|
95
|
+
This table is generated from the vendored GraphQL schema. Do not edit the
|
|
96
|
+
contents between the markers by hand.
|
|
97
|
+
|
|
98
|
+
<!-- AUTOGEN:method-table START -->
|
|
99
|
+
|
|
100
|
+
| Method | Source mutation | Returns | Playwright-named |
|
|
101
|
+
| ------ | --------------- | ------- | ---------------- |
|
|
102
|
+
| `add_cookies` | `cookies` | `CookieResponse` | ✅ |
|
|
103
|
+
| `add_script_tag` | `addScriptTag` | `AddScriptTagResponse` | ✅ |
|
|
104
|
+
| `add_style_tag` | `addStyleTag` | `AddStyleTagResponse` | ✅ |
|
|
105
|
+
| `authenticate` | `authenticate` | `HTTPResponse \| None` | — |
|
|
106
|
+
| `check` | `checkbox` | `ClickResponse` | — |
|
|
107
|
+
| `click` | `click` | `ClickResponse` | ✅ |
|
|
108
|
+
| `close` | `—` | `None` | ✅ |
|
|
109
|
+
| `close_live_url` | `closeLiveURL` | `CloseLiveURLResponse` | — |
|
|
110
|
+
| `content` | `html` | `str` | ✅ |
|
|
111
|
+
| `cookies` | `cookies` | `list[StandardCookie]` | ✅ |
|
|
112
|
+
| `emulate_media` | `emulateMediaType` | `EmulateMediaTypeResponse` | ✅ |
|
|
113
|
+
| `eval_on_selector` | `text` | `str` | ✅ |
|
|
114
|
+
| `eval_on_selector_all` | `mapSelector` | `list[MapSelectorResponse]` | ✅ |
|
|
115
|
+
| `evaluate` | `evaluate` | `str \| None` | ✅ |
|
|
116
|
+
| `fulfill` | `fulfill` | `FulfillResponse` | — |
|
|
117
|
+
| `go_back` | `back` | `HTTPResponse \| None` | ✅ |
|
|
118
|
+
| `go_forward` | `forward` | `HTTPResponse \| None` | ✅ |
|
|
119
|
+
| `goto` | `goto` | `HTTPResponse \| None` | ✅ |
|
|
120
|
+
| `hover` | `hover` | `HoverResponse` | ✅ |
|
|
121
|
+
| `html` | `html` | `HTMLResponse` | — |
|
|
122
|
+
| `live_url` | `liveURL` | `LiveURLResponse` | — |
|
|
123
|
+
| `load_secret` | `loadSecret` | `LoadSecretResponse` | — |
|
|
124
|
+
| `map_selector` | `mapSelector` | `list[MapSelectorResponse]` | — |
|
|
125
|
+
| `markdown` | `markdown` | `MarkdownResponse` | — |
|
|
126
|
+
| `pdf` | `pdf` | `bytes` | ✅ |
|
|
127
|
+
| `preferences` | `preferences` | `DefaultResponse` | — |
|
|
128
|
+
| `proxy` | `proxy` | `ProxyResponse` | — |
|
|
129
|
+
| `query_selector` | `querySelector` | `ElementHandle \| None` | ✅ |
|
|
130
|
+
| `query_selector_all` | `querySelectorAll` | `list[ElementHandle]` | ✅ |
|
|
131
|
+
| `reconnect` | `reconnect` | `ReconnectionResponse` | — |
|
|
132
|
+
| `reject` | `reject` | `RejectResponse` | — |
|
|
133
|
+
| `reload` | `reload` | `HTTPResponse \| None` | ✅ |
|
|
134
|
+
| `request` | `request` | `list[RequestResponse]` | — |
|
|
135
|
+
| `response` | `response` | `list[ResponseResponse]` | — |
|
|
136
|
+
| `screenshot` | `screenshot` | `bytes` | ✅ |
|
|
137
|
+
| `scroll` | `scroll` | `ScrollResponse` | — |
|
|
138
|
+
| `select_option` | `select` | `SelectResponse` | ✅ |
|
|
139
|
+
| `send` | `—` | `T` | — |
|
|
140
|
+
| `set_content` | `content` | `HTTPResponse \| None` | ✅ |
|
|
141
|
+
| `set_extra_http_headers` | `setExtraHTTPHeaders` | `HTTPHeadersResponse` | ✅ |
|
|
142
|
+
| `set_java_script_enabled` | `javaScriptEnabled` | `JavaScriptResponse` | — |
|
|
143
|
+
| `set_user_agent` | `userAgent` | `UserAgentResponse` | ✅ |
|
|
144
|
+
| `set_viewport_size` | `viewport` | `ViewportResponse` | ✅ |
|
|
145
|
+
| `solve` | `solve` | `CaptchaResponse` | — |
|
|
146
|
+
| `solve_image_captcha` | `solveImageCaptcha` | `CaptchaResponse` | — |
|
|
147
|
+
| `stop_session_recording` | `stopSessionRecording` | `StopSessionRecordingResponse` | — |
|
|
148
|
+
| `switch_to_window` | `switchToWindow` | `SwitchWindowResponse` | — |
|
|
149
|
+
| `text` | `text` | `TextResponse` | — |
|
|
150
|
+
| `title` | `title` | `str` | ✅ |
|
|
151
|
+
| `type` | `type` | `TypeResponse` | ✅ |
|
|
152
|
+
| `uncheck` | `checkbox` | `ClickResponse` | — |
|
|
153
|
+
| `url` | `url` | `str` | ✅ |
|
|
154
|
+
| `wait_for_event` | `waitForEvent` | `WaitForEvent` | — |
|
|
155
|
+
| `wait_for_function` | `waitForFunction` | `WaitForFunction` | ✅ |
|
|
156
|
+
| `wait_for_live_complete` | `liveComplete` | `LiveURLCompleteEvent` | — |
|
|
157
|
+
| `wait_for_navigation` | `waitForNavigation` | `HTTPResponse` | ✅ |
|
|
158
|
+
| `wait_for_network_idle` | `waitForNetworkIdle` | `WaitForTimeoutResponse` | — |
|
|
159
|
+
| `wait_for_request` | `waitForRequest` | `WaitForRequestResponse` | ✅ |
|
|
160
|
+
| `wait_for_response` | `waitForResponse` | `WaitForResponseResponse` | ✅ |
|
|
161
|
+
| `wait_for_selector` | `waitForSelector` | `WaitForSelectorResponse` | ✅ |
|
|
162
|
+
| `wait_for_timeout` | `waitForTimeout` | `None` | ✅ |
|
|
163
|
+
| `watch_event` | `watchEvent` | `WaitForEvent` | — |
|
|
164
|
+
|
|
165
|
+
<!-- AUTOGEN:method-table END -->
|
|
166
|
+
|
|
167
|
+
## Schema and generated code
|
|
168
|
+
|
|
169
|
+
`src/browserless_bap/mutations.graphql` is the vendored GraphQL schema. Its full digest,
|
|
170
|
+
line count, and source provenance are committed in `schema.lock`. Verify the
|
|
171
|
+
vendored schema without requiring any sibling checkout:
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
python scripts/sync_schema.py --check
|
|
175
|
+
```
|
|
176
|
+
|
|
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:
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
python scripts/sync_schema.py --from-bap-ts
|
|
184
|
+
python scripts/sync_schema.py --schema /path/to/mutations.graphql
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Generated Python modules are committed to git. Update the schema or generator,
|
|
188
|
+
run `python scripts/codegen.py`, and commit the inputs and generated outputs
|
|
189
|
+
together.
|
|
190
|
+
|
|
191
|
+
## Development
|
|
192
|
+
|
|
193
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, testing, and contribution
|
|
194
|
+
instructions.
|
|
195
|
+
|
|
196
|
+
## Wait for a Live URL handoff
|
|
197
|
+
|
|
198
|
+
```python
|
|
199
|
+
link = await page.live_url(instructions="Sign in, then click Done.", timeout=120_000)
|
|
200
|
+
print(link["liveURL"])
|
|
201
|
+
completion = await page.wait_for_live_complete(timeout=120_000)
|
|
202
|
+
if completion["reason"] != "userDone":
|
|
203
|
+
raise RuntimeError(f"Handoff ended: {completion['reason']}")
|
|
204
|
+
# To cancel a link instead: await page.close_live_url(link["liveURLId"])
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
The sync facade uses the same calls without `await`.
|
|
208
|
+
|
|
209
|
+
For a richer human handoff, pass an instructions card:
|
|
210
|
+
|
|
211
|
+
```python
|
|
212
|
+
link = await page.live_url(
|
|
213
|
+
instructions={
|
|
214
|
+
"layout": "panel",
|
|
215
|
+
"format": "markdown",
|
|
216
|
+
"title": "Complete sign in",
|
|
217
|
+
"summary": "**Sign in** to continue.",
|
|
218
|
+
"steps": ["Open your inbox", "Enter the code"],
|
|
219
|
+
"currentStep": 2,
|
|
220
|
+
},
|
|
221
|
+
done_label="Continue",
|
|
222
|
+
fail_label="Need help",
|
|
223
|
+
requester_name="Support",
|
|
224
|
+
)
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
With string instructions, use the top-level `instructions_title`, `steps`,
|
|
228
|
+
`current_step` and `instructions_format`. With a card, put `title`, `steps`,
|
|
229
|
+
`currentStep` and `format` inside it. Button labels and `requester_name` always
|
|
230
|
+
stay top-level. The server validates card limits. For an explicitly annotated
|
|
231
|
+
card, import `LiveURLInstructions` from `browserless_bap.types`.
|
|
232
|
+
|
|
233
|
+
The SDK subscribes before minting and retains completion until the next mint,
|
|
234
|
+
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
|
|
236
|
+
there is no client wait deadline; pass a positive timeout to bound the wait.
|
|
237
|
+
`timeout=0` also disables the wait deadline. Timing out or cancelling a wait does
|
|
238
|
+
not close the live URL.
|
|
239
|
+
|
|
240
|
+
Completion reasons are `userDone`, `userFailed`, `timeout`, `closed`, and
|
|
241
|
+
`viewerDisconnected`. Only `userDone` explicitly means the person finished.
|
|
242
|
+
Use `close_live_url(id)` to end a link programmatically;
|
|
243
|
+
the response contains `liveURLId`. Await each mint before starting another one.
|
|
244
|
+
A re-mint starts a new wait even when the server reuses its ID; existing waits
|
|
245
|
+
remain associated with the preceding handoff. Closing the page or losing the
|
|
246
|
+
connection rejects pending waits. The completion subscription closes when no pending handoffs or public listeners
|
|
247
|
+
remain; cached results remain available. Public listeners use `on`/`off`.
|
|
248
|
+
For reused IDs, the server emits the preceding handoff’s completion before the
|
|
249
|
+
replacement’s completion on the same ordered subscription stream.
|
|
250
|
+
|
|
251
|
+
Live URL handoffs need a Browserless server that supports
|
|
252
|
+
`wait_for_live_complete()` (the `liveComplete` event), `close_live_url()` and
|
|
253
|
+
instruction cards. When a live URL call passes `instructions`, this client sends
|
|
254
|
+
them in the newer format, which older servers reject even for a plain string.
|
|
255
|
+
Older clients send a format that newer servers reject. Upgrading is
|
|
256
|
+
therefore a coordinated client/server cutover, not a rolling server-first
|
|
257
|
+
upgrade.
|
|
258
|
+
|
|
259
|
+
For self-hosted upgrades, pause new handoffs and drain active ones, upgrade the
|
|
260
|
+
server and all clients together, then verify mint, completion, and close before
|
|
261
|
+
resuming handoffs. Handoffs remain unavailable during this cutover. To roll back,
|
|
262
|
+
pause and drain again and restore both the previous server and previous clients;
|
|
263
|
+
rolling back only one side leaves an incompatible pair. No mixed-version
|
|
264
|
+
compatibility path is provided by this SDK.
|