Module promises

Promises for Python

Yet another module for doing promises in python! This time with transparent proxies, and other convoluted stuff that will make you wish someone smarter had worked on this.

author:Christopher O’Brien <obriencj@gmail.com> license:LGPL v.3

General

promises.deliver(on_promise)

Attempts to deliver on a promise, and returns the resulting value. If the delivery of work causes an exception, it will be raised here.

Parameters:

on_promise : Proxy or Container promise

the promise to deliver on

Returns:

value :

the promised work if it could be successfully computed

promises.is_delivered(a_promise)

True if a_promise is a promise and has been delivered

promises.is_promise(obj)

True if obj is a promise (either a proxy or a container)

promises.promise_repr(of_promise)

Representation of a promise. If the promise is undelivered, will not deliver on it. If it is delivered, will deliver to check if the delivery indicates that the promise was broken.

Parameters:

of_promise : Proxy or Container

the promise to represent

Returns:

value : str

text representation of the promise

promises.breakable_deliver(on_promise)

Attempts to deliver on a promise. If delivery raises an Exception, it is caught and the sys.exc_info() is stored into a BrokenPromise instance which is returned in lieu of a normal result.

This can be called on any Proxy or Container, not just those that were created as breakable via the breakable_lazy and breakable_proxy functions.

Using this function to deliver on a promise will not change the behavior of whether it is considered delivered or not when an Exception is raised.

Only subclasses of Exception are caught – BaseException instances are considered too important to be caught this way.

Parameters:

on_promise : Proxy or Container promise

the promise to deliver on

Returns:

value :

the promised work if it could be successfully computed, or a BrokenPromise instance wrapping any Exception that may have been raised while attempting delivery

class promises.BrokenPromise(reason=None)

Bases: object

Result indicating a promise was broken. See the breakable_lazy, breakable_proxy, and breakable_deliver functions for more information.

class promises.PromiseAlreadyDelivered

Bases: exceptions.Exception

Raised when a paired promise’s delivery function is called more than once.

class promises.PromiseNotReady

Bases: exceptions.Exception

Raised when attempting to deliver on a promise whose underlying delivery function hasn’t been called.

Container Promises

promises.lazy(work, *args, **kwds)

Creates a new container promise to find an answer for work.

Parameters:

work : callable

executed when the promise is delivered

*args :

optional arguments to pass to work

**kwds :

optional keyword arguments to pass to work

Returns:

promise : Container

the container promise which will deliver on work(*args, **kwds)

promises.breakable(work, *args, **kwds)

Creates a Container promise to perform work. If delivery of the work raises an Exception, a BrokenPromise instance is created to wrap the sys.exc_info() and is returned in lieu of a result.

Unlike a promise created by lazy_proxy, raising an Exception in the work will result in the promise being considered delivered, but broken. Further attempts at delivery will not re-execute the work, but will return the BrokenPromise instance from the first failure.

promises.promise(blocking=False)

Returns a tuple of a new Container, a unary function to deliver a value into that promise, and a ternary function to feed an exception to the promise.

If blocking is True, then any attempt to deliver on the promise will block until/unless a value or exception has been set via the setter or seterr functions.

Returns:

promise : Container

promise acting as a placeholder for future data

setter : function(value)

function which delivers a value to fulfill the promise

seterr : function(exc_type, exc_inst, exc_tb)

function which delivers exc_info to raise on delivery of the promise

Examples

>>> prom, setter, seterr = promise()
>>> setter(5)
>>> deliver(prom)
5

Proxy Promises

promises.lazy_proxy(work, *args, **kwds)

Creates a new proxy promise to find an answer for work.

Parameters:

work : callable

executed when the promise is delivered

*args :

optional arguments to pass to work

**kwds :

optional keyword arguments to pass to work

Returns:

promise : Proxy

the proxy promise which will deliver on work(*args, **kwds)

promises.breakable_proxy(work, *args, **kwds)

Creates a Proxy promise to perform work. If delivery of the work raises an Exception, a BrokenPromise instance is created to wrap the sys.exc_info() and is returned in lieu of a result.

Unlike a promise created by lazy, raising an Exception in the work will result in the promise being considered delivered, but broken. Further attempts at delivery will not re-execute the work, but will return the BrokenPromise instance from the first failure.

promises.promise_proxy(blocking=False)

Returns a tuple of a new Proxy, a unary function to deliver a value into that promise, and a ternary function to feed an exception to the promise.

If blocking is True, then any attempt to deliver on the promise (including accessing its members) will block until/unless a value or exception has been set via the setter or seterr functions.

Returns:

promise : Proxy

promise acting as a placeholder for future data

setter : function(value)

function which delivers a value to fulfill the promise

seterr : function(exc_type, exc_inst, exc_tb)

function which delivers exc_info to raise on delivery of the promise

Examples

>>> prom, setter, seterr = promise_proxy()
>>> setter(5)
>>> prom
5