Introduce flat_bind

Fixes #97

README.md

@@ -68,6 +68,11 @@ def fetch_urls(urls):
 
 ## Changelog
 
+### v1.16.0
+
+- Introduced flat_bind
+  ([#97](https://github.com/rohanpm/more-executors/issues/97))
+
 ### v1.15.0
 
 - Fixed possible deadlock in CancelOnShutdownExecutor

docs/api-reference.rst

@@ -7,6 +7,8 @@ bind
 
 .. automethod:: more_executors.Executors.bind
 
+.. automethod:: more_executors.Executors.flat_bind
+
 
 concurrent.futures
 ..................

docs/user-guide.rst

@@ -132,6 +132,10 @@ In contrast, without using :meth:`bind`, the *first* step of the pipeline -
 :meth:`requests.get` - appears at the *end* of the code, which is harder
 to follow.
 
+:meth:`~more_executors.Executors.flat_bind` is also provided for use with
+callables returning a future. It behaves in the same way as :meth:`bind`,
+but avoids returning a nested future.
+
 
 Usage of threads
 ----------------

more_executors/_executors.py

@@ -26,7 +26,9 @@ class Executors(object):
 
     @classmethod
     def bind(cls, executor, fn):
-        """Bind a callable to an executor.
+        """Bind a synchronous callable to an executor.
+
+        If the callable returns a future, consider using :meth:`flat_bind` instead.
 
         Arguments:
             executor (~concurrent.futures.Executor): an executor
@@ -44,6 +46,32 @@ def bind(cls, executor, fn):
         """
         return BoundCallable(executor, fn)
 
+    @classmethod
+    def flat_bind(cls, executor, fn):
+        """Bind an asynchronous callable to an executor.
+
+        This convenience method should be used in preference to :meth:`bind`
+        when the bound callable returns a future, in order to avoid a nested
+        future in the returned value. It is equivalent to:
+
+        >>> bind(fn).with_flat_map(lambda future: future)
+
+        Arguments:
+            executor (~concurrent.futures.Executor): an executor
+            fn (callable): any function or callable which returns a future
+
+        Returns:
+            callable:
+                A new callable which, when invoked, will submit `fn` to `executor` and return
+                the resulting (flattened) future.
+
+                This returned callable provides the `Executors.with_*` methods, which may be
+                chained to further customize the behavior of the callable.
+
+        .. versionadded:: 1.16.0
+        """
+        return cls.bind(executor, fn).with_flat_map(lambda f: f)
+
     @classmethod
     def thread_pool(cls, *args, **kwargs):
         """Create a thread pool executor.

more_executors/_wrap.py

@@ -3,6 +3,10 @@ def bind(self, *args, **kwargs):
         from more_executors._executors import Executors
         return Executors.bind(self, *args, **kwargs)
 
+    def flat_bind(self, *args, **kwargs):
+        from more_executors._executors import Executors
+        return Executors.flat_bind(self, *args, **kwargs)
+
 
 class CanCustomize(object):
     def with_retry(self, *args, **kwargs):

tests/test_bind.py

@@ -14,6 +14,10 @@ def mult(x, y):
     return x*y
 
 
+def async_mult(x, y):
+    return Executors.sync().submit(mult, x, y)
+
+
 def test_single_bind():
     async_mult2 = Executors. \
         thread_pool(). \
@@ -52,6 +56,17 @@ def test_bind_then_map():
     assert results == [0, 200, 400]
 
 
+def test_flat_bind():
+    bound_async_mult = Executors.thread_pool().flat_bind(async_mult)
+
+    inputs = [(0, 1), (2, 3), (4, 5)]
+    expected_results = [0, 6, 20]
+    futures = [bound_async_mult(x, y) for (x, y) in inputs]
+    results = [f.result() for f in futures]
+
+    assert results == expected_results
+
+
 def test_no_rebind():
     bound = Executors.sync().bind(mult10)