Skip to content

Query

query

A DOMQuery is a set of DOM nodes associated with a given CSS selector.

This set of nodes may be further filtered with the filter method. Additional methods apply actions to the nodes in the query.

If this sounds like JQuery, a (once) popular JS library, it is no coincidence.

DOMQuery objects are typically created by Widget.query method.

Queries are lazy. Results will be calculated at the point you iterate over the query, or call a method which evaluates the query, such as first() and last().

DOMQuery

Bases: Generic[QueryType]

nodes: list[QueryType] property

Lazily evaluate nodes.

add_class(*class_names)

Add the given class name(s) to nodes.

exclude(selector)

Exclude nodes that match a given selector.

Parameters:

Name Type Description Default
selector str

A CSS selector.

required

Returns:

Type Description
DOMQuery[QueryType]

New DOM query.

filter(selector)

Filter this set by the given CSS selector.

Parameters:

Name Type Description Default
selector str

A CSS selector.

required

Returns:

Type Description
DOMQuery[QueryType]

New DOM Query.

first(expect_type=None)

Get the first matching node.

Parameters:

Name Type Description Default
expect_type type[ExpectType] | None

Require matched node is of this type, or None for any type. Defaults to None.

None

Raises:

Type Description
WrongType

If the wrong type was found.

NoMatches

If there are no matching nodes in the query.

Returns:

Type Description
QueryType | ExpectType

The matching Widget.

last(expect_type=None)

Get the last matching node.

Parameters:

Name Type Description Default
expect_type type[ExpectType] | None

Require matched node is of this type, or None for any type. Defaults to None.

None

Raises:

Type Description
WrongType

If the wrong type was found.

NoMatches

If there are no matching nodes in the query.

Returns:

Type Description
QueryType | ExpectType

The matching Widget.

only_one(expect_type=None)

Get the only matching node.

Parameters:

Name Type Description Default
expect_type type[ExpectType] | None

Require matched node is of this type, or None for any type. Defaults to None.

None

Raises:

Type Description
WrongType

If the wrong type was found.

NoMatches

If no node matches the query.

TooManyMatches

If there is more than one matching node in the query.

Returns:

Type Description
Widget | ExpectType

The matching Widget.

refresh(*, repaint=True, layout=False)

Refresh matched nodes.

Parameters:

Name Type Description Default
repaint bool

Repaint node(s). defaults to True.

True
layout bool

Layout node(s). Defaults to False.

False

Returns:

Type Description
DOMQuery[QueryType]

Query for chaining.

remove()

Remove matched nodes from the DOM.

Returns:

Type Description
AwaitRemove

An awaitable object that waits for the widgets to be removed.

remove_class(*class_names)

Remove the given class names from the nodes.

results(filter_type=None)

Get query results, optionally filtered by a given type.

Parameters:

Name Type Description Default
filter_type type[ExpectType] | None

A Widget class to filter results, or None for no filter. Defaults to None.

None

Yields:

Type Description
Iterator[Widget | ExpectType]

Iterator[Widget | ExpectType]: An iterator of Widget instances.

set_class(add, *class_names)

Set the given class name(s) according to a condition.

Parameters:

Name Type Description Default
add bool

Add the classes if True, otherwise remove them.

required

Returns:

Type Description
DOMQuery[QueryType]

Self.

set_styles(css=None, **update_styles)

Set styles on matched nodes.

Parameters:

Name Type Description Default
css str | None

CSS declarations to parser, or None. Defaults to None.

None

toggle_class(*class_names)

Toggle the given class names from matched nodes.

InvalidQueryFormat

Bases: QueryError

Query did not parse correctly.

NoMatches

Bases: QueryError

No nodes matched the query.

QueryError

Bases: Exception

Base class for a query related error.

TooManyMatches

Bases: QueryError

Too many nodes matched the query.

WrongType

Bases: QueryError

Query result was not of the correct type.