add a perform_delay_with_sleep performer, and do some minor doc tweaks

Author: radix

effect/__init__.py

@@ -15,18 +15,22 @@
     sync_perform,
     sync_performer)
 from ._intents import (
-    Delay, ParallelEffects, parallel, parallel_all_errors,
-    Constant, Error, FirstError, Func,
+    Delay, perform_delay_with_sleep,
+    ParallelEffects, parallel, parallel_all_errors, FirstError,
+    Constant, Error, Func,
     base_dispatcher)
 from ._dispatcher import ComposedDispatcher, TypeDispatcher
 
 
 __all__ = [
-    "Effect", "perform", "NoPerformerFoundError",
-    "NotSynchronousError", "sync_perform", "sync_performer",
-    "Delay", "ParallelEffects", "parallel", "parallel_all_errors",
-    "Constant", "Error", "FirstError", "Func",
+    # Order here affects the order that these things show up in the API docs.
+    "Effect", "sync_perform", "sync_performer",
     "base_dispatcher",
     "TypeDispatcher", "ComposedDispatcher",
+    "Delay", "perform_delay_with_sleep",
+    "ParallelEffects", "parallel", "parallel_all_errors",
+    "Constant", "Error", "Func",
     "catch", "raise_",
+    "NoPerformerFoundError", "NotSynchronousError", "perform",
+    "FirstError",
 ]

effect/_base.py

@@ -86,7 +86,9 @@ class NoPerformerFoundError(Exception):
 
 def perform(dispatcher, effect):
     """
-    Perform an effect and invoke callbacks bound to it.
+    Perform an effect and invoke callbacks bound to it. You probably don't want
+    to use this. Instead, use :func:`sync_perform` (or, if you're using
+    Twisted, see the `txeffect`_ library).
 
     The dispatcher will be called with the intent, and is expected to return a
     performer (another callable). See :obj:`TypeDispatcher` and
@@ -110,10 +112,6 @@ def perform(dispatcher, effect):
     callback. In the case of exceptions, the next error-callback will be called
     with a ``sys.exc_info()``-style tuple.
 
-    Note that this function does _not_ return the final result of the effect.
-    You may instead want to use :func:`.sync_perform` or
-    :func:`effect.twisted.perform`.
-
     :returns: None
 
     .. [#dispatcher] The dispatcher is passed because some performers need to

effect/_intents.py

@@ -5,18 +5,14 @@
 
 The :obj:`base_dispatcher` object in this module is a dispatcher which provides
 standard performers for intents which really only have one reasonable way to be
-performed, sunch as :class:`Func`, :class:`Error`, and
-:class:`Constant`.
-
-Other intents, such as :class:`ParallelEffects` and :class:`Delay`, need to
-have a performer specified elsewhere, since the performers are reliant on
-choices made by the application author. :module:`effect.twisted` provides a
-Twisted-specific dispatcher for these.
+performed, sunch as :class:`Func`, :class:`Error`, and :class:`Constant`.
 """
 
 
 from __future__ import print_function, absolute_import
 
+import time
+
 import attr
 
 from ._base import Effect
@@ -118,6 +114,12 @@ class Delay(object):
     delay = attr.ib()
 
 
+@sync_performer
+def perform_delay_with_sleep(dispatcher, intent):
+    """Perform a :obj:`Delay` by calling ``time.sleep``."""
+    time.sleep(intent.delay)
+
+
 @attr.s
 class Constant(object):
     """

effect/test_intents.py

@@ -14,6 +14,7 @@
 from ._intents import (
     base_dispatcher,
     Constant, perform_constant,
+    Delay, perform_delay_with_sleep,
     Error, perform_error,
     Func, perform_func,
     FirstError,
@@ -32,12 +33,14 @@ def test_perform_constant():
         Effect(intent))
     assert result == "foo"
 
+
 def test_perform_error():
     """perform_error raises the exception of an Error."""
     intent = Error(ValueError("foo"))
     with raises(ValueError):
         sync_perform(TypeDispatcher({Error: perform_error}), Effect(intent))
 
+
 def test_perform_func():
     """perform_func calls the function given in a Func."""
     intent = Func(lambda: "foo")
@@ -53,13 +56,23 @@ def test_perform_func_args_kwargs():
     result = sync_perform(TypeDispatcher({Func: perform_func}), Effect(intent))
     assert result == ((1, 2), {'key': 3})
 
+
 def test_first_error_str():
     """FirstErrors have a pleasing format."""
     fe = FirstError(exc_info=(ValueError, ValueError('foo'), None),
                     index=150)
     assert str(fe) == '(index=150) ValueError: foo'
 
 
+def test_perform_delay_with_sleep(monkeypatch):
+    """:func:`perform_delay_with_sleep` calls time.sleep."""
+    calls = []
+    monkeypatch.setattr('time.sleep', calls.append)
+    disp = TypeDispatcher({Delay: perform_delay_with_sleep})
+    sync_perform(disp, Effect(Delay(3.7)))
+    assert calls == [3.7]
+
+
 class ParallelAllErrorsTests(TestCase):
     """Tests for :func:`parallel_all_errors`."""