asynkit 0.9.0__tar.gz → 0.9.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: asynkit
-Version: 0.9.0
+Version: 0.9.2
 Summary: Async toolkit for advanced scheduling
 Home-page: https://github.com/kristjanvalur/py-asynkit
 License: MIT
@@ -136,28 +136,29 @@ just as would happen if it were directly turned into a `Task`.
 ## `coro_sync()` - Running coroutines synchronously
 
 If you are writing code which should work both synchronously and asynchronously,
-you can now write the code fully _async_ and then syn it _synchronously_ in the absence
-of an event loop.  Should the code cause any async features to be triggered, an exception is raised.  This helps avoid writing duplicate code.
+you can now write the code fully _async_ and then run it _synchronously_ in the absence
+of an event loop.  As long as the code doesn't _block_ (await unfinished _futures_) and doesn't try to access the event loop, it can successfully be executed.  This helps avoid writing duplicate code.
 
 ```python
-async def get_processed_data(datagetter):
-    data = datagetter()  # could be an async callback
+async def async_get_processed_data(datagetter):
+    data = datagetter()  # an optionally async callback
     data = await data if isawaitable(data) else data
     return process_data(data)
 
 
-# will raise SynchronousError if it datagetter to be async
+# raises SynchronousError if datagetter blocks
 def sync_get_processed_data(datagetter):
-    return asynkit.coro_sync(combine_stuff(cb1, cb2))
+    return asynkit.coro_sync(async_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)
@@ -167,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
@@ -181,22 +182,42 @@ 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 selectively fail if the logic tries to invoke any truly async operations.
+then simply fail if the code tries to invoke any truly async operations.
+If the invoked coroutine blocks, a `SynchronousError` is raised _from_ a `SynchronousAbort` exception which
+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.  
+
+The `syncfunction()` decorator can be used to automatically wrap an async function
+so that it is executed using `coro_sync()`:
+
+```pycon
+>>> @asynkit.syncfunction
+... async def sync_function():
+...     async def async_function():
+...         return "look, no async!"
+...     return await async_function()
+...
+>>> sync_function()
+'look, no async!'
+>>>
+```
 
-`coro_sync()` can also be applied as a decorator:
+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
-@asynkit.coro_sync
-async def sync_function():
-    return "look ma, no async!"
-
-
-assert sync_function().contains("look")
+@asynkit.syncfunction
+async def sync_client(sync_callback):
+    middleware = AsyncMiddleware(asynkit.asyncfunction(sync_callback))
+    return await middleware.run()
 ```
 
+Using this pattern, one can write the middleware completely async, make it also work
+for synchronous code, while avoiding the hybrid function _antipattern._
 
 ## `CoroStart`
 
@@ -319,6 +340,7 @@ async def runner():
     while True:
         try:
             print(await m.aawait(c))
+            break
         except OOBData as oob:
             print(oob.data)
 ```
@@ -345,7 +367,8 @@ m = Monitor()
 a = m.awaitable(coro(m))
 while True:
     try:
-        return await a
+        await a
+        break
     except OOBData as oob:
         handle_oob(oob.data)
 ```

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

@@ -112,28 +112,29 @@ just as would happen if it were directly turned into a `Task`.
 ## `coro_sync()` - Running coroutines synchronously
 
 If you are writing code which should work both synchronously and asynchronously,
-you can now write the code fully _async_ and then syn it _synchronously_ in the absence
-of an event loop.  Should the code cause any async features to be triggered, an exception is raised.  This helps avoid writing duplicate code.
+you can now write the code fully _async_ and then run it _synchronously_ in the absence
+of an event loop.  As long as the code doesn't _block_ (await unfinished _futures_) and doesn't try to access the event loop, it can successfully be executed.  This helps avoid writing duplicate code.
 
 ```python
-async def get_processed_data(datagetter):
-    data = datagetter()  # could be an async callback
+async def async_get_processed_data(datagetter):
+    data = datagetter()  # an optionally async callback
     data = await data if isawaitable(data) else data
     return process_data(data)
 
 
-# will raise SynchronousError if it datagetter to be async
+# raises SynchronousError if datagetter blocks
 def sync_get_processed_data(datagetter):
-    return asynkit.coro_sync(combine_stuff(cb1, cb2))
+    return asynkit.coro_sync(async_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)
@@ -143,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
@@ -157,22 +158,42 @@ 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 selectively fail if the logic tries to invoke any truly async operations.
+then simply fail if the code tries to invoke any truly async operations.
+If the invoked coroutine blocks, a `SynchronousError` is raised _from_ a `SynchronousAbort` exception which
+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.  
+
+The `syncfunction()` decorator can be used to automatically wrap an async function
+so that it is executed using `coro_sync()`:
+
+```pycon
+>>> @asynkit.syncfunction
+... async def sync_function():
+...     async def async_function():
+...         return "look, no async!"
+...     return await async_function()
+...
+>>> sync_function()
+'look, no async!'
+>>>
+```
 
-`coro_sync()` can also be applied as a decorator:
+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
-@asynkit.coro_sync
-async def sync_function():
-    return "look ma, no async!"
-
-
-assert sync_function().contains("look")
+@asynkit.syncfunction
+async def sync_client(sync_callback):
+    middleware = AsyncMiddleware(asynkit.asyncfunction(sync_callback))
+    return await middleware.run()
 ```
 
+Using this pattern, one can write the middleware completely async, make it also work
+for synchronous code, while avoiding the hybrid function _antipattern._
 
 ## `CoroStart`
 
@@ -295,6 +316,7 @@ async def runner():
     while True:
         try:
             print(await m.aawait(c))
+            break
         except OOBData as oob:
             print(oob.data)
 ```
@@ -321,7 +343,8 @@ m = Monitor()
 a = m.awaitable(coro(m))
 while True:
     try:
-        return await a
+        await a
+        break
     except OOBData as oob:
         handle_oob(oob.data)
 ```

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "asynkit"
-version = "0.9.0"
+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.0 → 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,
@@ -41,7 +40,9 @@ __all__ = [
     "coro_iter",
     "coro_sync",
     "SynchronousError",
-    "CoroutineAbort",
+    "SynchronousAbort",
+    "asyncfunction",
+    "syncfunction",
 ]
 
 PYTHON_37 = sys.version_info.major == 3 and sys.version_info.minor == 7
@@ -64,7 +65,7 @@ class SynchronousError(RuntimeError):
     """
 
 
-class CoroutineAbort(BaseException):
+class SynchronousAbort(BaseException):
     """
     Exception thrown into coroutine to abort it.
     """
@@ -504,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()
@@ -541,7 +516,7 @@ def coro_sync(
     try:
         # we can't use GeneratorExit because that gets special handling and
         # a traceback is not collected.
-        start.throw(CoroutineAbort())
+        start.throw(SynchronousAbort())
     except BaseException as err:
         raise SynchronousError("coroutine failed to complete synchronously") from err
     else:
@@ -553,3 +528,27 @@ def coro_sync(
             start.close()
         except RuntimeError:
             pass
+
+
+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.
+    """
+
+    @functools.wraps(func)
+    async def helper(*args: P.args, **kwargs: P.kwargs) -> T:
+        return func(*args, **kwargs)
+
+    return helper