transpub/deferred.py

# use unicode encoding for all literals by default (for python2.x)
from __future__ import unicode_literals
from functools import partial

class Deferred(object):
	"""
	Represents a delayed computation. This is a more elegant way to deal with
	callbacks.

	A Deferred object can be thought of as a computation whose value is yet to
	be determined. We can manipulate the Deferred as if it where a regular
	value by using the then method. Computations dependent on the Deferred will
	only proceed when the run method is called.

	Attributes of a Deferred can be accessed directly as methods. The result of
	calling these functions will be Deferred.

	Example:
		image = Deferred()
		getImageWithCallback(image.run)
		image.then(displayFunc)

		colors = Deferred()
		colors.append('blue')
		colors.then(print)
		colors.run(['red', 'green']) #=> ['red', 'green', 'blue']
	"""

	def __init__(self):
		self.subscribers = []
		self.computed = False
		self.args = None
		self.kwargs = None

	def run(self, *args, **kwargs):
		"""
		Give a value to the deferred. Calling this method more than once will
		result in a DeferredHasValue exception to be raised.
		"""
		if self.computed:
			raise DeferredHasValue("Deferred object already has a value.")
		else:
			self.args = args
			self.kwargs = kwargs
			for func, deferred in self.subscribers:
				deferred.run(func(*args, **kwargs))
			self.computed = True

	def then(self, func):
		"""
		Apply func to Deferred value. Returns a Deferred whose value will be
		the result of applying func.
		"""
		result = Deferred()
		if self.computed:
			result.run(func(*self.args, **self.kwargs))
		else:
			self.subscribers.append((func, result))
		return result

	def arg(self, n):
		"""
		Returns the nth positional argument of a deferred as a deferred

		Args:
			n - the index of the positional argument
		"""
		def helper(*args, **kwargs):
			return args[n]
		return self.then(helper)

	def when(self, func, *args, **kwargs):
		""" Calls when func(*args, **kwargs) when deferred gets a value """
		def helper(*args2, **kwargs2):
			func(*args, **kwargs)
		return self.then(helper)

	def __getattr__(self, method_name):
		return getattr(Then(self), method_name)


class Then(object):
	"""
	Allows you to call methods on a Deferred.

	Example:
	colors = Deferred()
	Then(colors).append('blue')
	colors.run(['red', 'green'])
	colors.then(print) #=> ['red', 'green', 'blue']
	"""
	def __init__(self, deferred):
		self.deferred = deferred

	def __getattr__(self, name):
		def tryCall(obj, *args, **kwargs):
			if callable(obj):
				return obj(*args, **kwargs)
			else:
				return obj
		def helper(*args, **kwargs):
			func = (lambda x: tryCall(getattr(x, name), *args, **kwargs))
			return self.deferred.then(func)
		return helper

def call(func, *args, **kwargs):
	"""
	Call a function with deferred arguments

	Example:
		colors = Deferred()
		colors.append('blue')
		colors.run(['red', 'green'])
		call(print, colors) #=> ['red', 'green', 'blue']
		call(print, 'hi', colors) #=> hi ['red', 'green', 'blue']
	"""
	for i, c in enumerate(args):
		if isinstance(c, Deferred):
			# Function without deferred arguments
			normalfunc = partial(func, *args[:i])
			# Function with deferred and possibly deferred arguments
			def restfunc(*arg2, **kwarg2):
				apply_deferred = partial(normalfunc, *arg2, **kwarg2)
				return call(apply_deferred, *args[i + 1:], **kwargs)
			return c.then(restfunc)
	items = kwargs.items()
	for i, (k, v) in enumerate(items):
		if isinstance(v, Deferred):
			# Function without deferred arguments
			normalfunc = partial(func, *args, **dict(items[:i]))
			# Function with deferred and possibly deferred arguments
			def restfunc2(*arg2, **kwarg2):
				apply_deferred = partial(normalfunc, *arg2, **kwarg2)
				return call(apply_deferred, **dict(items[i + 1:]))
			return v.then(restfunc2)
	# No items deferred
	return func(*args, **kwargs)

class DeferredHasValue(Exception):
	def __init__(self, string):
		super(DeferredHasValue, self).__init__(string)