API Reference

class promisio.Promise(f=None)

A promise class.

Parameters:

f – the promise function. If this argument is omitted, the promise is created without an associated function. The provided function must accept two arguments, resolve and reject that settle the promise by fullfilling it or rejecting it respectively.

Note: Creating a promise object directly is often unnecessary. The promisify() decorator is a much more convenient option.

then(on_resolved=None, on_rejected=None)

Appends fulfillment and rejection handlers to the promise.

Parameters:

• on_resolved – an optional fulfillment handler.

• on_rejected – an optional rejection handler.

Returns a new promise that resolves to the return value of the called handler, or to the original settled value if a handler was not provided.

catch(on_rejected)

Appends a rejection handler callback to the promise.

Parameters:

on_rejected – the rejection handler.

Returns a new promise that resolves to the return value of the handler.

finally_(on_settled)

Appends a fulfillment and reject handler to the promise.

Parameters:

on_settled – the handler.

The handler is invoked when the promise is fulfilled or rejected. Returns a new promise that resolves when the original promise settles.

cancel()

Cancels a promise, if possible.

A promise that is cancelled rejects with a asyncio.CancelledError.

cancelled()

Checks if a promise has been cancelled.

static resolve(value)

Returns a new Promise object that resolves to the given value.

Parameters:

value – the value the promise will resolve to.

If the value is another Promise instance, the new promise will resolve or reject when this promise does. If the value is an asyncio Task object, the new promise will be associated with the task and will pass cancellation requests to it if its Promise.cancel() method is invoked. Any other value creates a promise that immediately resolves to the value.

static reject(reason)

Returns a new promise object that is rejected with the given reason.

Parameters:

reason – the rejection reason. Must be an Exception instance.

static all(promises)

Wait for all promises to be resolved, or for any to be rejected.

Parameters:

promises – a list of promises to wait for.

Returns a promise that resolves to a aggregating list of all the values from the resolved input promises, in the same order as given. If one or more of the input promises are rejected, the returned promise is rejected with the reason of the first rejected promise.

static all_settled(promises)

Wait until all promises are resolved or rejected.

Parameters:

promises – a list of promises to wait for.

Returns a promise that resolves to a list of dicts, where each dict describes the outcome of each promise. For a promise that was fulfilled, the dict has this format:

{'status': 'fulfilled', 'value': <resolved-value>}

For a promise that was rejected, the dict has this format:

{'status': 'rejected', 'reason': <rejected-reason>}

static any(promises)

Wait until any of the promises given resolves.

Oaram promises:

a list of promises to wait for.

Returns a promise that resolves with the value of the first input promise. Promise rejections are ignored, except when all the input promises are rejected, in which case the returned promise rejects with an AggregateError.

static race(promises)

Wait until any of the promises is fulfilled or rejected.

Parameters:

promises – a list of promises to wait for.

Returns a promise that resolves or rejects with the first input promise that settles.

promisio.promisify(func)

Create a promise-based async function from regular or async functions.

Examples:

@promisify
def add(arg1, arg2):
    return arg1 + arg2

@promisify
async def random_sleep():
    await asyncio.sleep(random.random())

async def test():
    result = await add(1, 2)
    await random_sleep()

promisio.run(func, *args, **kwargs)

Run an async loop until the given promise-based function returns.

Parameters:

• func – the promise-based function to run.

• args – positional arguments to pass to the function.

• kwargs – keyword arguments to pass to the function.