ddp_utils.browser.facade.search¶

import ddp_utils.browser.facade.search

Backend-neutral structured DOM search criteria and value matching.

class ddp_utils.browser.facade.search.ElementQuery(name: str | None = None, attrs: Mapping[str, ~typing.Any]=<factory>, text: str | Pattern[str] | ValueMatch | None = None, match: MatchMode | str = MatchMode.EXACT, case_sensitive: bool = True, condition: SearchCondition | str = SearchCondition.ATTACHED)¶

Bases: object

Structured criteria for BeautifulSoup-like DOM search syntax.

Parameters

Name	Type	Description
name	str \| None	Optional HTML tag name. `None` means any tag.
attrs	Mapping[str, Any]	Attribute names mapped to values or `ValueMatch` objects. `True` means that the attribute must exist.
text	str \| Pattern[str] \| ValueMatch \| None	Optional visible-text value or independent `ValueMatch`.
match	MatchMode \| str	Default comparison mode for scalar text and attribute values.
case_sensitive	bool	Default case policy for scalar values.
condition	SearchCondition \| str	Required observable element state.

Examples

Find a visible link whose text contains a case-insensitive phrase:

query = ElementQuery(
    name="a",
    text="case details",
    match="contains",
    case_sensitive=False,
    condition="visible",
)

property candidate_selector: str¶

Return a safe broad CSS selector for backend candidate discovery.

Returns

Tag plus attribute-presence selector. Value matching remains in the neutral filter to preserve identical semantics across backends.

Examples

Narrow candidates before applying a contains comparison:

assert ElementQuery("a", {"href": "/"}).candidate_selector == "a[href]"

text_matcher() → ValueMatch | None¶

Return the normalized text matcher when text was requested.

Returns

Type	Description
ValueMatch \| None	Independent or default-derived matcher; otherwise `None`.

Examples

Obtain the default-derived matcher:

matcher = ElementQuery(text="Submit").text_matcher()

attribute_matcher(value: Any) → ValueMatch | None¶

Normalize one attribute value requirement.

Parameters

Name	Type	Description
value	Any	Scalar, compiled pattern, `ValueMatch`, or existence flag.

Returns

Type	Description
ValueMatch \| None	Value matcher, or `None` when only existence is required.

Examples

Convert a scalar using the query defaults:

matcher = query.attribute_matcher("button")

class ddp_utils.browser.facade.search.Match¶

Bases: object

Build explicit reusable value-match expressions.

Examples

Build a case-insensitive contains matcher:

matcher = Match.contains("fulton", case_sensitive=False)

static exact(value: Any, *, case_sensitive: bool = True, normalize_spaces: bool = False) → MatchExpression¶

Match a complete value.

Parameters

Name	Type	Description
value	Any	Expected value.
case_sensitive	bool	Preserve text case.
normalize_spaces	bool	Collapse whitespace before comparison.

Returns

Type	Description
MatchExpression	Match expression.

Examples

Match.exact("Ready", case_sensitive=False).

static contains(value: Any, *, case_sensitive: bool = True, normalize_spaces: bool = False) → MatchExpression¶

Match text containing a fragment.

Parameters

Name	Type	Description
value	Any	Required fragment.
case_sensitive	bool	Preserve text case.
normalize_spaces	bool	Collapse whitespace before comparison.

Returns

Type	Description
MatchExpression	Match expression.

Examples

Match.contains("case").

static starts_with(value: Any, *, case_sensitive: bool = True, normalize_spaces: bool = False) → MatchExpression¶

Match text beginning with a prefix.

Parameters

Name	Type	Description
value	Any	Required prefix.
case_sensitive	bool	Preserve text case.
normalize_spaces	bool	Collapse whitespace before comparison.

Returns

Type	Description
MatchExpression	Match expression.

Examples

Match.starts_with("Case #").

static ends_with(value: Any, *, case_sensitive: bool = True, normalize_spaces: bool = False) → MatchExpression¶

Match text ending with a suffix.

Parameters

Name	Type	Description
value	Any	Required suffix.
case_sensitive	bool	Preserve text case.
normalize_spaces	bool	Collapse whitespace before comparison.

Returns

Type	Description
MatchExpression	Match expression.

Examples

Match.ends_with(".pdf").

