ddp_utils.browser.facade.collections

import ddp_utils.browser.facade.collections

Ordered backend-neutral browser element collections.

class ddp_utils.browser.facade.collections.BrowserCollection(items: Sequence[BrowserElement] = ())

Bases: Sequence[BrowserElement]

Provide stable sequence and bulk operations for matched elements.

Parameters

Name	Type	Description
items	Sequence[BrowserElement]	Ordered browser elements.

Examples

Iterate search results without backend-specific collection objects:

for row in browser.find_all("tr", attrs={"data-result": True}):
    print(row.text)

Freeze one ordered element snapshot.

Parameters

Name	Type	Description
items	Sequence[BrowserElement]	Elements in backend-observed document order.

Examples

Wrap adapter results:

collection = BrowserCollection(elements)

property first: BrowserElement | None

Return the first element when present.

Returns

First element or None for an empty collection.

Examples

Use an optional first match:

first = rows.first

property last: BrowserElement | None

Return the last element when present.

Returns

Last element or None for an empty collection.

Examples

Inspect the final result:

last = rows.last

count() → int

Return the number of elements.

Returns

Type	Description
int	Element count.

Examples

assert rows.count() == 10.

nth(index: int) → BrowserElement

Return one element by Python index.

Parameters

Name	Type	Description
index	int	Positive or negative index.

Returns

Type	Description
BrowserElement	Selected element.

Examples

third = rows.nth(2).

all() → list[BrowserElement]

Return a mutable list snapshot.

Returns

Type	Description
list[BrowserElement]	Elements in document order.

Examples

items = rows.all().

texts() → list[str]

Return visible text for every element.

Returns

Type	Description
list[str]	Text values in collection order.

Examples

Compare all option labels:

assert "Fulton" in options.texts()

values() → list[Any]

Return live values for every element.

Returns

Type	Description
list[Any]	Values in collection order.

Examples

submitted = fields.values().

filter(*, text: Any = None, attrs: dict[str, Any] | None = None, **conditions: Any) → BrowserCollection

Return elements satisfying structured local criteria.

Parameters

Name	Type	Description
text	Any	Optional visible-text criterion.
attrs	dict[str, Any] | None	Optional attribute criteria.
**conditions	Any	Match mode, case policy, state, or predicate.

Returns

Type	Description
BrowserCollection	New ordered collection containing accepted elements.

Raises

Exception	Description
ElementActionError	If unsupported filter conditions are passed.

Examples

Keep visible rows only:

visible = rows.filter(condition="visible")

has(query: Any) → BrowserCollection

Keep elements containing a matching descendant.

Parameters

Name	Type	Description
query	Any	CSS selector, structured mapping, or callback.

Returns

Type	Description
BrowserCollection	Filtered collection.

Raises

Exception	Description
ElementActionError	If query is not a selector, mapping or callback.

Examples

cards_with_links = cards.has("a.details").

has_not(query: Any) → BrowserCollection

Keep elements without a matching descendant.

Parameters

Name	Type	Description
query	Any	CSS selector, structured mapping, or callback.

Returns

Type	Description
BrowserCollection	Filtered collection.

Examples

empty_cards = cards.has_not("a.details").

slice(start: int | None = None, stop: int | None = None, step: int | None = None) → BrowserCollection

Return a sliced collection.

Parameters

Name	Type	Description
start	int | None	Inclusive start index.
stop	int | None	Exclusive stop index.
step	int | None	Slice step.

Returns

Type	Description
BrowserCollection	New collection.

Examples

page = rows.slice(0, 10).

unique(*, by: str = 'identity') → BrowserCollection

Remove duplicates while preserving order.

Parameters

Name	Type	Description
by	str	identity, text, value, or attribute name.

Returns

Type	Description
BrowserCollection	Deduplicated collection.

Examples

unique_links = links.unique(by="href").

map(callback: Callable[[BrowserElement], Any]) → list[Any]

Map a callback over elements.

Parameters

Name	Type	Description
callback	Callable[[BrowserElement], Any]	Element transformation.

