quattro 22.2.0

Installation

To install quattro, simply:

$ pip install quattro

Task Groups

quattro contains a TaskGroup implementation. TaskGroups are inspired by Trio nurseries.

from quattro import TaskGroup

async def my_handler():
    # We want to spawn some tasks, and ensure they are all handled before we return.
    async def task_1():
        ...

    async def task_2():
        ...

    async with TaskGroup() as tg:
        t1 = tg.create_task(task_1)
        t2 = tg.create_task(task_2)

    # The end of the `async with` block awaits the tasks, ensuring they are handled.

TaskGroups are essential building blocks for achieving the concept of structured concurrency. In simple terms, structured concurrency means your code does not leak tasks - when a coroutine finishes, all tasks spawned by that coroutine and all its children are also finished. (In fancy terms, the execution flow becomes a directed acyclic graph.)

Structured concurrency can be achieved by using TaskGroups instead of asyncio.create_task to start background tasks. TaskGroups essentially do two things:

• when exiting from a TaskGroup async with block, the TaskGroup awaits all of its children, ensuring they are finished when it exits

• when a TaskGroup child task raises an exception, all other children and the task inside the context manager are cancelled

The implementation has been borrowed from the EdgeDB project.

Cancel Scopes

quattro contains an independent, asyncio implementation of Trio CancelScopes. Due to fundamental differences between asyncio and Trio the actual runtime behavior isn’t exactly the same, but close.

from quattro import move_on_after

async def my_handler():
    with move_on_after(1.0) as cancel_scope:
        await long_query()

    # 1 second later, the function continues running

quattro contains the following helpers:

• move_on_after

• move_on_at

• fail_after

• fail_at

All helpers produce instances of quattro.CancelScope, which is largely similar to the Trio variant.

CancelScopes have the following attributes:

• cancel() - a method through which the scope can be cancelled manually. cancel() can be called before the scope is entered; entering the scope will cancel it at the first opportunity

• deadline - read/write, an optional deadline for the scope, at which the scope will be cancelled

• cancelled_caught - a readonly bool property, whether the scope finished via cancellation

quattro also supports retrieving the current effective deadline in a task using quattro.current_effective_deadline. The current effective deadline is a float value, with float('inf') standing in for no deadline.

Python versions 3.11 and higher contain similar helpers, asyncio.timeout and asyncio.timeout_at. The quattro fail_after and fail_at helpers are effectively equivalent to the asyncio timeouts, and pass the test suite for them.

The differences are:

• The quattro versions are normal context managers (used with just with), asyncio versions are async context managers (using async with). Neither version needs to be async since nothing is awaited; quattro chooses to be non-async to signal there are no suspension points being hit, match Trio and be a little more readable.

• quattro additionally contains the move_on_at and move_on_after helpers.

• The quattro versions support getting the current effective deadline.

• The quattro versions can be cancelled manually using scope.cancel(), and precancelled before they are entered

• The quattro versions are available on all supported Python versions, not just 3.11+.

with trio.move_on_after(TIMEOUT):
    conn = make_connection()
    try:
        await conn.send_hello_msg()
    finally:
        await conn.send_goodbye_msg()

Changelog

Credits

The initial TaskGroup implementation has been taken from the EdgeDB project. The CancelScope implementation was heavily influenced by Trio, and inspired by the async_timeout package.