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

a_sync/a_sync/modifiers/manager.py

@@ -5,9 +5,47 @@ 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('_')]
+# TODO give me a docstring
+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. It also
+    handles synchronous functions, although no sync modifiers are currently
+    implemented.
+
+    Examples:
+        Creating a ModifierManager with specific modifiers:
+
+        >>> modifiers = ModifierKwargs(cache_type='memory', runs_per_minute=60)
+        >>> manager = ModifierManager(modifiers)
+
+        Applying modifiers to an asynchronous function:
+
+        >>> async def my_coro():
+        ...     pass
+        >>> modified_coro = manager.apply_async_modifiers(my_coro)
+
+        Applying modifiers to a synchronous function (no sync modifiers applied):
+
+        >>> def my_function():
+        ...     pass
+        >>> modified_function = manager.apply_sync_modifiers(my_function)
+
+    See Also:
+        - :class:`a_sync.a_sync.modifiers.cache`
+        - :class:`a_sync.a_sync.modifiers.limiter`
+        - :class:`a_sync.a_sync.modifiers.semaphores`
+    """
+
+    # TODO give us docstrings
     default: DefaultMode
     cache_type: CacheType
     cache_typed: bool
@@ -15,38 +53,86 @@ class ModifierManager(Dict[str, Any]):
     ram_cache_ttl: Optional[int]
     runs_per_minute: Optional[int]
     semaphore: SemaphoreSpec
+
     # sync modifiers
     executor: Executor
-    __slots__ = "_modifiers", 
+    """
+    This is not applied like a typical modifier but is still passed through the library with them for convenience. 
+    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.
+
+        Examples:
+            >>> async def my_coro():
+            ...     pass
+            >>> manager = ModifierManager(ModifierKwargs(runs_per_minute=60))
+            >>> modified_coro = manager.apply_async_modifiers(my_coro)
+        """
         # NOTE: THESE STACK IN REVERSE ORDER
         if self.use_limiter:
             coro_fn = limiter.apply_rate_limit(coro_fn, self.runs_per_minute)
@@ -55,35 +141,75 @@ 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.
+
+        Examples:
+            >>> def my_function():
+            ...     pass
+            >>> manager = ModifierManager(ModifierKwargs())
+            >>> modified_function = manager.apply_sync_modifiers(my_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]
 
+
+# TODO give us docstrings
 nulls = ModifierManager(null_modifiers)
 user_defaults = ModifierManager(user_set_default_modifiers)

a_sync/a_sync/modifiers/semaphores.py

@@ -12,58 +12,164 @@ 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]:
+    """Create a decorator to apply 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 (Union[int, asyncio.Semaphore, primitives.Semaphore]):
+            The semaphore to apply, which can be an integer, an `asyncio.Semaphore`, or a `primitives.Semaphore`.
+
+    Examples:
+        Using as a decorator with an integer semaphore:
+        >>> @apply_semaphore(2)
+        ... async def limited_concurrent_function():
+        ...     pass
+
+        Using as a decorator with an `asyncio.Semaphore`:
+        >>> sem = asyncio.Semaphore(2)
+        >>> @apply_semaphore(sem)
+        ... async def another_function():
+        ...     pass
+
+        Using as a decorator with a `primitives.Semaphore`:
+        >>> sem = primitives.ThreadsafeSemaphore(2)
+        >>> @apply_semaphore(sem)
+        ... async def yet_another_function():
+        ...     pass
+
+    See Also:
+        - :class:`asyncio.Semaphore`
+        - :class:`primitives.Semaphore`
+
+    Note:
+        `primitives.Semaphore` is a subclass of `asyncio.Semaphore`. Therefore, when the documentation refers to `asyncio.Semaphore`, it also includes `primitives.Semaphore` and any other subclasses.
+    """
 
-@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]:
+    """Apply a semaphore directly 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 (Callable): The coroutine function to which the semaphore will be applied.
+        semaphore (Union[int, asyncio.Semaphore, primitives.Semaphore]):
+            The semaphore to apply, which can be an integer, an `asyncio.Semaphore`, or a `primitives.Semaphore`.
+
+    Examples:
+        Applying directly to a function with an integer semaphore:
+        >>> async def my_coroutine():
+        ...     pass
+        >>> my_coroutine = apply_semaphore(my_coroutine, 3)
+
+        Applying directly with an `asyncio.Semaphore`:
+        >>> sem = asyncio.Semaphore(3)
+        >>> my_coroutine = apply_semaphore(my_coroutine, sem)
+
+        Applying directly with a `primitives.Semaphore`:
+        >>> sem = primitives.ThreadsafeSemaphore(3)
+        >>> my_coroutine = apply_semaphore(my_coroutine, sem)
+
+    See Also:
+        - :class:`asyncio.Semaphore`
+        - :class:`primitives.Semaphore`
+
+    Note:
+        `primitives.Semaphore` is a subclass of `asyncio.Semaphore`. Therefore, when the documentation refers to `asyncio.Semaphore`, it also includes `primitives.Semaphore` and any other subclasses.
+    """
+
+
 def apply_semaphore(
     coro_fn: Optional[Union[CoroFn[P, T], SemaphoreSpec]] = None,
     semaphore: SemaphoreSpec = None,
 ) -> AsyncDecoratorOrCoroFn[P, T]:
+    """Apply a semaphore to a coroutine function or return 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 (Optional[Callable]): The coroutine function to which the semaphore will be applied,
+            or None if the semaphore is to be used as a decorator.
+        semaphore (Union[int, asyncio.Semaphore, primitives.Semaphore]):
+            The semaphore to apply, which can be an integer, an `asyncio.Semaphore`, or a `primitives.Semaphore`.
+
+    Raises:
+        ValueError: If both `coro_fn` and `semaphore` are provided and the first argument is an integer or `asyncio.Semaphore`.
+        exceptions.FunctionNotAsync: If the provided function is not a coroutine.
+        TypeError: If the semaphore is not an integer, an `asyncio.Semaphore`, or a `primitives.Semaphore`.
+
+    Examples:
+        Using as a decorator:
+        >>> @apply_semaphore(2)
+        ... async def limited_concurrent_function():
+        ...     pass
+
+        Applying directly to a function:
+        >>> async def my_coroutine():
+        ...     pass
+        >>> my_coroutine = apply_semaphore(my_coroutine, 3)
+
+        Handling invalid inputs:
+        >>> try:
+        ...     apply_semaphore(3, 2)
+        ... except ValueError as e:
+        ...     print(e)
+
+    See Also:
+        - :class:`asyncio.Semaphore`
+        - :class:`primitives.Semaphore`
+
+    Note:
+        `primitives.Semaphore` is a subclass of `asyncio.Semaphore`. Therefore, when the documentation refers to `asyncio.Semaphore`, it also includes `primitives.Semaphore` and any other subclasses.
+    """
     # 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."""