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

a_sync/a_sync/modifiers/cache/memory.py

@@ -7,34 +7,76 @@ 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.
+    """
+
+
 @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.
+    """
+
+
 @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.
+    """
+
 
 @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.
+    """
+
 
 def apply_async_memory_cache(
     coro_fn: Optional[Union[CoroFn[P, T], int]] = None,
@@ -42,19 +84,43 @@ 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.
+
+    Returns:
+        A decorator if `coro_fn` is None, otherwise the cached coroutine function.
+    """
     # 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,78 @@ 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.
+
+    Args:
+        runs_per_minute: The number of allowed executions per minute.
+    """
+
+
 @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.
+
+    Args:
+        coro_fn: The coroutine function to be rate-limited.
+        runs_per_minute: The number of allowed executions per minute or an AsyncLimiter instance.
+    """
+
+
 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
+    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 AsyncLimiter instance. If coro_fn is an integer, this should be None.
+
+    Raises:
+        TypeError: If 'runs_per_minute' is neither an integer nor an AsyncLimiter when 'coro_fn' is None.
+        exceptions.FunctionNotAsync: If 'coro_fn' is not an asynchronous function.
+    """
     # 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)
-            
-    

a_sync/a_sync/modifiers/manager.py

@@ -5,9 +5,20 @@ from a_sync._typing import *
 from a_sync.a_sync.config import user_set_default_modifiers, null_modifiers
 from a_sync.a_sync.modifiers import cache, limiter, semaphores
 
-valid_modifiers = [key for key in ModifierKwargs.__annotations__ if not key.startswith('_') and not key.endswith('_')]
+valid_modifiers = [
+    key
+    for key in ModifierKwargs.__annotations__
+    if not key.startswith("_") and not key.endswith("_")
+]
+
 
 class ModifierManager(Dict[str, Any]):
+    """Manages modifiers for asynchronous and synchronous functions.
+
+    This class is responsible for applying modifiers to functions, such as
+    caching, rate limiting, and semaphores for asynchronous functions.
+    """
+
     default: DefaultMode
     cache_type: CacheType
     cache_typed: bool
@@ -17,36 +28,74 @@ class ModifierManager(Dict[str, Any]):
     semaphore: SemaphoreSpec
     # sync modifiers
     executor: Executor
-    __slots__ = "_modifiers", 
+    """This is not applied like a typical modifier. The executor is used to run the sync function in an asynchronous context."""
+
+    __slots__ = ("_modifiers",)
+
     def __init__(self, modifiers: ModifierKwargs) -> None:
+        """Initializes the ModifierManager with the given modifiers.
+
+        Args:
+            modifiers: A dictionary of modifiers to be applied.
+
+        Raises:
+            ValueError: If an unsupported modifier is provided.
+        """
         for key in modifiers.keys():
             if key not in valid_modifiers:
                 raise ValueError(f"'{key}' is not a supported modifier.")
         self._modifiers = modifiers
+
     def __repr__(self) -> str:
+        """Returns a string representation of the modifiers."""
         return str(self._modifiers)
+
     def __getattribute__(self, modifier_key: str) -> Any:
+        """Gets the value of a modifier.
+
+        Args:
+            modifier_key: The key of the modifier to retrieve.
+
+        Returns:
+            The value of the modifier, or the default value if not set.
+        """
         if modifier_key not in valid_modifiers:
             return super().__getattribute__(modifier_key)
-        return self[modifier_key] if modifier_key in self else user_defaults[modifier_key]
+        return (
+            self[modifier_key] if modifier_key in self else user_defaults[modifier_key]
+        )
 
-    
     @property
     def use_limiter(self) -> bool:
+        """Determines if a rate limiter should be used."""
         return self.runs_per_minute != nulls.runs_per_minute
+
     @property
     def use_semaphore(self) -> bool:
+        """Determines if a semaphore should be used."""
         return self.semaphore != nulls.semaphore
+
     @property
     def use_cache(self) -> bool:
-        return any([
-            self.cache_type != nulls.cache_type,
-            self.ram_cache_maxsize != nulls.ram_cache_maxsize,
-            self.ram_cache_ttl != nulls.ram_cache_ttl,
-            self.cache_typed != nulls.cache_typed,
-        ])
-    
+        """Determines if caching should be used."""
+        return any(
+            [
+                self.cache_type != nulls.cache_type,
+                self.ram_cache_maxsize != nulls.ram_cache_maxsize,
+                self.ram_cache_ttl != nulls.ram_cache_ttl,
+                self.cache_typed != nulls.cache_typed,
+            ]
+        )
+
     def apply_async_modifiers(self, coro_fn: CoroFn[P, T]) -> CoroFn[P, T]:
+        """Applies asynchronous modifiers to a coroutine function.
+
+        Args:
+            coro_fn: The coroutine function to modify.
+
+        Returns:
+            The modified coroutine function.
+        """
         # NOTE: THESE STACK IN REVERSE ORDER
         if self.use_limiter:
             coro_fn = limiter.apply_rate_limit(coro_fn, self.runs_per_minute)
@@ -55,35 +104,68 @@ class ModifierManager(Dict[str, Any]):
         if self.use_cache:
             coro_fn = cache.apply_async_cache(
                 coro_fn,
-                cache_type=self.cache_type or 'memory',
+                cache_type=self.cache_type or "memory",
                 cache_typed=self.cache_typed,
                 ram_cache_maxsize=self.ram_cache_maxsize,
-                ram_cache_ttl=self.ram_cache_ttl
+                ram_cache_ttl=self.ram_cache_ttl,
             )
         return coro_fn
-    
+
     def apply_sync_modifiers(self, function: SyncFn[P, T]) -> SyncFn[P, T]:
+        """Wraps a synchronous function.
+
+        Note:
+            There are no sync modifiers at this time, but they will be added here for convenience.
+
+        Args:
+            function: The synchronous function to wrap.
+
+        Returns:
+            The wrapped synchronous function.
+        """
+
         @functools.wraps(function)
         def sync_modifier_wrap(*args: P.args, **kwargs: P.kwargs) -> T:
             return function(*args, **kwargs)
-        # NOTE There are no sync modifiers at this time but they will be added here for my convenience.
+
         return sync_modifier_wrap
-    
+
     # Dictionary api
     def keys(self) -> KeysView[str]:  # type: ignore [override]
+        """Returns the keys of the modifiers."""
         return self._modifiers.keys()
+
     def values(self) -> ValuesView[Any]:  # type: ignore [override]
+        """Returns the values of the modifiers."""
         return self._modifiers.values()
+
     def items(self) -> ItemsView[str, Any]:  # type: ignore [override]
+        """Returns the items of the modifiers."""
         return self._modifiers.items()
+
     def __contains__(self, key: str) -> bool:  # type: ignore [override]
+        """Checks if a key is in the modifiers."""
         return key in self._modifiers
+
     def __iter__(self) -> Iterator[str]:
+        """Returns an iterator over the modifier keys."""
         return self._modifiers.__iter__()
+
     def __len__(self) -> int:
+        """Returns the number of modifiers."""
         return len(self._modifiers)
+
     def __getitem__(self, modifier_key: str):
+        """Gets the value of a modifier by key.
+
+        Args:
+            modifier_key: The key of the modifier to retrieve.
+
+        Returns:
+            The value of the modifier.
+        """
         return self._modifiers[modifier_key]  # type: ignore [literal-required]
 
+
 nulls = ModifierManager(null_modifiers)
 user_defaults = ModifierManager(user_set_default_modifiers)

a_sync/a_sync/modifiers/semaphores.py

@@ -12,58 +12,91 @@ from a_sync.primitives import ThreadsafeSemaphore, DummySemaphore
 
 @overload
 def apply_semaphore(  # type: ignore [misc]
-    coro_fn: Literal[None],
     semaphore: SemaphoreSpec,
-) -> AsyncDecorator[P, T]:...
+) -> AsyncDecorator[P, T]:
+    """Applies a semaphore to a coroutine function.
+
+    This overload is used when the semaphore is provided as a single argument,
+    returning a decorator that can be applied to a coroutine function.
+
+    Args:
+        semaphore: The semaphore to apply, which can be an integer or an asyncio.Semaphore object.
+    """
 
