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

a_sync/a_sync/modifiers/__init__.py

@@ -1,3 +1,30 @@
+"""
+This file contains all logic for ez-a-sync's "modifiers".
+
+Modifiers modify the behavior of ez-a-sync's ASync objects in various ways.
+
+Submodules:
+    cache: Handles caching mechanisms for async functions.
+    limiter: Manages rate limiting for async functions.
+    manager: Provides management of valid modifiers and their application.
+    semaphores: Implements semaphore logic for controlling concurrency.
+
+The modifiers available are:
+- `cache_type`: Specifies the type of cache to use, such as 'memory'.
+- `cache_typed`: Determines if types are considered for cache keys.
+- `ram_cache_maxsize`: Sets the maximum size for the LRU cache.
+- `ram_cache_ttl`: Defines the time-to-live for items in the cache.
+- `runs_per_minute`: Sets a rate limit for function execution.
+- `semaphore`: Specifies a semaphore for controlling concurrency.
+- `executor`: Defines the executor for synchronous functions. This is not applied like the other modifiers but is used to manage the execution context for synchronous functions when they are called in an asynchronous manner.
+
+See Also:
+    - :mod:`a_sync.a_sync.modifiers.cache`
+    - :mod:`a_sync.a_sync.modifiers.limiter`
+    - :mod:`a_sync.a_sync.modifiers.manager`
+    - :mod:`a_sync.a_sync.modifiers.semaphores`
+"""
+
 from aiolimiter import AsyncLimiter
 
 from a_sync._typing import *
@@ -6,14 +33,67 @@ from a_sync.a_sync.modifiers.manager import valid_modifiers
 
 
 def get_modifiers_from(thing: Union[dict, type, object]) -> ModifierKwargs:
+    """Extracts valid modifiers from a given object, type, or dictionary.
+
+    Args:
+        thing: The source from which to extract modifiers. It can be a dictionary,
+            a type, or an object.
+
+    Returns:
+        A ModifierKwargs object containing the valid modifiers extracted from the input.
+
+    Examples:
+        Extracting modifiers from a class:
+
+        >>> class Example:
+        ...     cache_type = 'memory'
+        ...     runs_per_minute = 60
+        >>> get_modifiers_from(Example)
+        ModifierKwargs({'cache_type': 'memory', 'runs_per_minute': 60})
+
+        Extracting modifiers from a dictionary:
+
+        >>> modifiers_dict = {'cache_type': 'memory', 'semaphore': 5}
+        >>> get_modifiers_from(modifiers_dict)
+        ModifierKwargs({'cache_type': 'memory', 'semaphore': ThreadsafeSemaphore(5)})
+
+    See Also:
+        - :class:`a_sync.a_sync.modifiers.manager.ModifierManager`
+    """
     if isinstance(thing, dict):
         apply_class_defined_modifiers(thing)
         return ModifierKwargs({modifier: thing[modifier] for modifier in valid_modifiers if modifier in thing})  # type: ignore [misc]
     return ModifierKwargs({modifier: getattr(thing, modifier) for modifier in valid_modifiers if hasattr(thing, modifier)})  # type: ignore [misc]
 
+
 def apply_class_defined_modifiers(attrs_from_metaclass: dict):
