Merge pull request #51 from python-effect/foldE

add a `fold_effect` function

Author: radix

docs/source/api/effect.fold.rst

@@ -0,0 +1,7 @@
+effect.fold module
+==================
+
+.. automodule:: effect.fold
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/api/effect.rst

@@ -8,6 +8,7 @@ Submodules
 
    effect.async
    effect.do
+   effect.fold
    effect.ref
    effect.retry
    effect.testing

effect/fold.py

@@ -0,0 +1,59 @@
+import traceback
+from functools import reduce
+
+from effect import Constant, Effect
+
+
+class FoldError(Exception):
+    """
+    Raised when one of the Effects passed to :func:`fold_effect` fails.
+
+    :ivar accumulator: The data accumulated so far, before the failing Effect.
+    :ivar wrapped_exception: The exc_info tuple representing the original
+        exception raised by the failing Effect.
+    """
+    def __init__(self, accumulator, wrapped_exception):
+        self.accumulator = accumulator
+        self.wrapped_exception = wrapped_exception
+
+    def __str__(self):
+        tb_lines = traceback.format_tb(self.wrapped_exception[2])
+        tb = ''.join(tb_lines)
+        return "FoldError(%r, %r) -> ORIGINAL TRACEBACK FOLLOWS\n%s" % (
+            self.accumulator, self.wrapped_exception, tb)
+
+
+def fold_effect(f, initial, effects):
+    """
+    Fold over the results of effects, left-to-right.
+
+    This is like :func:`functools.reduce`, but instead of acting on plain
+    values, it acts on the results of effects.
+
+    The function ``f`` will be called with the accumulator (starting with
+    ``initial``) and a result of an effect repeatedly for each effect. The
+    result of the previous call will be passed as the accumulator to the next
+    call.
+
+    For example, the following code evaluates to an Effect of 6::
+
+        fold_effect(operator.add, 0, [Effect(Constant(1)),
+                                      Effect(Constant(2)),
+                                      Effect(Constant(3))])
+
+    If no elements were in the list, Effect would result in 0.
+
+    :param callable f: function of ``(accumulator, element) -> accumulator``
+    :param initial: The value to be passed as the accumulator to the first
+        invocation of ``f``.
+    :param effects: sequence of Effects.
+    """
+
+    def failed(acc, e):
+        raise FoldError(acc, e)
+
+    def folder(acc, element):
+        return acc.on(lambda r: element.on(lambda r2: f(r, r2),
+                                           error=lambda e: failed(r, e)))
+
+    return reduce(folder, effects, Effect(Constant(initial)))

effect/test_fold.py

@@ -0,0 +1,64 @@
+
+import operator
+
+from pytest import raises
+
+from effect import (
+    ComposedDispatcher, Effect, Error,
+    base_dispatcher, sync_perform)
+from effect.fold import FoldError, fold_effect
+from effect.testing import SequenceDispatcher
+
+
+def _base_and(dispatcher):
+    """Compose base_dispatcher onto the given dispatcher."""
+    return ComposedDispatcher([dispatcher, base_dispatcher])
+
+
+def test_fold_effect():
+    """
+    :func:`fold_effect` folds the given function over the results of the
+    effects.
+    """
+    effs = [Effect('a'), Effect('b'), Effect('c')]
+
+    dispatcher = SequenceDispatcher([
+        ('a', lambda i: 'Ei'),
+        ('b', lambda i: 'Bee'),
+        ('c', lambda i: 'Cee'),
+    ])
+    eff = fold_effect(operator.add, 'Nil', effs)
+
+    with dispatcher.consume():
+        result = sync_perform(_base_and(dispatcher), eff)
+    assert result == 'NilEiBeeCee'
+
+
+def test_fold_effect_empty():
+    """
+    Returns an Effect resulting in the initial value when there are no effects.
+    """
+    eff = fold_effect(operator.add, 0, [])
+    result = sync_perform(base_dispatcher, eff)
+    assert result == 0
+
+
+def test_fold_effect_errors():
+    """
+    When one of the effects in the folding list fails, a FoldError is raised
+    with the accumulator so far.
+    """
+    effs = [Effect('a'), Effect(Error(ZeroDivisionError('foo'))), Effect('c')]
+
+    dispatcher = SequenceDispatcher([
+        ('a', lambda i: 'Ei'),
+    ])
+
+    eff = fold_effect(operator.add, 'Nil', effs)
+
+    with dispatcher.consume():
+        with raises(FoldError) as excinfo:
+            sync_perform(_base_and(dispatcher), eff)
+    assert excinfo.value.accumulator == 'NilEi'
+    assert excinfo.value.wrapped_exception[0] is ZeroDivisionError
+    assert str(excinfo.value.wrapped_exception[1]) == 'foo'