textual.css.query

This module contains the DOMQuery class and related objects.

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

DOMQuery(
    node,
    *,
    filter=None,
    exclude=None,
    deep=True,
    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
deep	bool	Query should be deep, i.e. recursive.	True
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

The node being queried.

nodes property

nodes

Lazily evaluate nodes.

add_class

add_class(*class_names)

Add the given class name(s) to nodes.

blur

blur()

Blur the first matching node that is focused.

Returns:

Type	Description
DOMQuery[QueryType]	Query for chaining.

exclude

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

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

first() -> QueryType

first(expect_type: type[ExpectType]) -> ExpectType

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.	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.

focus