API Reference

Cancelled

Exception class that represents cancellation. See Dealing with Cancellation.

Warning

Actually, this is not an exception class but a tuple of exception classes for now. But that’s an implementation detail, and it might become an actual class in the future; therefore, your code must be compatible in both cases.

class Event

async def async_fn(e):
    args, kwargs = await e.wait()
    assert args == (2, )
    assert kwargs == {'crow': 'raven', }

    args, kwargs = await e.wait()
    assert args == (3, )
    assert kwargs == {'toad': 'frog', }

e = Event()
e.fire(1, crocodile='alligator')
task = start(async_fn(e))
e.fire(2, crow='raven')
e.fire(3, toad='frog')
assert task.finished

Warning

This differs significantly from asyncio.Event, as this one does not have a “set” state. When a Task calls its wait() method, it will always be blocked until fire() is called after that. Use StatefulEvent if you want something closer to asyncio.Event.

Changed in version 0.7.0: This is now completely different from the previous version’s.

fire(*args, **kwargs)

wait() → Awaitable[tuple[tuple, dict]]

Waits for the event to be fired.

class ExclusiveEvent

Similar to Event, but this version does not allow multiple tasks to wait() simultaneously. As a result, it operates faster.

fire(*args, **kwargs)

wait() → Awaitable[tuple[tuple, dict]]

exception InvalidStateError

Operation is not allowed in the current state.

class Nursery

An equivalent of trio.Nursery. You should not directly instantiate this, use open_nursery().

close()

Cancel all the child tasks in the nursery as soon as possible.

property closed: bool

start(aw: Awaitable | Task, /, *, daemon=False) → Task

Immediately start a Task under the supervision of the nursery.

If the argument is a Task, itself will be returned. If it’s an Awaitable, it will be wrapped in a Task, and that Task will be returned.

The daemon parameter acts like the one in the threading module. When only daemon tasks are left, they get cancelled, and the nursery closes.

class StatefulEvent

The closest thing to asyncio.Event in this library.

StatefulEvent	asyncio.Event
.fire()	.set()
.wait()	.wait()
.clear()	.clear()
.is_fired	.is_set()
.params	–

async def async_fn(e):
    args, kwargs = await e.wait()
    assert args == (1, )
    assert kwargs == {'crow': 'raven', }

e = StatefulEvent()
task = start(async_fn(e))
assert not task.finished
e.fire(1, crow='raven')
assert task.finished

Added in version 0.7.2.

Changed in version 0.9.0: The .refire() and .fire_or_refire() methods have been removed.

clear()

Sets the event to a non-fired state.

fire(*args, **kwargs)

Fires the event if it’s not in a fired state.

property is_fired: bool

property params: tuple

The parameters passed to the last fire. Raises InvalidStateError if the event is not in a “fired” state. This is a convenient way to access the parameters from synchronous code.

e = StatefulEvent()

e.fire(1, crow='raven')
args, kwargs = e.params
assert args == (1, )
assert kwargs == {'crow': 'raven', }

e.clear()
e.fire(2, parasol='umbrella')
args, kwargs = e.params
assert args == (2, )
assert kwargs == {'parasol': 'umbrella', }

wait() → Awaitable[tuple[tuple, dict]]

StatelessEvent

An alias of Event.

Added in version 0.7.2.

class Task(aw: Awaitable, /)

cancel()

Cancel the task as soon as possible.

property cancelled: bool

Whether the task has been cancelled.

close()

An alias of cancel().

property finished: bool

Whether the task has completed execution.

property result: Any

Result of the task. If the task is not finished, InvalidStateError will be raised.

property root_coro: Coroutine

The starting point of the coroutine chain for the task.

property state: TaskState

The current state of the task.

class TaskState

Enum class that represents the Task state.

CANCELLED

The execution has been cancelled. The cause of the cancellation is either an explicit or implicit call to Task.cancel() or an unhandled exception.

CREATED

Waiting to start execution.

FINISHED

The execution has been completed.

STARTED

Currently running or suspended.

current_task() → Awaitable[Task]

