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 itswait()
method, it will always be blocked untilfire()
is called after that. UseStatefulEvent
if you want something closer toasyncio.Event
.Changed in version 0.7.0: This is now completely different from the previous versionβs.
- fire(*args, **kwargs)ΒΆ
- class ExclusiveEventΒΆ
Similar to
Event
, but this version does not allow multiple tasks towait()
simultaneously. As a result, it operates faster.- fire(*args, **kwargs)ΒΆ
- exception InvalidStateErrorΒΆ
Operation is not allowed in the current state.
- class NurseryΒΆ
An equivalent of
trio.Nursery
. You should not directly instantiate this, useopen_nursery()
.- close()ΒΆ
Cancel all the child tasks in the nursery as soon as possible.
- 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 anAwaitable
, it will be wrapped in a Task, and that Task will be returned.The
daemon
parameter acts like the one in thethreading
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 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', }
- class Task(aw: Awaitable, /)ΒΆ
- cancel()ΒΆ
Cancel the task as soon as possible.
- property result: AnyΒΆ
Result of the task. If the task is not finished,
InvalidStateError
will be raised.
- 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 totrio_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.")