add nested_sequence function

and some doc changes

Author: manishtomar

effect/test_testing.py

@@ -21,6 +21,7 @@
 from .do import do, do_return
 from .fold import FoldError, sequence
 from .testing import (
+    _ANY,
     ESConstant,
     ESError,
     ESFunc,
@@ -31,6 +32,7 @@
     conste,
     fail_effect,
     intent_func,
+    nested_sequence,
     parallel_sequence,
     perform_sequence,
     resolve_effect,
@@ -467,6 +469,37 @@ def test_parallel_sequence_must_be_parallel():
     assert excinfo.value.wrapped_exception[0] is AssertionError
 
 
+def test_nested_sequence():
+    """
+    :func:`nested_sequence` returns sequence performer function for an intent
+    that wraps an effect.
+    """
+
+    @attr.s
+    class WrappedIntent(object):
+        effect = attr.ib()
+        value = attr.ib()
+
+    @do
+    def internal():
+        yield Effect(1)
+        yield Effect(2)
+        yield do_return("wrap")
+
+    @do
+    def code_under_test():
+        r = yield Effect(WrappedIntent(internal(), "field"))
+        r2 = yield Effect(MyIntent("a"))
+        yield do_return((r, r2))
+
+    seq = [
+        (WrappedIntent(_ANY, "field"), nested_sequence([(1, const("r1")), (2, const("r2"))])),
+        (MyIntent("a"), const("result2"))
+    ]
+    eff = code_under_test()
+    assert perform_sequence(seq, eff) == ('wrap', 'result2')
+
+
 def test_const():
     """
     :func:`const` takes an argument but returns fixed value

effect/testing.py

@@ -8,6 +8,7 @@
 
 from contextlib import contextmanager
 from functools import partial
+from operator import attrgetter
 import sys
 
 import attr
@@ -20,8 +21,13 @@
 
 __all__ = [
     'perform_sequence',
+    'parallel_sequence',
+    'nested_sequence',
     'SequenceDispatcher',
     'noop',
+    'const',
+    'conste',
+    'intent_func',
     'resolve_effect',
     'fail_effect',
     'EQDispatcher',
@@ -30,9 +36,6 @@
     'ESConstant', 'ESError', 'ESFunc',
     'resolve_stubs',
     'resolve_stub',
-    'const',
-    'conste',
-    'intent_func',
 ]
 
 
@@ -86,6 +89,7 @@ def test_code():
     :param fallback_dispatcher: A dispatcher to use for intents that aren't
         found in the sequence. if None is provided, ``base_dispatcher`` is
         used.
+    :return: Result of performed sequence
     """
     def fmt_log():
         next_item = ''
@@ -162,6 +166,8 @@ def test_code():
         what :func:`perform_sequence` accepts.
     :param fallback_dispatcher: an optional dispatcher to compose onto the
         sequence dispatcher.
+    :return: (intent, performer) tuple as expected by :func:`perform_sequence`
+        where intent is ParallelEffects object
     """
     perf = partial(perform_sequence, fallback_dispatcher=fallback_dispatcher)
 
@@ -467,6 +473,43 @@ def consume(self):
                     [x[0] for x in self.sequence]))
 
 
+def nested_sequence(seq, get_effect=attrgetter('effect'),
+                    fallback_dispatcher=base_dispatcher):
+    """
+    Return a function of Intent -> a that performs an effect retrieved from the
+    intent (by accessing its `effect` attribute, by default) with the given
+    intent-sequence.
+
+    A demonstration is best::
+
+        SequenceDispatcher([
+            (BoundFields(effect=mock.ANY, fields={...}),
+             nested_sequence([(SomeIntent(), perform_some_intent)]))
+        ])
+
+    The point is that sometimes you have an intent that wraps another effect,
+    and you want to ensure that the nested effects follow some sequence in the
+    context of that wrapper intent.
+
+    ``get_effect`` defaults to ``attrgetter('effect')``, so you can override it if
+    your intent stores its nested effect in a different attribute. Or, more
+    interestingly, if it's something other than a single effect, e.g. for
+    ParallelEffects see the :func:`parallel_sequence` function.
+
+    :param list seq: sequence of intents like :obj:`SequenceDispatcher` takes
+    :param get_effect: callable to get the inner effect from the wrapper
+        intent.
+    :param fallback_dispatcher: an optional dispatcher to compose onto the
+        sequence dispatcher.
+    :return: ``callable`` that can be used as performer of a wrapped intent
+    """
+    def performer(intent):
+        effect = get_effect(intent)
+        return perform_sequence(seq, effect, fallback_dispatcher=fallback_dispatcher)
+
+    return performer
+
+
 def noop(intent):
     """
     Return None. This is just a handy way to make your intent sequences (as