Merge branch 'master' into sequence

Author: radix

Makefile

@@ -1,5 +1,5 @@
 lint:
-	flake8 --ignore=E131,E731,W503 effect/ examples/
+	flake8 --ignore=E131,E731,W503 effect/
 
 build-dist:
 	rm -rf dist

README.rst

@@ -1,8 +1,8 @@
 Effect
 ======
 
-.. image:: https://travis-ci.org/radix/effect.svg?branch=master
-    :target: https://travis-ci.org/radix/effect
+.. image:: https://travis-ci.org/python-effect/effect.svg?branch=master
+    :target: https://travis-ci.org/python-effect/effect
 
 Effect is a library for helping you write purely functional code by
 isolating the effects (that is, IO or state manipulation) in your code.
@@ -89,10 +89,10 @@ possible to override the way an intent is performed to do whatever you want.
 For more information on how to implement the actual effect-performing code,
 and other details, see the `documentation`_. There is also a full example
 of interacting with the user and using an HTTP client to talk to the GitHub
-API in the `examples`_ directory.
+API in the `effect-examples`_ repository.
 
 .. _`documentation`: https://effect.readthedocs.org/
-.. _`examples`: https://github.com/radix/effect/tree/master/examples
+.. _`effect-examples`: https://github.com/python-effect/effect-examples
 
 
 
@@ -133,6 +133,12 @@ There is a ``#python-effect`` IRC channel on irc.freenode.net.
 See Also
 ========
 
+For integrating Effect with Twisted's Deferreds, see the ``txEffect`` package
+(`pypi`_, `github`_).
+
+.. _`pypi`: https://warehouse.python.org/project/txeffect
+.. _`github`: https://github.com/python-effect/txeffect
+
 Over the past few years, the ecosystem of libraries to help with functional
 programming in Python has exploded. Here are some libraries I recommend:
 

dev-requirements.txt

@@ -1,4 +1,3 @@
 testtools
-twisted
 flake8
 pytest

docs/source/conf.py

@@ -60,9 +60,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.1a18'
+version = '0.1a19'
 # The full version, including alpha/beta/rc tags.
-release = '0.1a18'
+release = '0.1a19'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

effect/fold.py

@@ -25,13 +25,24 @@ def __str__(self):
 
 def fold_effect(f, initial, effects):
     """
-    Fold over effects.
+    Fold over the results of effects, left-to-right.
 
-    The function will be called with the accumulator (starting with
+    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``.

effect/test_fold.py

@@ -10,12 +10,16 @@
 from effect.testing import SequenceDispatcher
 
 
-def _disp(dispatcher):
+def _base_and(dispatcher):
+    """Compose base_dispatcher onto the given dispatcher."""
     return ComposedDispatcher([dispatcher, base_dispatcher])
 
 
 def test_fold_effect():
-    """Behaves like foldM."""
+    """
+    :func:`fold_effect` folds the given function over the results of the
+    effects.
+    """
     effs = [Effect('a'), Effect('b'), Effect('c')]
 
     dispatcher = SequenceDispatcher([
@@ -26,7 +30,7 @@ def test_fold_effect():
     eff = fold_effect(operator.add, 'Nil', effs)
 
     with dispatcher.consume():
-        result = sync_perform(_disp(dispatcher), eff)
+        result = sync_perform(_base_and(dispatcher), eff)
     assert result == 'NilEiBeeCee'
 
 
@@ -54,7 +58,7 @@ def test_fold_effect_errors():
 
     with dispatcher.consume():
         with raises(FoldError) as excinfo:
-            sync_perform(_disp(dispatcher), eff)
+            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'