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.

ExpectType module-attribute

ExpectType = TypeVar('ExpectType')

Type variable used to further restrict queries.

QueryType module-attribute

QueryType = TypeVar('QueryType', bound='Widget')

Type variable used to type generic queries.

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

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

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.

blur method

def blur(self):

Blur the first matching node that is focused.

Returns

Type	Description
DOMQuery[QueryType]	Query for chaining.

exclude method

def exclude(self, selector):

Exclude nodes that match a given selector.

Parameters

Parameter	Default	Description
selector str	required	A CSS selector.

Returns

Type	Description
DOMQuery[QueryType]	New DOM query.

filter method

def filter(self, selector):

Filter this set by the given CSS selector.

Parameters

Parameter	Default	Description
selector str	required	A CSS selector.

Returns

Type	Description
DOMQuery[QueryType]	New DOM Query.

first method

def first(self, expect_type=None):

Get the first matching node.

Parameters

Parameter	Default	Description
expect_type type[ExpectType] | None	None	Require matched node is of this type, or None for any type.

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.

focus method

def focus(self):

Focus the first matching node that permits focus.

Returns

Type	Description
DOMQuery[QueryType]	Query for chaining.

last method

def last(self, expect_type=None):

Get the last matching node.

Parameters

Parameter	Default	Description
expect_type type[ExpectType] | None	None	Require matched node is of this type, or None for any type.

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

Parameter	Default	Description
expect_type type[ExpectType] | None	None	Require matched node is of this type, or None for any type.

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
QueryType | ExpectType	The matching Widget.

refresh method

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

Refresh matched nodes.

Parameters

Parameter	Default	Description
repaint bool	True	Repaint node(s).
layout bool	False	Layout node(s).
recompose bool	False	Recompose node(s).

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

Parameter	Default	Description
filter_type type[ExpectType] | None	None	A Widget class to filter results, or None for no filter.

Yields:

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

set method

def set(
    self,
    display=None,
    visible=None,
    disabled=None,
    loading=None,
):

Sets common attributes on matched nodes.

Parameters

Parameter	Default	Description
display bool | None	None	Set display attribute on nodes, or None for no change.
visible bool | None	None	Set visible attribute on nodes, or None for no change.
disabled bool | None	None	Set disabled attribute on nodes, or None for no change.
loading bool | None	None	Set loading attribute on nodes, or None for no change.

Returns

Type	Description
DOMQuery[QueryType]	Query for chaining.

set_class method

def set_class(self, add, *class_names):

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

Parameters

Parameter	Default	Description
add bool	required	Add the classes if True, otherwise remove them.

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

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

Returns

Type	Description
DOMQuery[QueryType]	Self.

set_styles method

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

Set styles on matched nodes.

Parameters

Parameter	Default	Description
css str | None	None	CSS declarations to parser, or 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.