Query

A DOMQuery is a set of DOM nodes returned by query.

The set of nodes may be further refined with filter and exclude. Additional methods apply actions to all nodes in the query.

Info

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

DOMQuery class

def __init__(
    self, node, *, filter=None, exclude=None, parent=None
):

Bases: Generic[QueryType]

Warning

You won't need to construct this manually, as DOMQuery objects are returned by query.

Parameters

Name	Type	Description	Default
node	DOMNode	A DOM node.	required
filter	str | None	Query to filter children in the node.	None
exclude	str | None	Query to exclude children in the node.	None
parent	DOMQuery | None	The parent query, if this is the result of filtering another query.	None

Raises

Type	Description
InvalidQueryFormat	If the format of the query is invalid.

node property

node: DOMNode

The node being queried.

nodes property

nodes: list[QueryType]

Lazily evaluate nodes.

add_class method

def add_class(self, *class_names):

Add the given class name(s) to nodes.

exclude method

def exclude(self, 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 method

def filter(self, 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 method

def first(self, 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.	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 method

def last(self, 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.	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 method

def only_one(self, 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.	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 method

def refresh(self, *, repaint=True, layout=False):

Refresh matched nodes.

Parameters

Name	Type	Description	Default
repaint	bool	Repaint node(s).	True
layout	bool	Layout node(s).	False

Returns

Type	Description
DOMQuery[QueryType]	Query for chaining.

remove method

def remove(self):

Remove matched nodes from the DOM.

Returns

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

remove_class method

def remove_class(self, *class_names):

Remove the given class names from the nodes.

results method

def results(self, 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.	None

Yields:

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

set_class method

def set_class(self, 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_classes method

def set_classes(self, classes):

Set the classes on nodes to exactly the given set.

Parameters

Name	Type	Description	Default
classes	str | Iterable[str]	A string of space separated classes, or an iterable of class names.	required

Returns

Type	Description
DOMQuery[QueryType]	Self.

set_styles method

def set_styles(self, css=None, **update_styles):

Set styles on matched nodes.

Parameters

Name	Type	Description	Default
css	str | None	CSS declarations to parser, or None.	None

toggle_class method

def toggle_class(self, *class_names):

Toggle the given class names from matched nodes.

InvalidQueryFormat class

Bases: QueryError

Query did not parse correctly.

NoMatches class

Bases: QueryError

No nodes matched the query.

QueryError class

Bases: Exception

Base class for a query related error.

TooManyMatches class

Bases: QueryError

Too many nodes matched the query.

WrongType class

Bases: QueryError

Query result was not of the correct type.