feat(#31): add thunk function

README.rst

@@ -72,6 +72,7 @@ API
 - paco.series_
 - paco.some_
 - paco.throttle_
+- paco.thunk_
 - paco.timeout_
 - paco.TimeoutLimit_
 - paco.times_
@@ -105,6 +106,7 @@ API
 .. _paco.series: http://paco.readthedocs.io/en/latest/api.html#paco.searies
 .. _paco.some: http://paco.readthedocs.io/en/latest/api.html#paco.some
 .. _paco.throttle: http://paco.readthedocs.io/en/latest/api.html#paco.throttle
+.. _paco.thunk: http://paco.readthedocs.io/en/latest/api.html#paco.thunk
 .. _paco.timeout: http://paco.readthedocs.io/en/latest/api.html#paco.timeout
 .. _paco.TimeoutLimit: http://paco.readthedocs.io/en/latest/api.html#paco.TimeoutLimit
 .. _paco.times: http://paco.readthedocs.io/en/latest/api.html#paco.times

docs/api.rst

@@ -27,6 +27,7 @@ API documentation
    paco.series <http://paco.readthedocs.io/en/latest/api.html#paco.searies>
    paco.some <http://paco.readthedocs.io/en/latest/api.html#paco.some>
    paco.throttle <http://paco.readthedocs.io/en/latest/api.html#paco.throttle>
+   paco.thunk <http://paco.readthedocs.io/en/latest/api.html#paco.thunk>
    paco.timeout <http://paco.readthedocs.io/en/latest/api.html#paco.timeout>
    paco.TimeoutLimit <http://paco.readthedocs.io/en/latest/api.html#paco.TimeoutLimit>
    paco.times <http://paco.readthedocs.io/en/latest/api.html#paco.times>

paco/thunk.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+import asyncio
+from .assertions import assert_corofunction
+
+
+def thunk(coro):
+    """
+    A thunk is a subroutine that is created, often automatically, to assist
+    a call to another subroutine.
+
+    Creates a thunk coroutine which returns coroutine function that accepts no
+    arguments and when invoked it schedules the wrapper coroutine and
+    returns the final result.
+
+    See Wikipedia page for more information about Thunk subroutines:
+    https://en.wikipedia.org/wiki/Thunk
+
+    Arguments:
+        value (coroutinefunction): wrapped coroutine function to invoke.
+
+    Returns:
+        coroutinefunction
+
+    Usage::
+
+        async def task():
+            return 'foo'
+
+        coro = paco.thunk(task)
+
+        await coro()
+        # => 'foo'
+        await coro()
+        # => 'foo'
+
+    """
+    assert_corofunction(coro=coro)
+
+    @asyncio.coroutine
+    def wrapper():
+        return (yield from coro())
+
+    return wrapper

tests/thunk_test.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+import pytest
+import asyncio
+from paco import thunk
+from .helpers import run_in_loop
+
+
+@asyncio.coroutine
+def task():
+    return 'foo'
+
+
+def test_thunk():
+    coro = thunk(task)
+    assert run_in_loop(coro()) == 'foo'
+    assert run_in_loop(coro()) == 'foo'
+    assert run_in_loop(coro()) == 'foo'
+
+
+def test_thunk_error():
+    with pytest.raises(TypeError):
+        run_in_loop(None)
+
+    with pytest.raises(TypeError):
+        run_in_loop(1)
+
+    with pytest.raises(TypeError):
+        run_in_loop('foo')