Version 0.2.0.0

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Latest changes
 
+## 0.2.0.0
+
+Added docs, proper typing everywhere, fixed hanging issues in some contexts as well as the `get_event_loop` function
+
 ## 0.1.0.0
 
 Initial release

README.md

@@ -7,10 +7,72 @@
 
 A library to help automate the creation of universal python libraries
 
+## Overview
+
+Have you ever been frustrated that you need to maintain both sync and async versions of your library, even thought their code differs by just async and await?
+You might have came up to rewriting your code before release or other unreliable solutions.
+
+This library helps you to focus only on the main async implementation of your library: sync one will be created automatically
+
+Via decorating all your public methods, the wrapped functions automatically detect different conditions and run the functions accordingly.
+
+If user uses your library in async context, minimal overhead is added, it just returns the coroutine right away.
+
+Otherwise the library calls the coroutine via various loop methods, like as if you did it manually.
+
+There should be no issues at all, the only limitation is that signals and async subprocesses are supported only when running in the main thread.
+
+Also note that when run from a different os thread, the library will create a new event loop there and run coroutines.
+
+This means that you might need to adapt your code a bit in case you use some resources bound to a certain event loop (like `aiohttp.ClientSession`).
+
+You can see an example of how this could be solved [here](https://github.com/bitcartcc/bitcart-sdk/blob/4a425f80f62a0c90f8c5fa19ccb7e578590dcead/bitcart/providers/jsonrpcrequests.py#L51-L58)
+
 ## Installation
 
 `pip install universalasync`
 
+## Example of usage
+
+```python
+# wrap needed methods one by one
+class Client:
+    @async_to_sync_wraps
+    async def help():
+        ...
+
+    @async_to_sync_wraps
+    @property
+    async def async_property():
+        ...
+
+# or wrap whole classes
+@wrap
+class Client:
+    async def help(self):
+        ...
+
+    @property
+    async def async_property():
+        ...
+
+client = Client()
+
+def sync_call():
+    client.help()
+    client.async_property
+
+async def async_call():
+    await client.help()
+    await client.async_property
+
+# works in all cases
+sync_call()
+asyncio.run(async_call())
+threading.Thread(target=sync_call).start()
+threading.Thread(target=asyncio.run, args=(async_call(),)).start()
+```
+
 ## Copyright and License
 
 Copyright (C) 2021 MrNaif2018

docs/index.rst

@@ -15,7 +15,74 @@ Welcome to universalasync's documentation!
 
 A library to help automate the creation of universal python libraries
 
+Overview
+========
+
+Have you ever been frustrated that you need to maintain both sync and async versions of your library, even thought their code differs by just async and await?
+You might have came up to rewriting your code before release or other unreliable solutions.
+
+This library helps you to focus only on the main async implementation of your library: sync one will be created automatically
+
+Via decorating all your public methods, the wrapped functions automatically detect different conditions and run the functions accordingly.
+
+If user uses your library in async context, minimal overhead is added, it just returns the coroutine right away.
+
+Otherwise the library calls the coroutine via various loop methods, like as if you did it manually.
+
+There should be no issues at all, the only limitation is that signals and async subprocesses are supported only when running in the main thread.
+
+Also note that when run from a different os thread, the library will create a new event loop there and run coroutines.
+
+This means that you might need to adapt your code a bit in case you use some resources bound to a certain event loop (like ``aiohttp.ClientSession``).
+
+You can see an example of how this could be solved `here <https://github.com/bitcartcc/bitcart-sdk/blob/4a425f80f62a0c90f8c5fa19ccb7e578590dcead/bitcart/providers/jsonrpcrequests.py#L51-L58>`_
+
 Installation
 ============
 
 ``pip install universalasync``
+
+.. _example:
+
+Example of usage
+================
+
+
+.. code-block:: python
+
+        # wrap needed methods one by one
+        class Client:
+            @async_to_sync_wraps
+            async def help():
+                ...
+
+            @async_to_sync_wraps
+            @property
+            async def async_property():
+                ...
+
+        # or wrap whole classes
+        @wrap
+        class Client:
+            async def help(self):
+                ...
+
+            @property
+            async def async_property():
+                ...
+
+        client = Client()
+
+        def sync_call():
+            client.help()
+            client.async_property
+
+        async def async_call():
+            await client.help()
+            await client.async_property
+
+        # works in all cases
+        sync_call()
+        asyncio.run(async_call())
+        threading.Thread(target=sync_call).start()
+        threading.Thread(target=asyncio.run, args=(async_call(),)).start()

universalasync/__init__.py

@@ -3,11 +3,11 @@
 from typing import Any
 
 from .utils import get_event_loop
-from .wrapper import async_to_sync, async_to_sync_wraps, wrap
+from .wrapper import async_to_sync_wraps, wrap
 
 
 @async_to_sync_wraps
-async def idle() -> Any:
+async def idle() -> None:
     """Useful for making event loop idle in the main thread for other threads to work"""
     is_idling = True
 
@@ -23,4 +23,4 @@ def signal_handler(*args: Any, **kwargs: Any) -> None:
         await asyncio.sleep(1)
 
 
-__all__ = ["async_to_sync", "async_to_sync_wraps", "wrap", "get_event_loop", "idle"]
+__all__ = ["async_to_sync_wraps", "wrap", "get_event_loop", "idle"]

universalasync/utils.py

@@ -17,6 +17,8 @@ def _get_event_loop() -> asyncio.AbstractEventLoop:
 def get_event_loop() -> asyncio.AbstractEventLoop:
     """Useful utility for getting event loop. Acts like get_event_loop(), but also creates new event loop if needed
 
+    This will return a working event loop in 100% of cases.
+
     Returns:
         asyncio.AbstractEventLoop: event loop
     """

universalasync/version.py

@@ -1 +1 @@
-VERSION = "0.1.0.0"
+VERSION = "0.2.0.0"

universalasync/wrapper.py

@@ -33,15 +33,29 @@ def run_sync_ctx(coroutine: Any, loop: asyncio.AbstractEventLoop) -> Any:
         return iter_over_async(coroutine, lambda coro: loop.run_until_complete(coro))
 
 
-def async_to_sync_wraps(function: Callable, is_property: bool = False) -> Union[Callable, property]:
+def async_to_sync_wraps(function: Callable) -> Union[Callable, property]:
+    """Wrap an async method/property to universal method.
+
+    This allows to run wrapped methods in both async and sync contexts transparently without any additional code
+
+    When run from another thread, it runs coroutines in new thread's event loop
+
+    See :ref:`Example <example>` for full example
+
+    Args:
+        function (Callable): function/property to wrap
+
+    Returns:
+        Union[Callable, property]: modified function
+    """
+    is_property = inspect.isdatadescriptor(function)
+    if is_property:
+        function = cast(types.MethodDescriptorType, function).__get__
+
     @functools.wraps(function)
     def async_to_sync_wrap(*args: Any, **kwargs: Any) -> Any:
         loop = get_event_loop()
-
-        if is_property:
-            coroutine = cast(types.MethodDescriptorType, function).__get__(*args, **kwargs)
-        else:
-            coroutine = function(*args, **kwargs)
+        coroutine = function(*args, **kwargs)
 
         if loop.is_running():
             return coroutine
@@ -51,7 +65,7 @@ def async_to_sync_wrap(*args: Any, **kwargs: Any) -> Any:
             finally:
                 shutdown_tasks(loop)
                 loop.run_until_complete(loop.shutdown_asyncgens())
-                if sys.version_info >= (3, 9):
+                if sys.version_info >= (3, 9):  # pragma: no cover
                     loop.run_until_complete(loop.shutdown_default_executor())
 
     result: Union[Callable, property] = async_to_sync_wrap
@@ -69,19 +83,23 @@ def shutdown_tasks(loop: asyncio.AbstractEventLoop) -> None:
     loop.run_until_complete(asyncio.gather(*to_cancel, return_exceptions=True))
 
 
-def async_to_sync(obj: object, name: str, is_property: bool = False) -> None:
-    function = getattr(obj, name)
+def wrap(source: object) -> object:
+    """Convert all public async methods/properties of an object to universal methods.
 
-    setattr(obj, name, async_to_sync_wraps(function, is_property=is_property))
+    See :func:`async_to_sync_wraps` for more info
 
+    Args:
+        source (object): object to convert
 
-def wrap(source: object) -> object:
+    Returns:
+        object: converted object. Note that parameter passed is being modified anyway
+    """
     for name in dir(source):
         method = getattr(source, name)
 
         if not name.startswith("_"):
-            is_property = inspect.isdatadescriptor(method)
-            if inspect.iscoroutinefunction(method) or inspect.isasyncgenfunction(method) or is_property:
-                async_to_sync(source, name, is_property=is_property)
+            if inspect.iscoroutinefunction(method) or inspect.isasyncgenfunction(method) or inspect.isdatadescriptor(method):
+                function = getattr(source, name)
+                setattr(source, name, async_to_sync_wraps(function))
 
     return source