ez-a-sync 0.22.15__py3-none-any.whl → 0.22.16__py3-none-any.whl

a_sync/a_sync/decorator.py

@@ -35,6 +35,20 @@ def a_sync(
     Args:
         default: Specifies the default execution mode as 'async'.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+
+    Examples:
+        Basic usage with an asynchronous default:
+
+        >>> @a_sync(default='async')
+        ... async def my_function():
+        ...     return True
+        >>> await my_function()
+        True
+        >>> my_function(sync=True)
+        True
+
+    See Also:
+        :class:`ASyncDecoratorAsyncDefault`
     """
 
 
@@ -49,6 +63,20 @@ def a_sync(
     Args:
         default: Specifies the default execution mode as 'sync'.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+
+    Examples:
+        Basic usage with a synchronous default:
+
+        >>> @a_sync(default='sync')
+        ... def my_function():
+        ...     return True
+        >>> my_function()
+        True
+        >>> await my_function(sync=False)
+        True
+
+    See Also:
+        :class:`ASyncDecoratorSyncDefault`
     """
 
 
@@ -61,6 +89,20 @@ def a_sync(
 
     Args:
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+
+    Examples:
+        Usage without specifying a default mode:
+
+        >>> @a_sync
+        ... async def my_function():
+        ...     return True
+        >>> await my_function()
+        True
+        >>> my_function(sync=True)
+        True
+
+    See Also:
+        :class:`ASyncDecorator`
     """
 
 
@@ -77,6 +119,20 @@ def a_sync(
         coro_fn: The coroutine function to be decorated.
         default: Specifies no default execution mode.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+
+    Examples:
+        Decorating an asynchronous function without a default mode:
+
+        >>> async def my_function():
+        ...     return True
+        >>> decorated_function = a_sync(my_function)
+        >>> await decorated_function()
+        True
+        >>> decorated_function(sync=True)
+        True
+
+    See Also:
+        :class:`ASyncFunctionAsyncDefault`
     """
 
 
@@ -93,18 +149,21 @@ def a_sync(
         coro_fn: The synchronous function to be decorated.
         default: Specifies no default execution mode.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
-    """
-
 
-# @a_sync(default='async')
-# def some_fn():
-#     pass
-#
-# @a_sync(default='async')
-# async def some_fn():
-#     pass
-#
-# NOTE These should output a decorator that will be applied to 'some_fn'
+    Examples:
+        Decorating a synchronous function without a default mode:
+
+        >>> def my_function():
+        ...     return True
+        >>> decorated_function = a_sync(my_function)
+        >>> decorated_function()
+        True
+        >>> await decorated_function(sync=False)
+        True
+
+    See Also:
+        :class:`ASyncFunctionSyncDefault`
+    """
 
 
 @overload
@@ -120,6 +179,20 @@ def a_sync(
         coro_fn: Specifies no function.
         default: Specifies the default execution mode as 'async'.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+
+    Examples:
+        Creating an asynchronous default decorator without a function:
+
+        >>> @a_sync(default='async')
+        ... async def my_function():
+        ...     return True
+        >>> await my_function()
+        True
+        >>> my_function(sync=True)
+        True
+
+    See Also:
+        :class:`ASyncDecoratorAsyncDefault`
     """
 
 
@@ -136,10 +209,21 @@ def a_sync(
         coro_fn: Specifies the default execution mode as 'async'.
         default: Specifies no default execution mode.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
-    """
-
 
-# a_sync(some_fn, default='async')
+    Examples:
+        Using 'async' as the only argument:
+
+        >>> @a_sync('async')
+        ... async def my_function():
+        ...     return True
+        >>> await my_function()
+        True
+        >>> my_function(sync=True)
+        True
+
+    See Also:
+        :class:`ASyncDecoratorAsyncDefault`
+    """
 
 
 @overload  # async def, async default
@@ -155,6 +239,20 @@ def a_sync(
         coro_fn: The coroutine function to be decorated.
         default: Specifies the default execution mode as 'async'.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+
+    Examples:
+        Decorating an asynchronous function with an async default:
+
+        >>> async def my_function():
+        ...     return True
+        >>> decorated_function = a_sync(my_function, default='async')
+        >>> await decorated_function()
+        True
+        >>> decorated_function(sync=True)
+        True
+
+    See Also:
+        :class:`ASyncFunctionAsyncDefault`
     """
 
 
@@ -171,10 +269,21 @@ def a_sync(
         coro_fn: The synchronous function to be decorated.
         default: Specifies the default execution mode as 'async'.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
-    """
-
 
-# a_sync(some_fn, default='sync')
+    Examples:
+        Decorating a synchronous function with an async default:
+
+        >>> def my_function():
+        ...     return True
+        >>> decorated_function = a_sync(my_function, default='async')
+        >>> await decorated_function()
+        True
+        >>> decorated_function(sync=True)
+        True
+
+    See Also:
+        :class:`ASyncFunctionAsyncDefault`
+    """
 
 
 @overload  # async def, sync default
@@ -190,6 +299,20 @@ def a_sync(
         coro_fn: The coroutine function to be decorated.
         default: Specifies the default execution mode as 'sync'.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+
+    Examples:
+        Decorating an asynchronous function with a sync default:
+
+        >>> async def my_function():
+        ...     return True
+        >>> decorated_function = a_sync(my_function, default='sync')
+        >>> decorated_function()
+        True
+        >>> await decorated_function(sync=False)
+        True
+
+    See Also:
+        :class:`ASyncFunctionSyncDefault`
     """
 
 
@@ -206,18 +329,21 @@ def a_sync(
         coro_fn: The synchronous function to be decorated.
         default: Specifies the default execution mode as 'sync'.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
-    """
 
-
-# @a_sync(default='sync')
-# def some_fn():
-#     pass
-#
-# @a_sync(default='sync')
-# async def some_fn():
-#     pass
-#
-# NOTE These should output a decorator that will be applied to 'some_fn'
+    Examples:
+        Decorating a synchronous function with a sync default:
+
+        >>> def my_function():
+        ...     return True
+        >>> decorated_function = a_sync(my_function, default='sync')
+        >>> decorated_function()
+        True
+        >>> await decorated_function(sync=False)
+        True
+
+    See Also:
+        :class:`ASyncFunctionSyncDefault`
+    """
 
 
 @overload
@@ -233,6 +359,20 @@ def a_sync(
         coro_fn: Specifies no function.
         default: Specifies the default execution mode as 'sync'.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+
+    Examples:
+        Creating a synchronous default decorator without a function:
+
+        >>> @a_sync(default='sync')
+        ... def my_function():
+        ...     return True
+        >>> my_function()
+        True
+        >>> await my_function(sync=False)
+        True
+
+    See Also:
+        :class:`ASyncDecoratorSyncDefault`
     """
 
 
@@ -249,6 +389,20 @@ def a_sync(
         coro_fn: Specifies the default execution mode as 'sync'.
         default: Specifies no default execution mode.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+
+    Examples:
+        Using 'sync' as the only argument:
+
+        >>> @a_sync('sync')
+        ... def my_function():
+        ...     return True
+        >>> my_function()
+        True
+        >>> await my_function(sync=False)
+        True
+
+    See Also:
+        :class:`ASyncDecoratorSyncDefault`
     """
 
 
@@ -265,6 +419,20 @@ def a_sync(
         coro_fn: Specifies the default execution mode as 'sync'.
         default: Specifies no default execution mode.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+
+    Examples:
+        Using 'sync' as the only argument:
+
+        >>> @a_sync('sync')
+        ... def my_function():
+        ...     return True
+        >>> my_function()
+        True
+        >>> await my_function(sync=False)
+        True
+
+    See Also:
+        :class:`ASyncDecoratorSyncDefault`
     """
 
 
@@ -313,9 +481,9 @@ def a_sync(
             >>> @a_sync
             ... async def some_async_fn():
             ...     return True
-            >>> await some_fn()
+            >>> await some_async_fn()
             True
-            >>> some_fn(sync=True)
+            >>> some_async_fn(sync=True)
             True
 
             >>> @a_sync
@@ -324,7 +492,7 @@ def a_sync(
             >>> some_sync_fn()
             True
             >>> some_sync_fn(sync=False)
-            <coroutine object some_sync_fn at 0x12345678>
+            <coroutine object some_sync_fn at 0x7fb4f5fb49c0>
 
         2. As a decorator with default mode specified:
             >>> @a_sync(default='sync')
@@ -333,6 +501,17 @@ def a_sync(
             ...
             >>> some_fn()
             True
+            >>> some_fn(sync=False)
+            <coroutine object some_fn at 0x7fb4f5fb49c0>
+
+            >>> @a_sync('async')
+            ... def some_fn():
+            ...     return True
+            ...
+            >>> some_fn()
+            <coroutine object some_fn at 0x7fb4f5fb49c0>
+            >>> some_fn(asynchronous=False)
+            True
 
         3. As a decorator with modifiers:
             >>> @a_sync(cache_type='memory', runs_per_minute=60)
@@ -348,18 +527,19 @@ def a_sync(
             "some return value"
 
     The decorated function can then be called either synchronously or asynchronously:
-
-        result = some_fn()  # Synchronous call
-        result = await some_fn()  # Asynchronous call
+        >>> result = some_fn()  # Synchronous call
+        >>> result = await some_fn()  # Asynchronous call
 
     The execution mode can also be explicitly specified during the call:
-
-        result = some_fn(sync=True)  # Force synchronous execution
-        result = await some_fn(sync=False)  # Force asynchronous execution
+        >>> result = some_fn(sync=True)  # Force synchronous execution
+        >>> result = await some_fn(sync=False)  # Force asynchronous execution
 
     This decorator is particularly useful for libraries that need to support
     both synchronous and asynchronous usage, or for gradually migrating
     synchronous code to asynchronous without breaking existing interfaces.
+
+    See Also:
+        :class:`ASyncFunction`, :class:`ASyncDecorator`
     """
 
     # If the dev tried passing a default as an arg instead of a kwarg, ie: @a_sync('sync')...