Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 54 additions & 11 deletions src/content/reference/python.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,7 @@ raise [`ToolError`](#toolerror). Closing the browser closes every session.
def accept_cookies(self, *, prefer: str | None = None, selectors: list | None = None) -> Any
```

Dismiss the cookie consent banner on the current page: the browser offers the banner's own controls to TypeSafe System One (Jev), clicks the one it picks, and re-reads the page to check the banner went. Returns JSON — `dismissed` is what was clicked, `verified` whether the page agreed afterwards, `selectors` the controls clicked in order, and `reason` why nothing happened when nothing did. A click that leaves a banner up (a confirmation, say) is followed by one more pick. A page with nothing to click costs no model call; passing `selectors` clicks them in order and asks nothing, which is how a recorded call replays. Otherwise needs TYPESAFE_API_KEY.
Dismiss the cookie consent banner on the current page: the browser offers the banner's own controls to a decision model (Gemini Decisions or TypeSafe System One), clicks the one it picks, and re-reads the page to check the banner went. Returns JSON — `dismissed` is what was clicked, `verified` whether the page agreed afterwards, `selectors` the controls clicked in order, and `reason` why nothing happened when nothing did. A click that leaves a banner up (a confirmation, say) is followed by one more pick. A page with nothing to click costs no model call; passing `selectors` clicks them in order and asks nothing, which is how a recorded call replays. Otherwise needs TYPESAFE_API_KEY, or GOOGLE_API_KEY/GEMINI_API_KEY with LIGHTPANDA_DECISION_PROVIDER=gemini.


**Arguments:**
Expand Down Expand Up @@ -202,11 +202,11 @@ def classify(
) -> Any
```

Classify the page or an element subtree using TypeSafe System One (Jev). `questions` is a JSON array of categories (returns the one that fits), or a JSON object of questions keyed by the name each answer comes back under: `true` for a preset (isBlocked, isCaptcha, isConsentWall, isEmptyCatalog, isErrorPage, isLoginWall, isPaywall, isUnsupportedBrowser, isLoading; an empty object `{}` asks all of them), a string for a yes/no question (returns its probability), `{question, options}` for a choice, or `{question, levels}` for a score on 2-10 levels ordered low to high (returns the `score` between level indices, the nearest `level`, and per-level `probabilities`). A missing answer is null.
Classify the page or an element subtree using a decision model (Gemini Decisions or TypeSafe System One). `questions` is a JSON array of categories (returns the one that fits), or a JSON object of questions keyed by the name each answer comes back under: `true` for a preset (isBlocked, isCaptcha, isConsentWall, isEmptyCatalog, isErrorPage, isLoginWall, isPaywall, isUnsupportedBrowser, isLoading, isAgeGate, isRegionBlocked, isRateLimited; an empty object `{}` asks all of them), a string for a yes/no question (returns its probability), `{question, options}` for a choice, or `{question, levels}` for a score on 2-10 levels ordered low to high (returns the `score` between level indices, the nearest `level`, and per-level `probabilities`). A missing answer is null.


**Arguments:**
- **questions:** JSON string: array of categories, or object of questions (`{}` for every preset)
- **questions:** JSON object or array of questions, or a JSON-encoded string of the same (`{}` for every preset)
- **selector:** Optional CSS selector to classify a specific element subtree instead of the full page
- **presets:** Also ask every preset in the same call, each answered under its own name beside the questions. Needs the object form.

Expand Down Expand Up @@ -541,7 +541,7 @@ def login(
) -> Any
```

Sign in on the current page. The browser collects the candidate fields and sign-in controls, asks TypeSafe System One (Jev) only what the markup leaves ambiguous, fills the credentials, submits, and re-reads the page to say whether it worked. A password is only ever typed into an `input[type=password]`, and credentials only go to an https (or loopback) page whose form posts to an https URL. Pass `$LP_*` placeholders rather than literal secrets: they resolve inside the browser and never appear in the result. Returns JSON with the selectors it used, so a recorded call replays them with no model call. Otherwise needs TYPESAFE_API_KEY.
Sign in on the current page. The browser collects the candidate fields and sign-in controls, asks a decision model (Gemini Decisions or TypeSafe System One) only what the markup leaves ambiguous, fills the credentials, submits, and re-reads the page to say whether it worked. A password is only ever typed into an `input[type=password]`, and credentials only go to an https (or loopback) page whose form posts to an https URL. Pass `$LP_*` placeholders rather than literal secrets: they resolve inside the browser and never appear in the result. Returns JSON with the selectors it used, so a recorded call replays them with no model call. Otherwise needs TYPESAFE_API_KEY, or GOOGLE_API_KEY/GEMINI_API_KEY with LIGHTPANDA_DECISION_PROVIDER=gemini.


**Arguments:**
Expand Down Expand Up @@ -599,7 +599,19 @@ Details for a node by backendNodeId: a ready-to-use CSS `selector` that resolves
def page_tools(self) -> Any
```

List the tools the current page registers for agents through WebMCP (`navigator.modelContext.registerTool`), as JSON with each tool's `name`, `description`, `inputSchema` and hints. A page tool runs the site's own code and can be more reliable than driving its UI; call one with `callPageTool`. Many pages register their tools after `load`: if the list is empty on a page you expect to have tools, call `waitForState` with `networkidle` and list again.
List the tools the current page registers for agents through WebMCP (`navigator.modelContext.registerTool`), as JSON with each tool's `name`, `description`, `inputSchema` and hints. A page tool runs the site's own code and can be more reliable than driving its UI; call one with `callPageTool`. Other tool results already show the page's tools, with their schemas, whenever the set changes; call this to list them again. Many pages register their tools after `load`: on a page you expect to have tools, `waitForState` with `networkidle` gives them time.

### Session.popups [#session-popups]

```python
def popups(self, *, follow: int | None = None) -> Any
```

Windows the current page opened (`window.open` or target=_blank), main page first. A click that opens a window is followed automatically; a window opened late, after a fetch or a timer, lands here. `follow` makes that window current — subsequent tools act on it; pass the main page's id to switch back. Windows live until the page closes.


**Arguments:**
- **follow:** Id from a previous popups call. Makes that window current for subsequent tool calls.

### Session.press [#session-press]

Expand Down Expand Up @@ -642,7 +654,7 @@ def run(
) -> Any
```

Run a Lightpanda agent script in this session, as `lightpanda run` does, and return its console output followed by the value it returns. Pass the source as `script`, or the `path` of a file `save` wrote. The script drives pages through `const page = new Page(); await page.goto(url);` and the builtins as methods on `page`; `$LP_*` placeholders are resolved. Pages the script opens are closed when it ends; cookies and storage stay in the session, so a login carries over to the next call. Script variables do not carry over. A thrown error, a failed step or the timeout ends the script and is reported as an error after the output so far.
Run a Lightpanda agent script in this session, as `lightpanda run` does, and return its console output followed by the value it returns. Pass the source as `script`, or the `path` of a file `save` wrote. The script drives pages through `const page = new Page(); await page.goto(url);` and the builtins as methods on `page`; `$LP_*` placeholders are resolved. To read several URLs, make one `new Page()` per URL and `await Promise.all(pages.map((p, i) => p.goto(urls[i])))` so they load in parallel, then read each with `page.extract` or `page.evaluate`. Pages the script opens are closed when it ends; cookies and storage stay in the session, so a login carries over to the next call. Script variables do not carry over. A thrown error, a failed step or the timeout ends the script and is reported as an error after the output so far.


**Arguments:**
Expand Down Expand Up @@ -786,7 +798,7 @@ Check or uncheck a checkbox or radio button. Provide either a CSS selector (pref
def structured_data(self, *, url: str | None = None, timeout: int | None = None) -> Any
```

Page metadata as JSON: `jsonLd` (each JSON-LD block as a string), `openGraph`, `twitterCard`, `meta` and [`links`](#session-links) (key/value lists), plus `alternate` (hreflang variants) and `linkHeaders` (relations from the HTTP Link header) when present. Empty sections come back as empty arrays. Use it for publisher-declared facts such as product price, article author or canonical URL before scraping the visible text for them. If a url is provided, it navigates there first.
Page metadata as JSON: `jsonLd` (each JSON-LD block as a string), `openGraph`, `twitterCard`, `meta` and [`links`](#session-links) (key/value lists), plus `microdata` (itemscope items as `{type, id, properties}`, every property value an array), `alternate` (hreflang variants) and `linkHeaders` (relations from the HTTP Link header) when present. Empty sections come back as empty arrays. Use it for publisher-declared facts such as product price, article author or canonical URL before scraping the visible text for them. If a url is provided, it navigates there first.


**Arguments:**
Expand All @@ -803,11 +815,12 @@ def tree(
timeout: int | None = None,
backend_node_id: int | None = None,
max_depth: int | None = None,
max_bytes: int | None = None
max_bytes: int | None = None,
delta: bool | None = None
) -> Any
```

Semantic outline of the page as indented text: one node per line with its role, accessible name, value and backendNodeId, plus checked state and select options with the selected one marked. The default first read of an unfamiliar page; input and select values are already here, so no `nodeDetails` call is needed to read them. Pass `backendNodeId` to scope to a subtree and `maxDepth` to survey structure before going deeper. Read it again after any page-changing action, since the DOM it describes may have changed; use `nodeDetails` to turn a backendNodeId into a CSS selector for actions.
Semantic outline of the page as indented text: one node per line with its role, accessible name, value and backendNodeId, plus checked state and select options with the selected one marked. The default first read of an unfamiliar page; input and select values are already here, so no `nodeDetails` call is needed to read them. Pass `backendNodeId` to scope to a subtree and `maxDepth` to survey structure before going deeper. Read it again after any page-changing action, since the DOM it describes may have changed; pass `delta` then to get only what changed since the last [`tree`](#session-tree) call. Use `nodeDetails` to turn a backendNodeId into a CSS selector for actions.


**Arguments:**
Expand All @@ -816,6 +829,7 @@ Semantic outline of the page as indented text: one node per line with its role,
- **backend_node_id:** Optional backend node ID to get the tree for a specific element instead of the document root. 0 is treated as omitted.
- **max_depth:** Optional maximum depth of the tree to return. Useful for exploring high-level structure first.
- **max_bytes:** Optional cap on output size in bytes. Past it, lines are kept by priority (alerts, dialogs, invalid fields and the focused element, then controls and named nodes, then text; list entries breadth-first), and dropped lines are counted in a '[+N more @id]' marker. id is the backendNodeId of the node holding them, often a list item or list that isn't printed itself: call tree with backendNodeId=id to read them.
- **delta:** Optional. Return only what changed since the last tree returned in full, by backendNodeId: '- id' removed with its subtree, '~ line' changed, '+ line' added; a new or moved line ends with its place, (after id) or (first in id), and the added lines under it follow indented. One line says when nothing changed. The first call, a navigation, another backendNodeId, maxDepth or maxBytes, or a change to most of the tree return the full tree under a '[full tree]' line.

### Session.wait_for_script [#session-wait-for-script]

Expand Down Expand Up @@ -1105,16 +1119,18 @@ def tree(
self,
*,
max_depth: int | None = None,
max_bytes: int | None = None
max_bytes: int | None = None,
delta: bool | None = None
) -> Any
```

Semantic outline of the page as indented text: one node per line with its role, accessible name, value and backendNodeId, plus checked state and select options with the selected one marked. The default first read of an unfamiliar page; input and select values are already here, so no `nodeDetails` call is needed to read them. Pass `backendNodeId` to scope to a subtree and `maxDepth` to survey structure before going deeper. Read it again after any page-changing action, since the DOM it describes may have changed; use `nodeDetails` to turn a backendNodeId into a CSS selector for actions.
Semantic outline of the page as indented text: one node per line with its role, accessible name, value and backendNodeId, plus checked state and select options with the selected one marked. The default first read of an unfamiliar page; input and select values are already here, so no `nodeDetails` call is needed to read them. Pass `backendNodeId` to scope to a subtree and `maxDepth` to survey structure before going deeper. Read it again after any page-changing action, since the DOM it describes may have changed; pass `delta` then to get only what changed since the last [`tree`](#element-tree) call. Use `nodeDetails` to turn a backendNodeId into a CSS selector for actions.


**Arguments:**
- **max_depth:** Optional maximum depth of the tree to return. Useful for exploring high-level structure first.
- **max_bytes:** Optional cap on output size in bytes. Past it, lines are kept by priority (alerts, dialogs, invalid fields and the focused element, then controls and named nodes, then text; list entries breadth-first), and dropped lines are counted in a '[+N more @id]' marker. id is the backendNodeId of the node holding them, often a list item or list that isn't printed itself: call tree with backendNodeId=id to read them.
- **delta:** Optional. Return only what changed since the last tree returned in full, by backendNodeId: '- id' removed with its subtree, '~ line' changed, '+ line' added; a new or moved line ends with its place, (after id) or (first in id), and the added lines under it follow indented. One line says when nothing changed. The first call, a navigation, another backendNodeId, maxDepth or maxBytes, or a change to most of the tree return the full tree under a '[full tree]' line.

### Element.get [#element-get]

Expand Down Expand Up @@ -1967,6 +1983,33 @@ is_loading: bool
The page says it is still loading (spinners, placeholders, loading
text). A page that is blank while it loads says nothing, so this misses it.

### PageVerdict.is_age_gate [#pageverdict-is-age-gate]

```python
is_age_gate: bool
```

An age check covers the content, asking the visitor to confirm they are
an adult or to enter their date of birth.

### PageVerdict.is_region_blocked [#pageverdict-is-region-blocked]

```python
is_region_blocked: bool
```

The site says the content is not available in the visitor's country or
region.

### PageVerdict.is_rate_limited [#pageverdict-is-rate-limited]

```python
is_rate_limited: bool
```

The site says too many requests were sent, and to slow down or try again
later.

### PageVerdict.scores [#pageverdict-scores]

```python
Expand Down
Loading