Quick Start

This package implements JavaScript-style promises in Python with the asyncio package. The JavaScript Promise documentation is a good introductory reference.

To create a promise-based async function use the promisio.promisify() decorator. This decorator works on both sync and async functions. Regardless of the type of source function, the resulting function is always asynchronous.

Example:

import asyncio
from promisio import promisify

@promisify
async def f():
    await asyncio.sleep(1)
    return 42

@promisify
def g(x):
    return x * 2

async def main():
    print(await f())  # prints 42
    print(await g(42))  # prints 84

    promise = f()  # runs function in the background without waiting
    # ... do other stuff here in parallel with f running
    await promise  # finally wait for f to complete

asyncio.run(main())

The return value of a function that is decorated with promisify is a JavaScript-style promise object. Promises are awaitable, so the syntax to call and wait for a promise-based function is identical to that of a coroutine-based function.

The main difference is that promise-based functions can be called like regular functions and do not have to be awaited for them to start. When a promise-based function is called without awaiting, the function starts running while the calling function continues to execute.

Promise objects offer the promisio.Promise.then(), promisio.Promise.catch() and promisio.Promise.finally_() methods to chain promises as in JavaScript. These can be used in sync or async functions to work asychronously through promise callbacks. Once again, these methods work as their JavaScript counterparts.

The promisio.Promise.all(), promisio.Promise.all_settled(), promisio.Promise.any(), promisio.Promise.race(), promisio.Promise.resolve() and promisio.Promise.reject() functions are also available.

While promise cancellation is not possible with JavaScript promises, this package is extended to support cancellation via the promisio.Promise.cancel() and promisio.Promise.cancelled() methods. A cancelled promise gets rejected with a asyncio.CancelledError exception.