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

focus()

Focus the first matching node that permits focus.

Returns:

Type	Description
DOMQuery[QueryType]	Query for chaining.

last

last() -> QueryType

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

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

only_one() -> QueryType

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

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

refresh

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

Refresh matched nodes.

Parameters:

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

Returns:

Type	Description
DOMQuery[QueryType]	Query for chaining.

remove

remove()

Remove matched nodes from the DOM.

Returns:

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

remove_class

remove_class(*class_names)

Remove the given class names from the nodes.

results

results() -> Iterator[QueryType]

results(
    filter_type: type[ExpectType],
) -> Iterator[ExpectType]

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

Yields:

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

set

set(
    display=None, visible=None, disabled=None, loading=None
)

Sets common attributes on matched nodes.

Parameters:

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

Returns:

Type	Description
DOMQuery[QueryType]	Query for chaining.

set_class

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_classes

set_classes(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

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

toggle_class

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.