Documentation

Python SDK: Dom: searching HTML

ctx.dom(html, base_url) or response.dom() parses an already retrieved page. CSS selectors search the local document without another request.

Examples are fragments inside def run(ctx):. All SDK methods are synchronous; do not add await.

Obtaining the SDK object

dom = ctx.dom('<a href="/product">Product</a>', 'https://example.com')

q

dom.q(selector) -> Node | None

Argument	Type	Required	Purpose
`selector`	`str`	Yes	CSS selector.

Result: Node | None. An SDK object; use its methods instead of emitting it directly.

Find the first HTML element matching a CSS selector.

result = dom.q('a')

qa

dom.qa(selector) -> list[Node]

Argument	Type	Required	Purpose
`selector`	`str`	Yes	CSS selector.

Result: list[Node].

Find all matching HTML elements.

result = dom.qa('a')

first

dom.first(selectors) -> Node | None

Argument	Type	Required	Purpose
`selectors`	`list[str]`	Yes	Ordered fallback CSS selectors.

Result: Node | None. An SDK object; use its methods instead of emitting it directly.

Try several selectors and take the first match found.

result = dom.first(['.product', 'article'])

text

dom.text(selector, default=None) -> str | None

Argument	Type	Required	Purpose
`selector`	`str`	Yes	CSS selector.
`default`	`Any`	No, see the signature default	Fallback when no value is available.

Result: str | None.

Get the first match's text without an intermediate Node variable.

result = dom.text('.product-title', '')

attr

dom.attr(selector, name, default=None) -> str | None

Argument	Type	Required	Purpose
`selector`	`str`	Yes	CSS selector.
`name`	`str`	Yes	Field, header, file, credential, or metric name, depending on the method.
`default`	`Any`	No, see the signature default	Fallback when no value is available.

Result: str | None.

Read an attribute from the first matching element.

result = dom.attr('a', 'href')

max_number

dom.max_number(selector) -> int | None

Argument	Type	Required	Purpose
`selector`	`str`	Yes	CSS selector.

Result: int | None.

Find the largest number in element text, such as the last page number.

result = dom.max_number('.pagination a')

numbers_by_pattern

dom.numbers_by_pattern(pattern, subject) -> list[int | float]

Argument	Type	Required	Purpose
`pattern`	`str`	Yes	Regular expression or URL pattern, depending on the method.
`subject`	`str`	Yes	String being searched.

Result: list[int | float].

Finds numbers using a Python regular expression. It uses the first capture group when present, otherwise the complete match.

result = dom.numbers_by_pattern(r'(\d+)', 'Price 1250')

Errors and execution context

All calls are synchronous. Invalid arguments or malformed source data can raise ValueError/TypeError; a platform refusal or unavailable service raises RuntimeError. Missing elements/values return None or an empty collection only where explicitly documented. Do not convert every exception into an empty successful result. External-service methods are unavailable in export transformations; see transformation limits and environment.