Returns

Type	Description
list[Any]	Callback results.

Examples

ids = rows.map(lambda row: row.get("id")).

for_each(callback: Callable[[BrowserElement], Any]) → BrowserCollection

Invoke a callback for every element.

Parameters

Name	Type	Description
callback	Callable[[BrowserElement], Any]	Element consumer.

Returns

Type	Description
BrowserCollection	This collection.

Examples

rows.for_each(lambda row: row.highlight()).

click(*, required: bool = True) → CollectionActionResult[BrowserElement]

Click every element in order.

Parameters

Name	Type	Description
required	bool	Raise on the first failure when true.

Returns

Type	Description
CollectionActionResult[BrowserElement]	Ordered per-element action results.

Examples

Expand every visible disclosure control:

result = buttons.click(required=False)

show(*, timeout: float | None = None, stop_on_error: bool = True) → CollectionActionResult[BrowserElement]

Restore every facade-hidden element.

Parameters

Name	Type	Description
timeout	float | None	Optional per-element verification deadline.
stop_on_error	bool	Stop after the first failed element.

Returns

Type	Description
CollectionActionResult[BrowserElement]	Ordered per-element action results.

Examples

Restore a group of elements:

results.show()

hide(*, timeout: float | None = None, stop_on_error: bool = True) → CollectionActionResult[BrowserElement]

Hide every element and verify each result.

Parameters

Name	Type	Description
timeout	float | None	Optional per-element verification deadline.
stop_on_error	bool	Stop after the first failed element.

Returns

Type	Description
CollectionActionResult[BrowserElement]	Ordered per-element action results.

Examples

Hide multiple overlays:

overlays.hide(stop_on_error=False)

attributes(name: str) → list[str | None]

Return one attribute for every element.

Parameters

Name	Type	Description
name	str	Attribute name.

Returns

Type	Description
list[str | None]	Attribute values in collection order.

Examples

Read every result URL:

urls = links.attributes("href")

click_each(*, timeout: float | None = None, stop_on_error: bool = True) → CollectionActionResult[BrowserElement]

Click every element in order.

Parameters

Name	Type	Description
timeout	float | None	Per-element timeout.
stop_on_error	bool	Stop after the first failure.

Returns

Type	Description
CollectionActionResult[BrowserElement]	Ordered action results.

Examples

result = buttons.click_each(stop_on_error=False).

fill_each(values: Any, *, timeout: float | None = None) → CollectionActionResult[BrowserElement]

Fill every element from scalar or per-element values.

Parameters

Name	Type	Description
values	Any	Scalar value or sequence matching collection length.
timeout	float | None	Per-element timeout.

Returns

Type	Description
CollectionActionResult[BrowserElement]	Ordered action results.

Raises

Exception	Description
ElementActionError	If the number of values differs from the length of the collection.

Examples

result = fields.fill_each(["John", "Smith"]).

wait(*, timeout: float, minimum: int | None = None, maximum: int | None = None, count: int | None = None, **conditions: Any) → BrowserCollection

Wait until current elements satisfy state and cardinality constraints.

Parameters

Name	Type	Description
timeout	float	Deadline in seconds.
minimum	int | None	Optional minimum count.
maximum	int | None	Optional maximum count.
count	int | None	Optional exact count.
**conditions	Any	Element boolean property expectations.

Returns

Type	Description
BrowserCollection	Accepted collection.

Raises

Exception	Description
ElementActionError	If the collection snapshot is empty: an empty snapshot cannot acquire new elements, so the query has to be repeated.

Examples

ready = rows.wait(timeout=10, minimum=1, visible=True).

property native: tuple[Any, ...]

Return provider-native elements.

Returns

Native elements in collection order.

Examples

native = rows.native.

native_items() → tuple[Any, ...]

Return explicit native element escape hatches.

Returns

Type	Description
tuple[Any, …]	Native elements in collection order.

Examples

Use a provider-only bulk operation intentionally:

native = collection.native_items()