asynkit 0.9.1__tar.gz → 0.9.2__tar.gz

{asynkit-0.9.1 → asynkit-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: asynkit
-Version: 0.9.1
+Version: 0.9.2
 Summary: Async toolkit for advanced scheduling
 Home-page: https://github.com/kristjanvalur/py-asynkit
 License: MIT
@@ -141,7 +141,7 @@ of an event loop.  As long as the code doesn't _block_ (await unfinished _future
 
 ```python
 async def async_get_processed_data(datagetter):
-    data = datagetter()  # could be an async callback
+    data = datagetter()  # an optionally async callback
     data = await data if isawaitable(data) else data
     return process_data(data)
 
@@ -154,11 +154,11 @@ def sync_get_processed_data(datagetter):
 This sort of code might previously have been written thus:
 
 ```python
-# may return an awaitable
-def get_processed_data(datagetter):
+# A hybrid function, _may_ return an _awaitable_
+def hybrid_get_processed_data(datagetter):
     data = datagetter()
     if isawaitable(data):
-        # return an awaitable helper function
+        # return an awaitable helper closure
         async def helper():
             data = await data
             return process_data(data)
@@ -168,12 +168,12 @@ def get_processed_data(datagetter):
 
 
 async def async_get_processed_data(datagetter):
-    r = get_processed_data(datagetter)
+    r = hybrid_get_processed_data(datagetter)
     return await r if isawaitable(r) else r
 
 
 def sync_get_processed_data(datagetter):
-    r = get_processed_data(datagetter)
+    r = hybrid_get_processed_data(datagetter)
     if isawaitable(r):
         raise RuntimeError("callbacks failed to run synchronously")
     return r
@@ -182,7 +182,7 @@ def sync_get_processed_data(datagetter):
 The above pattern, writing async methods as sync and returning async helpers,
 is common in library code which needs to work both in synchronous and asynchronous
 context.  Needless to say, it is very convoluted, hard to debug and contains a lot
-of code duplication where the same logic is repeated inside async helper methods.
+of code duplication where the same logic is repeated inside async helper closures.
 
 Using `coro_sync()` it is possible to write the entire logic as `async` methods and
 then simply fail if the code tries to invoke any truly async operations.
@@ -190,11 +190,11 @@ If the invoked coroutine blocks, a `SynchronousError` is raised _from_ a `Synchr
 contains a traceback.  This makes it easy to pinpoint the location in the code where the
 async code blocked.  If the code tries to access the event loop, e.g. by creating a `Task`, a `RuntimeError` will be raised.  
 
-
-`coro_sync()` can also be applied as a decorator:
+The `syncfunction()` decorator can be used to automatically wrap an async function
+so that it is executed using `coro_sync()`:
 
 ```pycon
->>> @asynkit.coro_sync
+>>> @asynkit.syncfunction
 ... async def sync_function():
 ...     async def async_function():
 ...         return "look, no async!"
@@ -205,34 +205,19 @@ async code blocked.  If the code tries to access the event loop, e.g. by creatin
 >>>
 ```
 
-the `ensure_corofunc()` utility can be used when passing callbacks to async
-code, to ensure that the callbacks are async.  This, with `coro_sync()`, can help integrate
-synchronous code with async middleware:
+the `asyncfunction()` utility can be used when passing synchronous callbacks to async
+code, to make them async.  This, along with `syncfunction()` and `coro_sync()`,
+can be used to integrate synchronous code with async middleware:
 
 ```python
-def sync_client(sync_callback):
-    middleware = AsyncMiddleware(asynkit.ensure_corofunc(sync_callback))
-    return asynkit.coro_sync(middleware.run())
+@asynkit.syncfunction
+async def sync_client(sync_callback):
+    middleware = AsyncMiddleware(asynkit.asyncfunction(sync_callback))
+    return await middleware.run()
 ```
 
-Using this pattern, one can avoid writing special synchronous versions of middleware, or having
-_hybrid_ methods which _optionally_ return awaitables:
-
-```python
-# the hybrid method antipattern
-def hybrid_method(callable):
-    """A hybrid method, possibly returning awaitable"""
-    data = callable()
-    if isawaitable(data):
-        # inner async method with duplicate code
-        async def async_helper(data):
-            data2 = await data
-            return process_data(data2)
-
-        return async_helper
-    else:
-        return process_data(data)  # duplicate code
-```
+Using this pattern, one can write the middleware completely async, make it also work
+for synchronous code, while avoiding the hybrid function _antipattern._
 
 ## `CoroStart`
 

{asynkit-0.9.1 → asynkit-0.9.2}/README.md

@@ -117,7 +117,7 @@ of an event loop.  As long as the code doesn't _block_ (await unfinished _future
 
 ```python
 async def async_get_processed_data(datagetter):
-    data = datagetter()  # could be an async callback
+    data = datagetter()  # an optionally async callback
     data = await data if isawaitable(data) else data
     return process_data(data)
 
@@ -130,11 +130,11 @@ def sync_get_processed_data(datagetter):
 This sort of code might previously have been written thus:
 
 ```python
-# may return an awaitable
-def get_processed_data(datagetter):
+# A hybrid function, _may_ return an _awaitable_
+def hybrid_get_processed_data(datagetter):
     data = datagetter()
     if isawaitable(data):
-        # return an awaitable helper function
+        # return an awaitable helper closure
         async def helper():
             data = await data
             return process_data(data)
@@ -144,12 +144,12 @@ def get_processed_data(datagetter):
 
 
 async def async_get_processed_data(datagetter):
-    r = get_processed_data(datagetter)
+    r = hybrid_get_processed_data(datagetter)
     return await r if isawaitable(r) else r
 
 
 def sync_get_processed_data(datagetter):
-    r = get_processed_data(datagetter)
+    r = hybrid_get_processed_data(datagetter)
     if isawaitable(r):
         raise RuntimeError("callbacks failed to run synchronously")
     return r
@@ -158,7 +158,7 @@ def sync_get_processed_data(datagetter):
 The above pattern, writing async methods as sync and returning async helpers,
 is common in library code which needs to work both in synchronous and asynchronous
 context.  Needless to say, it is very convoluted, hard to debug and contains a lot
-of code duplication where the same logic is repeated inside async helper methods.
+of code duplication where the same logic is repeated inside async helper closures.
 
 Using `coro_sync()` it is possible to write the entire logic as `async` methods and
 then simply fail if the code tries to invoke any truly async operations.
@@ -166,11 +166,11 @@ If the invoked coroutine blocks, a `SynchronousError` is raised _from_ a `Synchr
 contains a traceback.  This makes it easy to pinpoint the location in the code where the
 async code blocked.  If the code tries to access the event loop, e.g. by creating a `Task`, a `RuntimeError` will be raised.  
 
-
-`coro_sync()` can also be applied as a decorator:
+The `syncfunction()` decorator can be used to automatically wrap an async function
+so that it is executed using `coro_sync()`:
 
 ```pycon
->>> @asynkit.coro_sync
+>>> @asynkit.syncfunction
 ... async def sync_function():
 ...     async def async_function():
 ...         return "look, no async!"
@@ -181,34 +181,19 @@ async code blocked.  If the code tries to access the event loop, e.g. by creatin
 >>>
 ```
 
-the `ensure_corofunc()` utility can be used when passing callbacks to async
-code, to ensure that the callbacks are async.  This, with `coro_sync()`, can help integrate
-synchronous code with async middleware:
+the `asyncfunction()` utility can be used when passing synchronous callbacks to async
+code, to make them async.  This, along with `syncfunction()` and `coro_sync()`,
+can be used to integrate synchronous code with async middleware:
 
 ```python
-def sync_client(sync_callback):
-    middleware = AsyncMiddleware(asynkit.ensure_corofunc(sync_callback))
-    return asynkit.coro_sync(middleware.run())
+@asynkit.syncfunction
+async def sync_client(sync_callback):
+    middleware = AsyncMiddleware(asynkit.asyncfunction(sync_callback))
+    return await middleware.run()
 ```
 
-Using this pattern, one can avoid writing special synchronous versions of middleware, or having
-_hybrid_ methods which _optionally_ return awaitables:
-
-```python
-# the hybrid method antipattern
-def hybrid_method(callable):
-    """A hybrid method, possibly returning awaitable"""
-    data = callable()
-    if isawaitable(data):
-        # inner async method with duplicate code
-        async def async_helper(data):
-            data2 = await data
-            return process_data(data2)
-
-        return async_helper
-    else:
-        return process_data(data)  # duplicate code
-```
+Using this pattern, one can write the middleware completely async, make it also work
+for synchronous code, while avoiding the hybrid function _antipattern._
 
 ## `CoroStart`
 

{asynkit-0.9.1 → asynkit-0.9.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "asynkit"
-version = "0.9.1"
+version = "0.9.2"
 description = "Async toolkit for advanced scheduling"
 authors = ["Kristján Valur Jónsson <sweskman@gmail.com>"]
 repository = "https://github.com/kristjanvalur/py-asynkit"
@@ -75,6 +75,7 @@ module = [
     "asynkit.loop.eventloop",
     "asynkit.compat",
     "asynkit.tools",
+    "tests.test_coro",
 ]
 warn_unused_ignores=false
 

{asynkit-0.9.1 → asynkit-0.9.2}/src/asynkit/coroutine.py

@@ -4,7 +4,6 @@ import inspect
 import sys
 import types
 from contextvars import Context, copy_context
-from inspect import iscoroutinefunction
 from types import FrameType
 from typing import (
     Any,
@@ -34,7 +33,6 @@ __all__ = [
     "coro_eager",
     "func_eager",
     "eager",
-    "ensure_corofunc",
     "coro_get_frame",
     "coro_is_new",
     "coro_is_suspended",
@@ -43,6 +41,8 @@ __all__ = [
     "coro_sync",
     "SynchronousError",
     "SynchronousAbort",
+    "asyncfunction",
+    "syncfunction",
 ]
 
 PYTHON_37 = sys.version_info.major == 3 and sys.version_info.minor == 7
@@ -505,36 +505,10 @@ def awaitmethod(
     return wrapper
 
 
-@overload
 def coro_sync(coro: Coroutine[Any, Any, T]) -> T:
-    ...
-
-
-@overload
-def coro_sync(coro: Callable[P, Coroutine[Any, Any, T]]) -> Callable[P, T]:
-    ...
-
-
-def coro_sync(
-    coro: Union[Coroutine[Any, Any, T], Callable[P, Coroutine[Any, Any, T]]]
-) -> Union[T, Callable[P, T]]:
-
     """Runs a corouting synchronlously.  If the coroutine blocks, a
     SynchronousError is raised.
-
-    Can also be used as a decorator for an async function.
     """
-    if iscoroutinefunction(coro):
-        # we are a decorator
-        coro2 = cast(Callable[..., Coroutine[Any, Any, T]], coro)
-
-        @functools.wraps(coro)
-        def helper(*args: Any, **kwargs: Any) -> T:
-            return coro_sync(coro2(*args, **kwargs))
-
-        return helper
-    coro = cast(Coroutine[Any, Any, T], coro)
-    # We are running a coroutine synchronously
     start = CoroStart[T](coro)
     if start.done():
         return start.result()
@@ -556,17 +530,25 @@ def coro_sync(
             pass
 
 
-def ensure_corofunc(
-    callable: Union[Callable[P, T], Callable[P, Coroutine[Any, Any, T]]]
-) -> Callable[P, Coroutine[Any, Any, T]]:
-    """Make a callable async, so that the result needs to be awaited.
-    Useful for adding synchronous callbacs to async code.
+def syncfunction(func: Callable[P, Coroutine[Any, Any, T]]) -> Callable[P, T]:
+    """Make an async function synchronous, by invoking
+    `coro_sync()` on its coroutine.  Useful as a decorator.
+    """
+
+    @functools.wraps(func)
+    def helper(*args: P.args, **kwargs: P.kwargs) -> T:
+        return coro_sync(func(*args, **kwargs))
+
+    return helper
+
+
+def asyncfunction(func: Callable[P, T]) -> Callable[P, Coroutine[Any, Any, T]]:
+    """Make a regular function async, so that its result needs to be awaited.
+    Useful when providing synchronous callbacks to async code.
     """
-    if inspect.iscoroutinefunction(callable):
-        return callable
 
+    @functools.wraps(func)
     async def helper(*args: P.args, **kwargs: P.kwargs) -> T:
-        callable2 = cast(Callable[P, T], callable)
-        return callable2(*args, **kwargs)
+        return func(*args, **kwargs)
 
     return helper