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.