Returns the Task instance corresponding to the caller.

task = await current_task()

dummy_task = <asyncgui.Task object>

An already closed task. This can be utilized to prevent the need for the common null validation mentioned below.

Before:

class MyClass:
    def __init__(self):
        self._task = None

    def restart(self):
        if self._task is not None:
            self._task.cancel()
        self._task = asyncgui.start(self.main())

    async def main(self):
        ...

After:

class MyClass:
    def __init__(self):
        self._task = asyncgui.dummy_task

    def restart(self):
        self._task.cancel()
        self._task = asyncgui.start(self.main())

    async def main(self):
        ...

move_on_when(aw: Awaitable | Task) → AbstractAsyncContextManager[Task]

An alias of wait_any_cm(), which is equivalent to trio_util.move_on_when().

open_nursery() → AbstractAsyncContextManager[Nursery]

An equivalent of trio.open_nursery().

async with open_nursery() as nursery:
    nursery.start(async_fn1())
    nursery.start(async_fn2(), daemon=True)

run_as_daemon(aw: Awaitable | Task) → AbstractAsyncContextManager[Task]

Runs the given task and the code inside the with-block concurrently, and waits for the with-block to complete. As soon as that happens, the task will be cancelled if it is still running.

This is equivalent to trio_util.run_and_cancelling().

async with run_as_daemon(async_fn()) as task:
    ...
if task.finished:
    print(f"async_fn completed with a return value of {task.result}.")
else:
    print(f"async_fn was cancelled.")

run_as_main(aw: Awaitable | Task) → AbstractAsyncContextManager[Task]

Runs the given task and the code inside the with-block concurrently, and waits for the task to either complete or be cancelled. As soon as that happens, the with-block will be cancelled if it is still running.

async with run_as_main(async_fn()) as task:
    ...
if task.finished:
    print(f"async_fn completed with a return value of {task.result}.")
else:
    print(f"async_fn was cancelled.")

sleep_forever()

await sleep_forever()

start(aw: Awaitable | Task, /) → Task

Immediately start a Task.

async def async_func():
    ...

task = start(async_func())

Warning

Tasks started with this function are root tasks. You must ensure they aren’t garbage-collected while still running –for example, by explicitly calling Task.cancel() before the program exits.

async wait_all(*aws: Iterable[Awaitable | Task]) → Awaitable[Sequence[Task]]

Runs multiple tasks concurrently, and waits for all of them to either complete or be cancelled.

tasks = await wait_any(async_fn0(), async_fn1(), async_fn2())
for i, task in enumerate(tasks):
    if task.finished:
        print(f"async_fn{i} completed with a return value of {task.result}.")
    else:
        print(f"async_fn{i} was cancelled.")

wait_all_cm(aw: Awaitable | Task) → AbstractAsyncContextManager[Task]

Runs the given task and the code inside the with-block concurrently, and waits for the with-block to complete and for the task to either complete or be cancelled.

async with wait_all_cm(async_fn()) as task:
    ...
if task.finished:
    print(f"async_fn completed with a return value of {task.result}.")
else:
    print(f"async_fn was cancelled.")

async wait_any(*aws: Iterable[Awaitable | Task]) → Awaitable[Sequence[Task]]

Runs multiple tasks concurrently and waits until either one completes or all are cancelled. As soon as one completes, the others will be cancelled.

tasks = await wait_any(async_fn0(), async_fn1(), async_fn2())
for i, task in enumerate(tasks):
    if task.finished:
        print(f"async_fn{i} completed with a return value of {task.result}.")
    else:
        print(f"async_fn{i} was cancelled.")

wait_any_cm(aw: Awaitable | Task) → AbstractAsyncContextManager[Task]

Runs the given task and the code inside the with-block concurrently, and waits for either one to complete. As soon as that happens, the other will be cancelled if it is still running.

This is equivalent to trio_util.move_on_when().

async with wait_any_cm(async_fn()) as task:
    ...
if task.finished:
    print(f"async_fn completed with a return value of {task.result}.")
else:
    print(f"async_fn was cancelled.")