-    if 'semaphore' in attrs_from_metaclass and isinstance(val := attrs_from_metaclass['semaphore'], int):
-        attrs_from_metaclass['semaphore'] = ThreadsafeSemaphore(val)
-    if "runs_per_minute" in attrs_from_metaclass and isinstance(val := attrs_from_metaclass['runs_per_minute'], int):
-        attrs_from_metaclass['runs_per_minute'] = AsyncLimiter(val)
-        
+    """Applies class-defined modifiers to a dictionary of attributes.
+
+    This function modifies the input dictionary in place. If the 'semaphore' key
+    is present and its value is an integer, it is converted to a ThreadsafeSemaphore.
+    If the 'runs_per_minute' key is present and its value is an integer, it is
+    converted to an AsyncLimiter. If these keys are not present or their values
+    are not integers, the function will silently do nothing.
+
+    Args:
+        attrs_from_metaclass: A dictionary of attributes from a metaclass.
+
+    Examples:
+        Applying modifiers to a dictionary:
+
+        >>> attrs = {'semaphore': 3, 'runs_per_minute': 60}
+        >>> apply_class_defined_modifiers(attrs)
+        >>> attrs['semaphore']
+        ThreadsafeSemaphore(3)
+
+        >>> attrs['runs_per_minute']
+        AsyncLimiter(60)
+
+    See Also:
+        - :class:`a_sync.primitives.locks.ThreadsafeSemaphore`
+        - :class:`aiolimiter.AsyncLimiter`
+    """
+    if isinstance(val := attrs_from_metaclass.get("semaphore"), int):
+        attrs_from_metaclass["semaphore"] = ThreadsafeSemaphore(val)
+    if isinstance(val := attrs_from_metaclass.get("runs_per_minute"), int):
+        attrs_from_metaclass["runs_per_minute"] = AsyncLimiter(val)

a_sync/a_sync/modifiers/cache/__init__.py

@@ -8,53 +8,152 @@ from a_sync.a_sync.modifiers.cache.memory import apply_async_memory_cache
 
 
 class CacheArgs(TypedDict):
+    """Typed dictionary for cache arguments."""
+
     cache_type: CacheType
+    """The type of cache to use. Currently, only 'memory' is implemented."""
+
     cache_typed: bool
+    """Whether to consider types for cache keys."""
+
     ram_cache_maxsize: Optional[int]
+    """The maximum size for the LRU cache."""
+
     ram_cache_ttl: Optional[int]
+    """The time-to-live for items in the LRU cache."""
+
 
 @overload
 def apply_async_cache(
-    coro_fn: Literal[None],
     **modifiers: Unpack[CacheArgs],
-) -> AsyncDecorator[P, T]:...
-    
+) -> AsyncDecorator[P, T]:
+    """Creates a decorator to apply an asynchronous cache.
+
+    This overload is used when no coroutine function is provided. The returned
+    decorator can be applied to a coroutine function later.
+
+    Args:
+        **modifiers: Cache configuration options such as `cache_type`, `cache_typed`, `ram_cache_maxsize`, and `ram_cache_ttl`.
+
+    Examples:
+        >>> @apply_async_cache(cache_type='memory', ram_cache_maxsize=100)
+        ... async def my_function():
+        ...     pass
+
+    See Also:
+        :func:`apply_async_memory_cache`
+    """
+
+
 @overload
 def apply_async_cache(
     coro_fn: int,
     **modifiers: Unpack[CacheArgs],
-) -> AsyncDecorator[P, T]:...
-    
+) -> AsyncDecorator[P, T]:
+    """Creates a decorator with `ram_cache_maxsize` set by an integer.
+
+    This overload is used when an integer is provided as the first argument,
+    which sets the `ram_cache_maxsize` for the cache. The returned decorator
+    can be applied to a coroutine function later.
+
+    Args:
+        coro_fn: An integer to set as the max size for the cache.
+        **modifiers: Additional cache configuration options.
+
+    Examples:
+        >>> @apply_async_cache(100, cache_type='memory')
+        ... async def my_function():
+        ...     pass
+
+    See Also:
+        :func:`apply_async_memory_cache`
+    """
+
+
 @overload
 def apply_async_cache(
     coro_fn: CoroFn[P, T],
     **modifiers: Unpack[CacheArgs],
-) -> CoroFn[P, T]:...
-    
+) -> CoroFn[P, T]:
+    """Applies an asynchronous cache directly to a coroutine function.
+
+    This overload is used when a coroutine function is provided. The cache is
+    applied directly to the function.
+
+    Args:
+        coro_fn: The coroutine function to be cached.
+        **modifiers: Cache configuration options such as `cache_type`, `cache_typed`, `ram_cache_maxsize`, and `ram_cache_ttl`.
+
+    Examples:
+        >>> async def my_function():
+        ...     pass
+        >>> cached_function = apply_async_cache(my_function, cache_type='memory', ram_cache_maxsize=100)
+
+    See Also:
+        :func:`apply_async_memory_cache`
+    """
+
+
 def apply_async_cache(
     coro_fn: Union[CoroFn[P, T], CacheType, int] = None,
-    cache_type: CacheType = 'memory',
+    cache_type: CacheType = "memory",
     cache_typed: bool = False,
     ram_cache_maxsize: Optional[int] = None,
     ram_cache_ttl: Optional[int] = None,
 ) -> AsyncDecoratorOrCoroFn[P, T]:
-    
+    """Applies an asynchronous cache to a coroutine function.
+
+    This function can be used to apply a cache to a coroutine function, either by passing the function directly or by using it as a decorator. The cache type is currently limited to 'memory'. If an unsupported cache type is specified, a `NotImplementedError` is raised.
+
+    Args:
+        coro_fn: The coroutine function to apply the cache to, or an integer to set as the max size.
+        cache_type: The type of cache to use. Currently, only 'memory' is implemented.
+        cache_typed: Whether to consider types for cache keys.
+        ram_cache_maxsize: The maximum size for the LRU cache. If set to an integer, it overrides coro_fn.
+        ram_cache_ttl: The time-to-live for items in the LRU cache.
+
+    Raises:
+        TypeError: If 'ram_cache_maxsize' is not an integer or None.
+        FunctionNotAsync: If the provided function is not asynchronous.
+        NotImplementedError: If an unsupported cache type is specified.
+
+    Examples:
+        >>> @apply_async_cache(cache_type='memory', ram_cache_maxsize=100)
+        ... async def my_function():
+        ...     pass
+
+        >>> async def my_function():
+        ...     pass
+        >>> cached_function = apply_async_cache(my_function, cache_type='memory', ram_cache_maxsize=100)
+
+        >>> @apply_async_cache(100, cache_type='memory')
+        ... async def another_function():
+        ...     pass
+
+    See Also:
+        :func:`apply_async_memory_cache`
+    """
+
     # Parse Inputs
     if isinstance(coro_fn, int):
         assert ram_cache_maxsize is None
         ram_cache_maxsize = coro_fn
         coro_fn = None
-    
-    # Validate 
+
+    # Validate
     elif coro_fn is None:
         if ram_cache_maxsize is not None and not isinstance(ram_cache_maxsize, int):
-            raise TypeError("'lru_cache_maxsize' must be an integer or None.", ram_cache_maxsize)
+            raise TypeError(
+                "'lru_cache_maxsize' must be an integer or None.", ram_cache_maxsize
+            )
     elif not asyncio.iscoroutinefunction(coro_fn):
         raise exceptions.FunctionNotAsync(coro_fn)
-    
-    if cache_type == 'memory':
-        cache_decorator = apply_async_memory_cache(maxsize=ram_cache_maxsize, ttl=ram_cache_ttl, typed=cache_typed)
+
+    if cache_type == "memory":
+        cache_decorator = apply_async_memory_cache(
+            maxsize=ram_cache_maxsize, ttl=ram_cache_ttl, typed=cache_typed
+        )
         return cache_decorator if coro_fn is None else cache_decorator(coro_fn)
-    elif cache_type == 'disk':
+    elif cache_type == "disk":
         pass
-    raise NotImplementedError(f"cache_type: {cache_type}")
+    raise NotImplementedError(f"cache_type: {cache_type}")

a_sync/a_sync/modifiers/cache/memory.py

@@ -7,34 +7,110 @@ from async_lru import alru_cache
 from a_sync import exceptions
 from a_sync._typing import *
 
+
 class CacheKwargs(TypedDict):
+    """Typed dictionary for cache keyword arguments."""
+
     maxsize: Optional[int]
     ttl: Optional[int]
     typed: bool
 
+
 @overload
-def apply_async_memory_cache(
-    coro_fn: Literal[None],
-    **kwargs: Unpack[CacheKwargs]
-) -> AsyncDecorator[P, T]:...
-    
+def apply_async_memory_cache(**kwargs: Unpack[CacheKwargs]) -> AsyncDecorator[P, T]:
+    """
+    Creates a decorator to apply an asynchronous LRU cache.
+
+    This overload is used when no coroutine function is provided. The returned
+    decorator can be applied to a coroutine function later.
+
+    Args:
+        **kwargs: Keyword arguments for cache configuration, including maxsize,
+            ttl, and typed.
+
+    Examples:
+        >>> @apply_async_memory_cache(maxsize=128, ttl=60)
+        ... async def fetch_data():
+        ...     pass
+
+    See Also:
+        - :func:`alru_cache` for the underlying caching mechanism.
+    """
+
+
 @overload
 def apply_async_memory_cache(
-    coro_fn: int,
-    **kwargs: Unpack[CacheKwargs]
-) -> AsyncDecorator[P, T]:...
-    
+    coro_fn: int, **kwargs: Unpack[CacheKwargs]
+) -> AsyncDecorator[P, T]:
+    """Creates a decorator with maxsize set by an integer.
+
+    This overload is used when an integer is provided as the coroutine function,
+    which sets the maxsize for the cache. The returned decorator can be applied
+    to a coroutine function later.
+
+    Args:
+        coro_fn: An integer to set as maxsize for the cache.
+        **kwargs: Additional keyword arguments for cache configuration, including
+            ttl and typed.
+
+    Examples:
+        >>> # This usage is not supported
+        >>> apply_async_memory_cache(128, ttl=60)
+
+    See Also:
+        - :func:`apply_async_memory_cache` for correct usage.
+    """
+
+
 @overload
 def apply_async_memory_cache(
-    coro_fn: CoroFn[P, T],
-    **kwargs: Unpack[CacheKwargs]
-) -> CoroFn[P, T]:...
+    coro_fn: CoroFn[P, T], **kwargs: Unpack[CacheKwargs]
+) -> CoroFn[P, T]:
+    """
+    Applies an asynchronous LRU cache to a provided coroutine function.
+
+    This overload is used when a coroutine function is provided. The cache is
+    applied directly to the function.
+
+    Args:
+        coro_fn: The coroutine function to be cached.
+        **kwargs: Keyword arguments for cache configuration, including maxsize,
+            ttl, and typed.
+
+    Examples:
+        >>> async def fetch_data():
+        ...     pass
+        >>> cached_fetch = apply_async_memory_cache(fetch_data, maxsize=128, ttl=60)
+
+    See Also:
+        - :func:`alru_cache` for the underlying caching mechanism.
+    """
+
 
 @overload
 def apply_async_memory_cache(
-    coro_fn: Literal[None],
-    **kwargs: Unpack[CacheKwargs]
-) -> AsyncDecorator[P, T]:...
+    coro_fn: Literal[None], **kwargs: Unpack[CacheKwargs]
+) -> AsyncDecorator[P, T]:
+    """
+    Creates a decorator to apply an asynchronous LRU cache.
+
+    This duplicate overload is used when no coroutine function is provided. The
+    returned decorator can be applied to a coroutine function later.
+
+    Args:
+        coro_fn: None, indicating no coroutine function is provided.
+        **kwargs: Keyword arguments for cache configuration, including maxsize,
+            ttl, and typed.
+
+    Examples:
+        >>> @apply_async_memory_cache(maxsize=128, ttl=60)
+        ... async def fetch_data():
+        ...     pass
+
+    See Also:
+        - :func:`alru_cache` for the underlying caching mechanism.
+    """
+
 
 def apply_async_memory_cache(
     coro_fn: Optional[Union[CoroFn[P, T], int]] = None,
@@ -42,19 +118,53 @@ def apply_async_memory_cache(
     ttl: Optional[int] = None,
     typed: bool = False,
 ) -> AsyncDecoratorOrCoroFn[P, T]:
+    """
+    Applies an asynchronous LRU cache to a coroutine function.
+
+    This function uses the `alru_cache` from the `async_lru` library to cache
+    the results of an asynchronous coroutine function. The cache can be configured
+    with a maximum size, a time-to-live (TTL), and whether the cache keys should
+    be typed.
+
+    Args:
+        coro_fn: The coroutine function to be cached, or an integer to set as maxsize.
+        maxsize: The maximum size of the cache. If set to -1, it is converted to None,
+            making the cache unbounded.
+        ttl: The time-to-live for cache entries in seconds. If None, entries do not expire.
+        typed: Whether to consider the types of arguments as part of the cache key.
+
+    Raises:
+        TypeError: If `maxsize` is not a positive integer or None when `coro_fn` is None.
+        exceptions.FunctionNotAsync: If `coro_fn` is not an asynchronous function.
+
+    Examples:
+        >>> @apply_async_memory_cache(maxsize=128, ttl=60)
+        ... async def fetch_data():
+        ...     pass
+
+        >>> async def fetch_data():
+        ...     pass
+        >>> cached_fetch = apply_async_memory_cache(fetch_data, maxsize=128, ttl=60)
+
+    See Also:
+        - :func:`alru_cache` for the underlying caching mechanism.
+    """
     # Parse Inputs
     if isinstance(coro_fn, int):
         assert maxsize is None
         maxsize = coro_fn
         coro_fn = None
-    
-    # Validate 
+
+    # Validate
     elif coro_fn is None:
-        if not (maxsize is None or isinstance(maxsize, int)):
-            raise TypeError("'lru_cache_maxsize' must be a positive integer or None.", maxsize)
+        if maxsize not in [None, -1] and (not isinstance(maxsize, int) or maxsize <= 0):
+            raise TypeError(
+                "'lru_cache_maxsize' must be a positive integer or None.", maxsize
+            )
+
     elif not asyncio.iscoroutinefunction(coro_fn):
         raise exceptions.FunctionNotAsync(coro_fn)
-    
+
     if maxsize == -1:
         maxsize = None
 

a_sync/a_sync/modifiers/limiter.py

@@ -8,48 +8,127 @@ from a_sync import aliases, exceptions
 from a_sync._typing import *
 
 
+LimiterSpec = Union[int, AsyncLimiter]
+
+
 @overload
 def apply_rate_limit(
-    coro_fn: Literal[None],
     runs_per_minute: int,
-) -> AsyncDecorator[P, T]:...
-    
-@overload
-def apply_rate_limit(
-    coro_fn: int,
-    runs_per_minute: Literal[None],
-) -> AsyncDecorator[P, T]:...
-    
+) -> AsyncDecorator[P, T]:
+    """Decorator to apply a rate limit to an asynchronous function.
+
+    This overload allows specifying the number of allowed executions per minute.
+
+    Args:
+        runs_per_minute: The number of allowed executions per minute.
+
+    Examples:
+        Applying a rate limit of 60 executions per minute:
+
+        >>> @apply_rate_limit(60)
+        ... async def my_function():
+        ...     pass
+
+    See Also:
+        :class:`aiolimiter.AsyncLimiter`
+    """
+
+
 @overload
 def apply_rate_limit(
     coro_fn: CoroFn[P, T],
-    runs_per_minute: Union[int, AsyncLimiter],
-) -> CoroFn[P, T]:...
-    
+    runs_per_minute: LimiterSpec,
+) -> CoroFn[P, T]:
+    """Decorator to apply a rate limit to an asynchronous function.
+
+    This overload allows specifying either the number of allowed executions per minute
+    or an :class:`aiolimiter.AsyncLimiter` instance.
+
+    Args:
+        coro_fn: The coroutine function to be rate-limited.
+        runs_per_minute: The number of allowed executions per minute or an :class:`aiolimiter.AsyncLimiter` instance.
+
+    Examples:
+        Using an :class:`aiolimiter.AsyncLimiter` instance:
+
+        >>> async_limiter = AsyncLimiter(60)
+        >>> @apply_rate_limit(async_limiter)
+        ... async def my_function():
+        ...     pass
+
+    See Also:
+        :class:`aiolimiter.AsyncLimiter`
+    """
+
+
 def apply_rate_limit(
     coro_fn: Optional[Union[CoroFn[P, T], int]] = None,
-    runs_per_minute: Optional[Union[int, AsyncLimiter]] = None,
+    runs_per_minute: Optional[LimiterSpec] = None,
 ) -> AsyncDecoratorOrCoroFn[P, T]:
+    """Applies a rate limit to an asynchronous function.
+
+    This function can be used as a decorator to limit the number of times
+    an asynchronous function can be called per minute. It can be configured
+    with either an integer specifying the number of runs per minute or an
+    :class:`aiolimiter.AsyncLimiter` instance.
+
+    Args:
+        coro_fn: The coroutine function to be rate-limited. If an integer is provided, it is treated as runs per minute, and `runs_per_minute` should be None.
+        runs_per_minute: The number of allowed executions per minute or an :class:`aiolimiter.AsyncLimiter` instance. If `coro_fn` is an integer, this should be None.
+
+    Raises:
+        TypeError: If `runs_per_minute` is neither an integer nor an :class:`aiolimiter.AsyncLimiter` when `coro_fn` is None.
+        exceptions.FunctionNotAsync: If `coro_fn` is not an asynchronous function.
+
+    Examples:
+        Applying a rate limit of 60 executions per minute:
+
+        >>> @apply_rate_limit(60)
+        ... async def my_function():
+        ...     pass
+
+        Using an :class:`aiolimiter.AsyncLimiter` instance:
+
+        >>> async_limiter = AsyncLimiter(60)
+        >>> @apply_rate_limit(async_limiter)
+        ... async def my_function():
+        ...     pass
+
+        Specifying the rate limit directly in the decorator:
+
+        >>> @apply_rate_limit
+        ... async def my_function():
+        ...     pass
+
+    See Also:
+        :class:`aiolimiter.AsyncLimiter`
+    """
     # Parse Inputs
-    if isinstance(coro_fn, int):
+    if isinstance(coro_fn, (int, AsyncLimiter)):
         assert runs_per_minute is None
         runs_per_minute = coro_fn
         coro_fn = None
-        
+
     elif coro_fn is None:
-        if runs_per_minute is not None and not isinstance(runs_per_minute, int):
+        if runs_per_minute is not None and not isinstance(
+            runs_per_minute, (int, AsyncLimiter)
+        ):
             raise TypeError("'runs_per_minute' must be an integer.", runs_per_minute)
-        
+
     elif not asyncio.iscoroutinefunction(coro_fn):
         raise exceptions.FunctionNotAsync(coro_fn)
-    
+
     def rate_limit_decorator(coro_fn: CoroFn[P, T]) -> CoroFn[P, T]:
-        limiter = runs_per_minute if isinstance(runs_per_minute, AsyncLimiter) else AsyncLimiter(runs_per_minute) if runs_per_minute else aliases.dummy
+        limiter = (
+            runs_per_minute
+            if isinstance(runs_per_minute, AsyncLimiter)
+            else AsyncLimiter(runs_per_minute) if runs_per_minute else aliases.dummy
+        )
+
         async def rate_limit_wrap(*args: P.args, **kwargs: P.kwargs) -> T:
             async with limiter:  # type: ignore [attr-defined]
                 return await coro_fn(*args, **kwargs)
+
         return rate_limit_wrap
-    
+
     return rate_limit_decorator if coro_fn is None else rate_limit_decorator(coro_fn)
-            
-