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.

textual.css.query

ExpectType module-attribute ¶

QueryType module-attribute ¶

DOMQuery ¶

node ¶

filter ¶

exclude ¶

deep ¶

parent ¶

node property ¶

nodes property ¶

add_class ¶

blur ¶

exclude ¶

selector ¶

filter ¶

selector ¶

first ¶

expect_type ¶

focus ¶

last ¶

expect_type ¶

only_one ¶

expect_type ¶

refresh ¶

repaint ¶

layout ¶

recompose ¶

remove ¶

remove_class ¶

results ¶

filter_type ¶

set ¶

display ¶

visible ¶

disabled ¶

loading ¶

set_class ¶

add ¶

set_classes ¶

classes ¶

set_styles ¶

css ¶

toggle_class ¶

InvalidQueryFormat ¶

NoMatches ¶

QueryError ¶

TooManyMatches ¶

WrongType ¶

ExpectType `module-attribute` ¶

QueryType `module-attribute` ¶

`node` ¶

`filter` ¶

`exclude` ¶

`deep` ¶

`parent` ¶

node `property` ¶

nodes `property` ¶

`selector` ¶

`selector` ¶

`expect_type` ¶

`expect_type` ¶

`expect_type` ¶

`repaint` ¶

`layout` ¶

`recompose` ¶

`filter_type` ¶

`display` ¶

`visible` ¶

`disabled` ¶

`loading` ¶

`add` ¶

`classes` ¶

`css` ¶