static regex(pattern: str | Pattern[str], flags: int = 0) → MatchExpression¶

Match a regular expression.

Parameters

Name	Type	Description
pattern	str \| Pattern[str]	Pattern text or compiled pattern.
flags	int	Flags for a string pattern.

Returns

Type	Description
MatchExpression	Match expression.

Examples

Match.regex(r"CASE-\d+").

static one_of(values: Iterable[Any], *, case_sensitive: bool = True) → MatchExpression¶

Match any value from a collection.

Parameters

Name	Type	Description
values	Iterable[Any]	Accepted values.
case_sensitive	bool	Preserve text case.

Returns

Type	Description
MatchExpression	Match expression.

Examples

Match.one_of(["ready", "complete"]).

static present() → MatchExpression¶

Match any non-None value.

Returns

Type	Description
MatchExpression	Presence expression.

Examples

Match.present().matches("").

static absent() → MatchExpression¶

Match only None.

Returns

Type	Description
MatchExpression	Absence expression.

Examples

Match.absent().matches(None).

static predicate(callback: Callable[[Any], bool], *, description: str | None = None) → MatchExpression¶

Wrap a custom predicate.

Parameters

Name	Type	Description
callback	Callable[[Any], bool]	Predicate receiving the observed value.
description	str \| None	Optional diagnostic label.

Returns

Type	Description
MatchExpression	Match expression.

Examples

Match.predicate(lambda value: int(value) > 0).

class ddp_utils.browser.facade.search.MatchExpression(callback: Callable[[Any], bool], description: str)¶

Bases: object

Store one reusable backend-neutral value predicate.

Parameters

Name	Type	Description
callback	Callable[[Any], bool]	Predicate receiving an observed value.
description	str	Human-readable diagnostic description.

Examples

Match.contains("ready").matches("not ready").

matches(actual: Any) → bool¶

Evaluate the expression.

Parameters

Name	Type	Description
actual	Any	Observed value.

Returns

Type	Description
bool	Predicate outcome.

Examples

Match.exact("ready").matches("ready").

class ddp_utils.browser.facade.search.MatchMode(value)¶

Bases: str, Enum

Supported text and attribute comparison modes.

Examples

Match a value by prefix:

mode = MatchMode.STARTS_WITH

classmethod parse(value: MatchMode | str) → MatchMode¶

Normalize a comparison mode.

Parameters

Name	Type	Description
value	MatchMode \| str	Existing mode or case-insensitive textual mode.

Returns

Type	Description
MatchMode	Parsed comparison mode.

Raises

Exception	Description
BrowserConfigurationError	The mode is unsupported.

Examples

Normalize a manifest-derived value:

mode = MatchMode.parse("starts-with")

class ddp_utils.browser.facade.search.SearchCondition(value)¶

Bases: str, Enum

Observable element states accepted by search and wait operations.

Examples

Wait for an actionable control:

condition = SearchCondition.CLICKABLE

classmethod parse(value: SearchCondition | str) → SearchCondition¶

Normalize a search condition.

Parameters

Name	Type	Description
value	SearchCondition \| str	Existing condition or case-insensitive textual condition.

Returns

Type	Description
SearchCondition	Parsed search condition.

Raises

Exception	Description
BrowserConfigurationError	The condition is unsupported.

Examples

Normalize a user option:

condition = SearchCondition.parse("Visible")

class ddp_utils.browser.facade.search.ValueMatch(value: str | Pattern[str], mode: MatchMode | str = MatchMode.EXACT, case_sensitive: bool = True)¶

Bases: object

Describe one independently configurable text or attribute comparison.

Parameters

Name	Type	Description
value	str \| Pattern[str]	Expected string or compiled regular expression.
mode	MatchMode \| str	Comparison mode.
case_sensitive	bool	Whether string comparisons preserve case.

Examples

Match an attribute by a case-insensitive suffix:

criterion = ValueMatch(".pdf", mode="ends_with", case_sensitive=False)

matches(actual: Any) → bool¶

Return whether an observed value satisfies this criterion.

Parameters

Name	Type	Description
actual	Any	Observed DOM text or attribute value.

Returns

Type	Description
bool	`True` when the configured comparison succeeds.

Examples

Test a value without a browser:

assert ValueMatch("court", mode="contains").matches("court record")