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

a_sync/a_sync/decorator.py

@@ -2,9 +2,14 @@
 # mypy: disable-error-code=misc
 from a_sync._typing import *
 from a_sync.a_sync import _flags, config
-from a_sync.a_sync.function import (ASyncDecorator, ASyncFunction, ASyncDecoratorAsyncDefault, 
-                             ASyncDecoratorSyncDefault, ASyncFunctionAsyncDefault, 
-                             ASyncFunctionSyncDefault)
+from a_sync.a_sync.function import (
+    ASyncDecorator,
+    ASyncFunction,
+    ASyncDecoratorAsyncDefault,
+    ASyncDecoratorSyncDefault,
+    ASyncFunctionAsyncDefault,
+    ASyncFunctionSyncDefault,
+)
 
 ########################
 # The a_sync decorator #
@@ -18,36 +23,78 @@ from a_sync.a_sync.function import (ASyncDecorator, ASyncFunction, ASyncDecorato
 # async def some_fn():
 #     pass
 
+
 @overload
 def a_sync(
     default: Literal["async"],
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncDecoratorAsyncDefault:...
+) -> ASyncDecoratorAsyncDefault:
+    """
+    Creates an asynchronous default decorator.
+
+    Args:
+        default: Specifies the default execution mode as 'async'.
+        **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+    """
+
 
 @overload
 def a_sync(
     default: Literal["sync"],
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncDecoratorSyncDefault:...
+) -> ASyncDecoratorSyncDefault:
+    """
+    Creates a synchronous default decorator.
+
+    Args:
+        default: Specifies the default execution mode as 'sync'.
+        **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+    """
+
 
 @overload
 def a_sync(
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncDecorator:...
+) -> ASyncDecorator:
+    """
+    Creates a decorator with no default execution mode specified.
 
-@overload # async def, None default
-def a_sync(  
+    Args:
+        **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
+    """
+
+
+@overload  # async def, None default
+def a_sync(
     coro_fn: CoroFn[P, T],
     default: Literal[None] = None,
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncFunctionAsyncDefault[P, T]:...
+) -> ASyncFunctionAsyncDefault[P, T]:
+    """
+    Decorates an asynchronous function with no default execution mode specified.
+
+    Args:
+        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.
+    """
+
 
-@overload # sync def none default
-def a_sync(  
+@overload  # sync def none default
+def a_sync(
     coro_fn: SyncFn[P, T],
     default: Literal[None] = None,
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncFunctionSyncDefault[P, T]:...
+) -> ASyncFunctionSyncDefault[P, T]:
+    """
+    Decorates a synchronous function with no default execution mode specified.
+
+    Args:
+        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():
@@ -59,51 +106,108 @@ def a_sync(
 #
 # NOTE These should output a decorator that will be applied to 'some_fn'
 
-@overload 
-def a_sync(  
+
+@overload
+def a_sync(
     coro_fn: Literal[None],
-    default: Literal['async'],
+    default: Literal["async"],
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncDecoratorAsyncDefault:...
+) -> ASyncDecoratorAsyncDefault:
+    """
+    Creates an asynchronous default decorator with no function specified.
+
+    Args:
+        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.
+    """
+
 
-@overload # if you try to use default as the only arg
-def a_sync(  
-    coro_fn: Literal['async'],
+@overload  # if you try to use default as the only arg
+def a_sync(
+    coro_fn: Literal["async"],
     default: Literal[None],
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncDecoratorAsyncDefault:...
+) -> ASyncDecoratorAsyncDefault:
+    """
+    Creates an asynchronous default decorator with no default execution mode specified.
+
+    Args:
+        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')
 
-@overload # async def, async default
-def a_sync(  
+
+@overload  # async def, async default
+def a_sync(
     coro_fn: CoroFn[P, T],
-    default: Literal['async'],
+    default: Literal["async"],
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncFunctionAsyncDefault[P, T]:...
+) -> ASyncFunctionAsyncDefault[P, T]:
+    """
+    Decorates an asynchronous function with an asynchronous default execution mode.
+
+    Args:
+        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.
+    """
+
 
-@overload # sync def async default
-def a_sync(  
+@overload  # sync def async default
+def a_sync(
     coro_fn: SyncFn[P, T],
-    default: Literal['async'],
+    default: Literal["async"],
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncFunctionAsyncDefault[P, T]:...
+) -> ASyncFunctionAsyncDefault[P, T]:
+    """
+    Decorates a synchronous function with an asynchronous default execution mode.
+
+    Args:
+        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')
 
-@overload # async def, sync default
-def a_sync(  
+
+@overload  # async def, sync default
+def a_sync(
     coro_fn: CoroFn[P, T],
-    default: Literal['sync'],
+    default: Literal["sync"],
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncFunctionSyncDefault:...
+) -> ASyncFunctionSyncDefault:
+    """
+    Decorates an asynchronous function with a synchronous default execution mode.
 
-@overload # sync def sync default
-def a_sync(  
+    Args:
+        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.
+    """
+
+
+@overload  # sync def sync default
+def a_sync(
     coro_fn: SyncFn[P, T],
-    default: Literal['sync'],
+    default: Literal["sync"],
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncFunctionSyncDefault:...
+) -> ASyncFunctionSyncDefault:
+    """
+    Decorates a synchronous function with a synchronous default execution mode.
+
+    Args:
+        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():
@@ -115,32 +219,62 @@ def a_sync(
 #
 # NOTE These should output a decorator that will be applied to 'some_fn'
 
-@overload 
-def a_sync(  
+
+@overload
+def a_sync(
     coro_fn: Literal[None],
-    default: Literal['sync'],
+    default: Literal["sync"],
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncDecoratorSyncDefault:...
+) -> ASyncDecoratorSyncDefault:
+    """
+    Creates a synchronous default decorator with no function specified.
+
+    Args:
+        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.
+    """
 
-@overload # if you try to use default as the only arg
-def a_sync(  
-    coro_fn: Literal['sync'],
+
+@overload  # if you try to use default as the only arg
+def a_sync(
+    coro_fn: Literal["sync"],
     default: Literal[None] = None,
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncDecoratorSyncDefault:...
+) -> ASyncDecoratorSyncDefault:
+    """
+    Creates a synchronous default decorator with no default execution mode specified.
+
+    Args:
+        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.
+    """
 
-@overload # if you try to use default as the only arg
-def a_sync(  
-    coro_fn: Literal['sync'],
+
+@overload  # if you try to use default as the only arg
+def a_sync(
+    coro_fn: Literal["sync"],
     default: Literal[None],
     **modifiers: Unpack[ModifierKwargs],
-) -> ASyncDecoratorSyncDefault:...
-    
+) -> ASyncDecoratorSyncDefault:
+    """
+    Creates a synchronous default decorator with no default execution mode specified.
+
+    Args:
+        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.
+    """
+
+
 # catchall
-def a_sync(  
+def a_sync(
     coro_fn: Optional[AnyFn[P, T]] = None,
     default: DefaultMode = config.DEFAULT_MODE,
-    **modifiers: Unpack[ModifierKwargs],  # default values are set by passing these kwargs into a ModifierManager object.
+    **modifiers: Unpack[
+        ModifierKwargs
+    ],  # default values are set by passing these kwargs into a ModifierManager object.
 ) -> Union[ASyncDecorator, ASyncFunction[P, T]]:
     """
     A versatile decorator that enables both synchronous and asynchronous execution of functions.
@@ -155,97 +289,84 @@ def a_sync(
                  If None, the mode is inferred from the decorated function type.
         **modifiers: Additional keyword arguments to modify the behavior of the decorated function.
                      See :class:`ModifierKwargs` for available options.
-    
+
     Modifiers:
-        lib defaults:
-            async settings
-                cache_type: CacheType = None,            - This can be None or 'memory'. 'memory' is a lru cache which can be modified with the 'cache_typed','ram_cache_maxsize','ram_cache_ttl' modifiers.
-                cache_typed: bool = False,               - Set to True if you want types considered treated for cache keys. ie with cache_typed=True, Decimal(0) and 0 will be considered separate keys.
-                ram_cache_maxsize: Optional[int] = -1,   - The maxsize for your lru cache. None if cache is unbounded. If you set this value without specifying a cache type, 'memory' will automatically be applied.
-                ram_cache_ttl: Optional[int] = None,     - The ttl for items in your lru cache. Set to None. If you set this value without specifying a cache type, 'memory' will automatically be applied.
-                runs_per_minute: Optional[int] = None,   - Setting this value enables a rate limiter for the decorated function.
-                semaphore: SemaphoreSpec = None,         - drop in a Semaphore for your async defined functions.
-            sync settings
-                executor: Executor = config.default_sync_executor
-
-    Returns:
-        An :class:`~ASyncDecorator` if used as a decorator factory, or an :class:`~ASyncFunction`
-        if used directly on a function.
+        The following modifiers can be used to customize the behavior of the decorator:
+
+        - cache_type: Can be None or 'memory'. 'memory' is an LRU cache which can be modified with
+          the 'cache_typed', 'ram_cache_maxsize', and 'ram_cache_ttl' modifiers.
+        - cache_typed: Set to True if you want types considered for cache keys. For example, with
+          cache_typed=True, Decimal(0) and 0 will be considered separate keys.
+        - ram_cache_maxsize: The max size for your LRU cache. None if the cache is unbounded. If you
+          set this value without specifying a cache type, 'memory' will automatically be applied.
+        - ram_cache_ttl: The TTL for items in your LRU cache. Set to None. If you set this value
+          without specifying a cache type, 'memory' will automatically be applied.
+        - runs_per_minute: Setting this value enables a rate limiter for the decorated function.
+        - semaphore: Drop in a Semaphore for your async defined functions.
+        - executor: The executor for the synchronous function. Set to the library's default of
+          config.default_sync_executor.
 
     Examples:
         The decorator can be used in several ways.
 
         1. As a simple decorator:
-        ```python
-        >>> @a_sync
-        ... async def some_async_fn():
-        ...     return True
-        >>> await some_fn()
-        True
-        >>> some_fn(sync=True)
-        True
-        ```
-        ```
-        >>> @a_sync
-        ... def some_sync_fn():
-        ...     return True
-        >>> some_sync_fn()
-        True
-        >>> some_sync_fn(sync=False)
-        <coroutine object some_sync_fn at 0x12345678>
-        ```
+            >>> @a_sync
+            ... async def some_async_fn():
+            ...     return True
+            >>> await some_fn()
+            True
+            >>> some_fn(sync=True)
+            True
+
+            >>> @a_sync
+            ... def some_sync_fn():
+            ...     return True
+            >>> some_sync_fn()
+            True
+            >>> some_sync_fn(sync=False)
+            <coroutine object some_sync_fn at 0x12345678>
 
         2. As a decorator with default mode specified:
-        ```python
-        >>> @a_sync(default='sync')
-        ... async def some_fn():
-        ...     return True
-        ...
-        >>> some_fn()
-        True
-        ```
+            >>> @a_sync(default='sync')
+            ... async def some_fn():
+            ...     return True
+            ...
+            >>> some_fn()
+            True
 
         3. As a decorator with modifiers:
-        ```python
-        >>> @a_sync(cache_type='memory', runs_per_minute=60)
-        ... async def some_fn():
-        ...    return True
-        ...
-        >>> some_fn(sync=True)
-        True
-        ```
+            >>> @a_sync(cache_type='memory', runs_per_minute=60)
+            ... async def some_fn():
+            ...    return True
+            ...
+            >>> some_fn(sync=True)
+            True
 
         4. Applied directly to a function:
-        ```python
-        >>> some_fn = a_sync(some_existing_function, default='sync')
-        >>> some_fn()
-        "some return value"
-        ```
+            >>> some_fn = a_sync(some_existing_function, default='sync')
+            >>> some_fn()
+            "some return value"
 
     The decorated function can then be called either synchronously or asynchronously:
 
-    ```python
-    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:
 
-    ```python
-    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.
     """
-    
+
     # If the dev tried passing a default as an arg instead of a kwarg, ie: @a_sync('sync')...
-    if coro_fn in ['async', 'sync']:
+    if coro_fn in ["async", "sync"]:
         default = coro_fn  # type: ignore [assignment]
         coro_fn = None
-    
+
     if default == "sync":
         deco = ASyncDecoratorSyncDefault(default=default, **modifiers)
     elif default == "async":
@@ -254,4 +375,5 @@ def a_sync(
         deco = ASyncDecorator(default=default, **modifiers)
     return deco if coro_fn is None else deco(coro_fn)  # type: ignore [arg-type]
 
-# TODO: in a future release, I will make this usable with sync functions as well
+
+# TODO: in a future release, I will make this usable with sync functions as well