-@overload
-def apply_semaphore(
-    coro_fn: SemaphoreSpec,
-    semaphore: Literal[None],
-) -> AsyncDecorator[P, T]:...
 
 @overload
 def apply_semaphore(
     coro_fn: CoroFn[P, T],
     semaphore: SemaphoreSpec,
-) -> CoroFn[P, T]:...
-    
+) -> CoroFn[P, T]:
+    """Applies a semaphore to a coroutine function.
+
+    This overload is used when both the coroutine function and semaphore are provided,
+    directly applying the semaphore to the coroutine function.
+
+    Args:
+        coro_fn: The coroutine function to which the semaphore will be applied.
+        semaphore: The semaphore to apply, which can be an integer or an asyncio.Semaphore object.
+    """
+
+
 def apply_semaphore(
     coro_fn: Optional[Union[CoroFn[P, T], SemaphoreSpec]] = None,
     semaphore: SemaphoreSpec = None,
 ) -> AsyncDecoratorOrCoroFn[P, T]:
+    """Applies a semaphore to a coroutine function or returns a decorator.
+
+    This function can be used to apply a semaphore to a coroutine function either by
+    passing the coroutine function and semaphore as arguments or by using the semaphore
+    as a decorator. It raises exceptions if the inputs are not valid.
+
+    Args:
+        coro_fn: The coroutine function to which the semaphore will be applied, or None
+            if the semaphore is to be used as a decorator.
+        semaphore: The semaphore to apply, which can be an integer or an asyncio.Semaphore object.
+
+    Raises:
+        ValueError: If both coro_fn and semaphore are provided as invalid inputs.
+        exceptions.FunctionNotAsync: If the provided function is not a coroutine.
+        TypeError: If the semaphore is not an integer or an asyncio.Semaphore object.
+    """
     # Parse Inputs
     if isinstance(coro_fn, (int, asyncio.Semaphore)):
         if semaphore is not None:
             raise ValueError("You can only pass in one arg.")
         semaphore = coro_fn
         coro_fn = None
