Capture the result of a Trio or anyio task
Project description
Welcome to aioresult! This is a very small library to capture the result of an asynchronous operation, either an async function (with the ResultCapture class) or more generally (with the Future class). It works with Trio nurseries and anyio task groups. It is not needed for Python 3.11 asyncio task groups because those already return an object representing the task, allowing the result to be retrieved.
The code is hosted on github: https://github.com/arthur-tacca/aioresult
Documentation is on ReadTheDocs: https://aioresult.readthedocs.io/en/stable/docs.html
Quick Overview
The ResultCapture class runs an async function in a nursery and stores its return value (or raised exception) for later:
async with trio.open_nursery() as n: result1 = ResultCapture.start_soon(n, foo, 1) result2 = ResultCapture.start_soon(n, foo, 2) # At this point the tasks have completed, and results are stashed in ResultCapture objects print("results", result1.result(), result2.result())
When stored in list, the effect is very similar to the asyncio gather() function:
async with trio.open_nursery() as n: results = [aioresult.ResultCapture.start_soon(n, foo, i) for i in range(10)] print("results:", *[r.result() for r in results])
There is also a derived class StartableResultCapture, meant for async functions that satisfy the Trio task start protocol.
There is also a simple Future class that shares a lot of its code with ResultCapture. The result is retrieved the same way, but it is set explicitly rather than captured from a task. It is most often used when an API wants to return a value that will be demultiplexed from a shared connection:
# When making a request, create a future, store it for later and return to caller f = aioresult.Future() # The result is set, usually inside a networking API f.set_result(result) # The calling code can wait for the result then retrieve it await f.wait_done() print("result:", f.result())
The interface in Future and ResultCapture to wait for a result and retrieve it is shared in a base class ResultBase.
Installation and Usage
Install into a suitable virtual environment with pip:
pip install aioresult
aioresult can be used with Trio nurseries:
import trio from aioresult import ResultCapture async def wait_and_return(i): await trio.sleep(i) return i async def use_aioresult(): async with trio.open_nursery() as n: results = [ResultCapture.start_soon(n, wait_and_return, i) for i in range(5)] print("results:", *[r.result() for r in results]) if __name__ == "__main__": trio.run(use_aioresult)
It can also be used with anyio task groups:
import asyncio import anyio from aioresult import ResultCapture async def wait_and_return(i): await anyio.sleep(i) return i async def use_aioresult(): async with anyio.create_task_group() as tg: results = [ResultCapture.start_soon(tg, wait_and_return, i) for i in range(5)] print("results:", *[r.result() for r in results]) if __name__ == "__main__": asyncio.run(use_aioresult())
Running the Tests
The automated tests are currently not run through any automated pipeline. To run them yourself, start by installing the dependencies:
pip install pytest coverage anyio trio
To just run the tests, run pytest in the root of the repository:
python -m pytest
To also get coverage information, run it with the coverage command:
coverage run -m pytest
You can then use coverage html to get a nice HTML output of exactly what code has been tested and what has been missed.
License
Copyright Arthur Tacca 2022
Distributed under the Boost Software License, Version 1.0. See accompanying file LICENSE or the copy at https://www.boost.org/LICENSE_1_0.txt
This is similar to other liberal licenses like MIT and BSD: you can use this library without the need to share your program’s source code, so long as you provide attribution of aioresult.
The Boost license has the additional provision that you do not even need to provide attribution if you are distributing your software in binary form only, e.g. if you have compiled to an executable with Nuitka. (Bundlers like pyinstaller and py2exe don’t count for this because they still include the source code internally.)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.