textual.worker
This module contains the Worker
class and related objects.
See the guide for how to use workers.
WorkType
module-attribute
¶
WorkType: TypeAlias = Union[
Callable[[], Coroutine[None, None, ResultType]],
Callable[[], ResultType],
Awaitable[ResultType],
]
Type used for workers.
active_worker
module-attribute
¶
Currently active worker context var.
DeadlockError ¶
Bases: WorkerError
The operation would result in a deadlock.
Worker ¶
Bases: Generic[ResultType]
A class to manage concurrent work (either a task or a thread).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
node |
DOMNode
|
The widget, screen, or App that initiated the work. |
required |
work |
WorkType
|
A callable, coroutine, or other awaitable object to run in the worker. |
required |
name |
str
|
Name of the worker (short string to help identify when debugging). |
''
|
group |
str
|
The worker group. |
'default'
|
description |
str
|
Description of the worker (longer string with more details). |
''
|
exit_on_error |
bool
|
Exit the app if the worker raises an error. Set to |
True
|
thread |
bool
|
Mark the worker as a thread worker. |
False
|
cancelled_event
instance-attribute
¶
A threading event set when the worker is cancelled.
error
property
¶
The exception raised by the worker, or None
if there was no error.
is_cancelled
property
¶
Has the work been cancelled?
Note that cancelled work may still be running.
progress
property
¶
Progress as a percentage.
If the total steps is None, then this will return 0. The percentage will be clamped between 0 and 100.
result
property
¶
The result of the worker, or None
if there is no result.
StateChanged ¶
Bases: Message
The worker state changed.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
worker |
Worker
|
The worker object. |
required |
state |
WorkerState
|
New state. |
required |
advance ¶
Advance the number of completed steps.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
steps |
int
|
Number of steps to advance. |
1
|
run
async
¶
Run the work.
Implement this method in a subclass, or pass a callable to the constructor.
Returns:
Type | Description |
---|---|
ResultType
|
Return value of the work. |
update ¶
wait
async
¶
Wait for the work to complete.
Raises:
Type | Description |
---|---|
WorkerFailed
|
If the Worker raised an exception. |
WorkerCancelled
|
If the Worker was cancelled before it completed. |
Returns:
Type | Description |
---|---|
ResultType
|
The return value of the work. |
WorkerCancelled ¶
Bases: WorkerError
The worker was cancelled and did not complete.
WorkerFailed ¶
WorkerState ¶
A description of the worker's current state.
get_current_worker ¶
Get the currently active worker.
Raises:
Type | Description |
---|---|
NoActiveWorker
|
If there is no active worker. |
Returns:
Type | Description |
---|---|
Worker
|
A Worker instance. |