-        
+
     elif not asyncio.iscoroutinefunction(coro_fn):
         raise exceptions.FunctionNotAsync(coro_fn)
-        
+
     # Create the semaphore if necessary
     if isinstance(semaphore, int):
         semaphore = primitives.ThreadsafeSemaphore(semaphore)
     elif not isinstance(semaphore, asyncio.Semaphore):
-        raise TypeError(f"'semaphore' must either be an integer or a Semaphore object. You passed {semaphore}")
-    
+        raise TypeError(
+            f"'semaphore' must either be an integer or a Semaphore object. You passed {semaphore}"
+        )
+
     # Create and return the decorator
     if isinstance(semaphore, primitives.Semaphore):
         # NOTE: Our `Semaphore` primitive can be used as a decorator.
         #       While you can use it the `async with` way like any other semaphore and we could make this code section cleaner,
         #       applying it as a decorator adds some useful info to its debug logs so we do that here if we can.
         semaphore_decorator = semaphore
-    
+
     else:
+
         def semaphore_decorator(coro_fn: CoroFn[P, T]) -> CoroFn[P, T]:
             @functools.wraps(coro_fn)
             async def semaphore_wrap(*args, **kwargs) -> T:
                 async with semaphore:  # type: ignore [union-attr]
                     return await coro_fn(*args, **kwargs)
+
             return semaphore_wrap
-        
+
     return semaphore_decorator if coro_fn is None else semaphore_decorator(coro_fn)
 
 
 dummy_semaphore = primitives.DummySemaphore()
+"""A dummy semaphore that does not enforce any concurrency limits."""