EAsync -- easy async decorator and promises

@async

Decorator around the functions for them to be asynchronous.

Used as a simple decorator or along with named arguments. Preserves function's or method's docs, names and other stuff using functools.wraps.

When the wrapped function is called, it produces the Promise of itself.

Usage:

>>> from easync import async
>>> @async
>>> def f1():
>>>    # some heavy-weight code

>>> @async(daemon=True, print_exception=False)
>>> def f2():
>>>     # some faulty daemon we don't really care about

>>> @async(print_exception=logging.WARNING)
>>> def f3():
>>>     # setting another logging level

>>> f1().wait()
<result>
>>> f2()  # started daemon
easync.Promise(...)
>>> f3().then(callback, error)  # notice, here the print_exception is suppressed (see Promise doc for more)
easync.Promise(...)

Promise

This is a threading wrapper that performs asynchronous call of the provided function. The behaviour is inspired by JavaScript Promises, but differs in several points.

First, the resolution is based upon the return of the function beneath. On successful return, the result is stored in Promise.result On exception, exception is stored in Promise.exception More about how Promise resolves in Resolving Promises.

You can add callbacks by using methods Promise.then or Promise.catch They will create a new Promise resolving in either the resolution of the previous one or the underlying callback.

If at the final stage no exception is processed or were generated new ones, they will be printed.

Basic usage:

>>> from easync import Promise
>>> promise = Promise(func)(...args)
>>> promise.wait()
<result>  # if any
>>> promise.result
<result>  # if any
>>> promise.exception
Exception  # if something went wrong
>>> promise.exc_info
Tuple (Exception.__class__, Exception, traceback)  # if any

Callbacks usage:

>>> def callback(result):
>>>     do_stuff(result)
>>> def error(exception, exc_info):
>>>     my_log(exception, exc_info=exc_info)
>>> def some_final(_):
>>>     cleanup()
>>> Promise(func)(...args).then(callback, error).then(some_final)
Promise(...)

Promise.Callable

The to-be-runned function.

Promise.result

This parameter holds the result the underlying function returned.

Promise.exception

This parameter holds the exception if the underlying function fails.

Promise.exc_info

This parameter holds the exception information tuple if the underlying function fails and the tuple was recovered. In case of Promise.reject, it will be None.

Promise.resolved

True if the function resolves. More about it in Resolving Promises.

Promise.started

threading.Event, sets when thread is started.

Promise.finished

threading.Event, sets when thread is finished, no matter where had it been resolved or not.

Promise.print_exception

Enables exception printout if caught. Uses logging to do so and has to be one of logging levels. False or None disable. Also automatically sets to False when a dependent Promise created through Promise.then or Promise.catch.

Resolving Promises

Functions

If the Promise is constructed with a function, it will resolve in it's return or reject with the caught exception.

Other Promises

Just resolves in the same way the other one is resolved. Printouts will be suppressed in the first one.

Events and Conditions

If Promise is based on threading.Event or threading.Condition, it is resolved when the underlying Event or Condition occurs. The type testing is duck-type for having the wait method, so anything using the interface of waiting can be resolved, for example other Promises, or threads.

The resolving is based on testing is_failed on the object, and if that one returns, the Promise rejects. Otherwise, the get_result is called to obtain the result. Both are duck-type thingeys.

Anything else

Resolves successfully with the result equals to the passed-in argument.

Promise.__init__

__init__(function[, daemon=False, print_exception=logging.ERROR])

The constructor creates a threading.Thread wrapping the function. To start it, call the resulting object as a function with it's arguments. (Explained in Promise.__call__)

>>> promise = Promise(func, print_exception=None)
>>> promise()

Promise.__call__

__call__(*args, **kwargs)

Starts the thread and passes the arguments of the function into it. Returns self, for simple adding Promise.then, Promise.wait or Promise.catch.

Promise.wait

wait([timeout=None])

Pauses the current thread to wait until the underlying promise resolves.

If timeout is set, raises easync.TimeoutError if it's reached.

Returns result of the underlying function if there's any.

Promise.then

then([resolved=None, rejected=None, print_exception=Promise.print_exception])

This method sets callbacks for a Promise.

NOTE this method suppresses the Promise default error handling by setting Promise.print_exception to False. You can then re-enable printouts manually, overriding the Promise.print_exception yourself.

NOTE calling this method twice on the same Promise object will result in duplicated exception printouts unless changed.

The result is a new Promise which resolves in:

This is done to have this kind of behaviour:

>>> Promise(action)(...args).then(parse_result).then(parse_one_more_result).catch(any_exception).then(cleanup)

Promise.catch

catch([callback=None, print_exception=Promise.print_exception])

The same as Promise.then (resolved=None, callback, print_exception).

Promise static methods

Promise.resolve

Promise.resolve(thing)

Resolves thing, regardless of what it is, to result.

Promise.reject

Promise.reject(thing)

Rejects thing, regardless of what it is.

NOTE, if this will be called, the Promise.exc_info will be set None.

Promise.all

Promise.all(things)

Resolves when all the items in the enumerate(things) are resolved. Or rejects when any of the items is rejected.

Promise.race

Promise.race(things)

Resolves when any of the items in the enumerate(things) is resolved. Or rejects when any of the items is rejected.

Other functions

get_result

get_result(obj)

Returns the first found attribute of result or success of the object obj, if any. Otherwise returns None.

is_failed

is_failed(obj)

Returns: