ez-a-sync 0.33.4__cp313-cp313-musllinux_1_2_i686.whl

a_sync/a_sync/modifiers/__init__.pxd

@@ -0,0 +1 @@
+from a_sync.a_sync.modifiers.manager cimport ModifierManager

a_sync/a_sync/modifiers/__init__.py

@@ -0,0 +1,101 @@
+"""
+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 typing import Union
+
+from aiolimiter import AsyncLimiter
+
+from a_sync._typing import ModifierKwargs
+from a_sync.a_sync.modifiers.manager import valid_modifiers
+from a_sync.primitives.locks import ThreadsafeSemaphore
+
+
+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):
+    """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

@@ -0,0 +1,160 @@
+# mypy: disable-error-code=valid-type
+# mypy: disable-error-code=misc
+from asyncio import iscoroutinefunction
+from typing import Optional, TypedDict, Union, overload
+
+from typing_extensions import Unpack
+
+from a_sync import exceptions
+from a_sync._typing import AsyncDecorator, AsyncDecoratorOrCoroFn, CoroFn, P, T, CacheType
+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(
+    **modifiers: Unpack[CacheArgs],
+) -> 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]:
+    """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]:
+    """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_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
+    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)
+    elif not 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
+        )
+        return cache_decorator if coro_fn is None else cache_decorator(coro_fn)
+    elif cache_type == "disk":
+        pass
+    raise NotImplementedError(f"cache_type: {cache_type}")

a_sync/a_sync/modifiers/cache/memory.py

@@ -0,0 +1,165 @@
+# mypy: disable-error-code=valid-type
+# mypy: disable-error-code=misc
+
+from async_lru import alru_cache
+
+from a_sync._typing import *
+from a_sync.exceptions import FunctionNotAsync
+
+
+class CacheKwargs(TypedDict):
+    """Typed dictionary for cache keyword arguments."""
+
+    maxsize: Optional[int]
+    ttl: Optional[int]
+    typed: bool
+
+
+@overload
+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]:
+    """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]:
+    """
+    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]:
+    """
+    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,
+    maxsize: Optional[int] = None,
+    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
+    elif coro_fn is None:
+        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 iscoroutinefunction(coro_fn):
+        raise FunctionNotAsync(coro_fn)
+
+    if maxsize == -1:
+        maxsize = None
+
+    cache_decorator = alru_cache(maxsize=maxsize, ttl=ttl, typed=typed)
+    return cache_decorator if coro_fn is None else cache_decorator(coro_fn)

a_sync/a_sync/modifiers/limiter.py

@@ -0,0 +1,132 @@
+# mypy: disable-error-code=valid-type
+# mypy: disable-error-code=misc
+from asyncio import iscoroutinefunction
+
+from aiolimiter import AsyncLimiter
+
+from a_sync import aliases, exceptions
+from a_sync._typing import *
+
+
+LimiterSpec = Union[int, AsyncLimiter]
+
+
+@overload
+def apply_rate_limit(
+    runs_per_minute: int,
+) -> 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: 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[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, 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, AsyncLimiter)):
+            raise TypeError("'runs_per_minute' must be an integer.", runs_per_minute)
+
+    elif not 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
+        )
+
+        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)