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

a_sync/a_sync/singleton.py

@@ -1,6 +1,7 @@
 from a_sync.a_sync._meta import ASyncSingletonMeta
 from a_sync.a_sync.base import ASyncGenericBase
 
+
 class ASyncGenericSingleton(ASyncGenericBase, metaclass=ASyncSingletonMeta):
     """
     A base class for creating singleton-esque ASync classes.

a_sync/aliases.py

@@ -1,4 +1,3 @@
-
 from a_sync.a_sync.modifiers.semaphores import dummy_semaphore as dummy
 from a_sync.a_sync.property import a_sync_cached_property as cached_property
 from a_sync.a_sync.property import a_sync_property as property

a_sync/asyncio/__init__.py

@@ -1,5 +1,8 @@
 """
-This package contains buffed versions of the objects found in the builtin `asyncio` package.
+This package provides custom utilities and extensions to the builtin `asyncio` package.
+
+These utilities include enhanced versions of common asyncio functions, offering additional
+features and improved functionality for asynchronous programming.
 """
 
 from a_sync.asyncio.as_completed import as_completed

a_sync/asyncio/as_completed.py

@@ -7,26 +7,65 @@ import asyncio
 try:
     from tqdm.asyncio import tqdm_asyncio
 except ImportError as e:
+
     class tqdm_asyncio:  # type: ignore [no-redef]
         def as_completed(*args, **kwargs):
             raise ImportError("You must have tqdm installed to use this feature")
-        
+
+
 from a_sync._typing import *
 from a_sync.iter import ASyncIterator
 
+
 @overload
-def as_completed(fs: Iterable[Awaitable[T]], *, timeout: Optional[float] = None, return_exceptions: bool = False, aiter: Literal[False] = False, tqdm: bool = False, **tqdm_kwargs: Any) -> Iterator[Coroutine[Any, Any, T]]:
-    ...
+def as_completed(
+    fs: Iterable[Awaitable[T]],
+    *,
+    timeout: Optional[float] = None,
+    return_exceptions: bool = False,
+    aiter: Literal[False] = False,
+    tqdm: bool = False,
+    **tqdm_kwargs: Any
+) -> Iterator[Coroutine[Any, Any, T]]: ...
 @overload
-def as_completed(fs: Iterable[Awaitable[T]], *, timeout: Optional[float] = None, return_exceptions: bool = False, aiter: Literal[True] = True, tqdm: bool = False, **tqdm_kwargs: Any) -> ASyncIterator[T]:
-    ...
+def as_completed(
+    fs: Iterable[Awaitable[T]],
+    *,
+    timeout: Optional[float] = None,
+    return_exceptions: bool = False,
+    aiter: Literal[True] = True,
+    tqdm: bool = False,
+    **tqdm_kwargs: Any
+) -> ASyncIterator[T]: ...
 @overload
-def as_completed(fs: Mapping[K, Awaitable[V]], *, timeout: Optional[float] = None, return_exceptions: bool = False, aiter: Literal[False] = False, tqdm: bool = False, **tqdm_kwargs: Any) -> Iterator[Coroutine[Any, Any, Tuple[K, V]]]:
-    ...
+def as_completed(
+    fs: Mapping[K, Awaitable[V]],
+    *,
+    timeout: Optional[float] = None,
+    return_exceptions: bool = False,
+    aiter: Literal[False] = False,
+    tqdm: bool = False,
+    **tqdm_kwargs: Any
+) -> Iterator[Coroutine[Any, Any, Tuple[K, V]]]: ...
 @overload
-def as_completed(fs: Mapping[K, Awaitable[V]], *, timeout: Optional[float] = None, return_exceptions: bool = False, aiter: Literal[True] = True, tqdm: bool = False, **tqdm_kwargs: Any) -> ASyncIterator[Tuple[K, V]]:
-    ...
-def as_completed(fs, *, timeout: Optional[float] = None, return_exceptions: bool = False, aiter: bool = False, tqdm: bool = False, **tqdm_kwargs: Any):
+def as_completed(
+    fs: Mapping[K, Awaitable[V]],
+    *,
+    timeout: Optional[float] = None,
+    return_exceptions: bool = False,
+    aiter: Literal[True] = True,
+    tqdm: bool = False,
+    **tqdm_kwargs: Any
+) -> ASyncIterator[Tuple[K, V]]: ...
+def as_completed(
+    fs,
+    *,
+    timeout: Optional[float] = None,
+    return_exceptions: bool = False,
+    aiter: bool = False,
+    tqdm: bool = False,
+    **tqdm_kwargs: Any
+):
     """
     Concurrently awaits a list of awaitable objects or mappings of awaitables and returns an iterator of results.
 
@@ -39,16 +78,13 @@ def as_completed(fs, *, timeout: Optional[float] = None, return_exceptions: bool
     - Provides progress reporting using tqdm if 'tqdm' is set to True.
 
     Args:
-        fs (Iterable[Awaitable[T] or Mapping[K, Awaitable[V]]]): The awaitables to await concurrently. It can be a list of individual awaitables or a mapping of awaitables.
-        timeout (float, optional): The maximum time, in seconds, to wait for the completion of awaitables. Defaults to None (no timeout).
-        return_exceptions (bool, optional): If True, exceptions are returned as results instead of raising them. Defaults to False.
-        aiter (bool, optional): If True, returns an async iterator of results. Defaults to False.
-        tqdm (bool, optional): If True, enables progress reporting using tqdm. Defaults to False.
+        fs: The awaitables to await concurrently. It can be a list of individual awaitables or a mapping of awaitables.
+        timeout: The maximum time, in seconds, to wait for the completion of awaitables. Defaults to None (no timeout).
+        return_exceptions: If True, exceptions are returned as results instead of raising them. Defaults to False. Note: This parameter is not currently implemented in the function logic.
+        aiter: If True, returns an async iterator of results. Defaults to False.
+        tqdm: If True, enables progress reporting using tqdm. Defaults to False.
         **tqdm_kwargs: Additional keyword arguments for tqdm if progress reporting is enabled.
 
-    Returns:
-        Iterator[Coroutine[Any, Any, T] or ASyncIterator[Tuple[K, V]]]: An iterator of results when awaiting individual awaitables or an async iterator when awaiting mappings.
-
     Examples:
         Awaiting individual awaitables:
         ```
@@ -56,85 +92,176 @@ def as_completed(fs, *, timeout: Optional[float] = None, return_exceptions: bool
         for coro in as_completed(awaitables):
             val = await coro
             ...
-            
+
         async for val in as_completed(awaitables, aiter=True):
             ...
         ```
-        
+
         Awaiting mappings of awaitables:
         ```
         mapping = {'key1': async_function1(), 'key2': async_function2()}
-        
+
         for coro in as_completed(mapping):
             k, v = await coro
             ...
-            
+
         async for k, v in as_completed(mapping, aiter=True):
             ...
         ```
     """
     if isinstance(fs, Mapping):
-        return as_completed_mapping(fs, timeout=timeout, return_exceptions=return_exceptions, aiter=aiter, tqdm=tqdm, **tqdm_kwargs) 
+        return as_completed_mapping(
+            fs,
+            timeout=timeout,
+            return_exceptions=return_exceptions,
+            aiter=aiter,
+            tqdm=tqdm,
+            **tqdm_kwargs
+        )
     if return_exceptions:
         fs = [_exc_wrap(f) for f in fs]
     return (
-        ASyncIterator(__yield_as_completed(fs, timeout=timeout, tqdm=tqdm, **tqdm_kwargs)) if aiter 
-        else tqdm_asyncio.as_completed(fs, timeout=timeout, **tqdm_kwargs) if tqdm 
-        else asyncio.as_completed(fs, timeout=timeout)
+        ASyncIterator(
+            __yield_as_completed(fs, timeout=timeout, tqdm=tqdm, **tqdm_kwargs)
+        )
+        if aiter
+        else (
+            tqdm_asyncio.as_completed(fs, timeout=timeout, **tqdm_kwargs)
+            if tqdm
+            else asyncio.as_completed(fs, timeout=timeout)
+        )
     )
 
+
 @overload
-def as_completed_mapping(mapping: Mapping[K, Awaitable[V]], *, timeout: Optional[float] = None, return_exceptions: bool = False, aiter: Literal[True] = True, tqdm: bool = False, **tqdm_kwargs: Any) -> ASyncIterator[Tuple[K, V]]:
-    ...
+def as_completed_mapping(
+    mapping: Mapping[K, Awaitable[V]],
+    *,
+    timeout: Optional[float] = None,
+    return_exceptions: bool = False,
+    aiter: Literal[True] = True,
+    tqdm: bool = False,
+    **tqdm_kwargs: Any
+) -> ASyncIterator[Tuple[K, V]]: ...
 @overload
-def as_completed_mapping(mapping: Mapping[K, Awaitable[V]], *, timeout: Optional[float] = None, return_exceptions: bool = False, aiter: Literal[False] = False, tqdm: bool = False, **tqdm_kwargs: Any) -> Iterator[Coroutine[Any, Any, Tuple[K, V]]]:
-    ...
-def as_completed_mapping(mapping: Mapping[K, Awaitable[V]], *, timeout: Optional[float] = None, return_exceptions: bool = False, aiter: bool = False, tqdm: bool = False, **tqdm_kwargs: Any) -> Union[Iterator[Coroutine[Any, Any, Tuple[K, V]]], ASyncIterator[Tuple[K, V]]]:
+def as_completed_mapping(
+    mapping: Mapping[K, Awaitable[V]],
+    *,
+    timeout: Optional[float] = None,
+    return_exceptions: bool = False,
+    aiter: Literal[False] = False,
+    tqdm: bool = False,
+    **tqdm_kwargs: Any
+) -> Iterator[Coroutine[Any, Any, Tuple[K, V]]]: ...
+def as_completed_mapping(
+    mapping: Mapping[K, Awaitable[V]],
+    *,
+    timeout: Optional[float] = None,
+    return_exceptions: bool = False,
+    aiter: bool = False,
+    tqdm: bool = False,
+    **tqdm_kwargs: Any
+) -> Union[Iterator[Coroutine[Any, Any, Tuple[K, V]]], ASyncIterator[Tuple[K, V]]]:
     """
     Concurrently awaits a mapping of awaitable objects and returns an iterator or async iterator of results.
 
     This function is designed to await a mapping of awaitable objects, where each key-value pair represents a unique awaitable. It enables concurrent execution and gathers results into an iterator or an async iterator.
 
     Args:
-        mapping (Mapping[K, Awaitable[V]]): A dictionary-like object where keys are of type K and values are awaitable objects of type V.
-        timeout (float, optional): The maximum time, in seconds, to wait for the completion of awaitables. Defaults to None (no timeout).
-        return_exceptions (bool, optional): If True, exceptions are returned as results instead of raising them. Defaults to False.
-        aiter (bool, optional): If True, returns an async iterator of results. Defaults to False.
-        tqdm (bool, optional): If True, enables progress reporting using tqdm. Defaults to False.
+        mapping: A dictionary-like object where keys are of type K and values are awaitable objects of type V.
+        timeout: The maximum time, in seconds, to wait for the completion of awaitables. Defaults to None (no timeout).
+        return_exceptions: If True, exceptions are returned as results instead of raising them. Defaults to False.
+        aiter: If True, returns an async iterator of results. Defaults to False.
+        tqdm: If True, enables progress reporting using tqdm. Defaults to False.
         **tqdm_kwargs: Additional keyword arguments for tqdm if progress reporting is enabled.
 
-    Returns:
-        Union[Iterator[Coroutine[Any, Any, Tuple[K, V]]] or ASyncIterator[Tuple[K, V]]]: An iterator of results or an async iterator when awaiting mappings.
-
     Example:
         ```
         mapping = {'key1': async_function1(), 'key2': async_function2()}
-        
+
         for coro in as_completed_mapping(mapping):
             k, v = await coro
             ...
-            
+
         async for k, v in as_completed_mapping(mapping, aiter=True):
             ...
         ```
     """
-    return as_completed([__mapping_wrap(k, v, return_exceptions=return_exceptions) for k, v in mapping.items()], timeout=timeout, aiter=aiter, tqdm=tqdm, **tqdm_kwargs)
+    return as_completed(
+        [
+            __mapping_wrap(k, v, return_exceptions=return_exceptions)
+            for k, v in mapping.items()
+        ],
+        timeout=timeout,
+        aiter=aiter,
+        tqdm=tqdm,
+        **tqdm_kwargs
+    )
+
 
 async def _exc_wrap(awaitable: Awaitable[T]) -> Union[T, Exception]:
+    """Wraps an awaitable to catch exceptions and return them instead of raising.
+
+    Args:
+        awaitable: The awaitable to wrap.
+
+    Returns:
+        The result of the awaitable or the exception if one is raised.
+    """
     try:
         return await awaitable
     except Exception as e:
         return e
-    
-async def __yield_as_completed(futs: Iterable[Awaitable[T]], *, timeout: Optional[float] = None, return_exceptions: bool = False, tqdm: bool = False, **tqdm_kwargs: Any) -> AsyncIterator[T]:
-    for fut in as_completed(futs, timeout=timeout, return_exceptions=return_exceptions, tqdm=tqdm, **tqdm_kwargs):
+
+
+async def __yield_as_completed(
+    futs: Iterable[Awaitable[T]],
+    *,
+    timeout: Optional[float] = None,
+    return_exceptions: bool = False,
+    tqdm: bool = False,
+    **tqdm_kwargs: Any
+) -> AsyncIterator[T]:
+    """Yields results from awaitables as they complete.
+
+    Args:
+        futs: The awaitables to await.
+        timeout: The maximum time, in seconds, to wait for the completion of awaitables. Defaults to None (no timeout).
+        return_exceptions: If True, exceptions are returned as results instead of raising them. Defaults to False.
+        tqdm: If True, enables progress reporting using tqdm. Defaults to False.
+        **tqdm_kwargs: Additional keyword arguments for tqdm if progress reporting is enabled.
+    """
+    for fut in as_completed(
+        futs,
+        timeout=timeout,
+        return_exceptions=return_exceptions,
+        tqdm=tqdm,
+        **tqdm_kwargs
+    ):
         yield await fut
 
+
 @overload
-async def __mapping_wrap(k: K, v: Awaitable[V], return_exceptions: Literal[True] = True) -> Union[V, Exception]:...
+async def __mapping_wrap(
+    k: K, v: Awaitable[V], return_exceptions: Literal[True] = True
+) -> Union[V, Exception]: ...
 @overload
-async def __mapping_wrap(k: K, v: Awaitable[V], return_exceptions: Literal[False] = False) -> V:...
-async def __mapping_wrap(k: K, v: Awaitable[V], return_exceptions: bool = False) -> Union[V, Exception]:
+async def __mapping_wrap(
+    k: K, v: Awaitable[V], return_exceptions: Literal[False] = False
+) -> V: ...
+async def __mapping_wrap(
+    k: K, v: Awaitable[V], return_exceptions: bool = False
+) -> Union[V, Exception]:
+    """Wraps a key-value pair of awaitable to catch exceptions and return them with the key.
+
+    Args:
+        k: The key associated with the awaitable.
+        v: The awaitable to wrap.
+        return_exceptions: If True, exceptions are returned as results instead of raising them. Defaults to False.
+
+    Returns:
+        A tuple of the key and the result of the awaitable or the exception if one is raised.
+    """
     try:
         return k, await v
     except Exception as e:
@@ -142,4 +269,5 @@ async def __mapping_wrap(k: K, v: Awaitable[V], return_exceptions: bool = False)
             return k, e
         raise
 
-__all__ = ["as_completed", "as_completed_mapping"]
+
+__all__ = ["as_completed", "as_completed_mapping"]

a_sync/asyncio/create_task.py

@@ -12,24 +12,26 @@ from a_sync._typing import *
 
 logger = logging.getLogger(__name__)
 
+
 def create_task(
-    coro: Awaitable[T], 
-    *, 
-    name: Optional[str] = None, 
+    coro: Awaitable[T],
+    *,
+    name: Optional[str] = None,
     skip_gc_until_done: bool = False,
     log_destroy_pending: bool = True,
 ) -> "asyncio.Task[T]":
     """
     Extends asyncio.create_task to support any Awaitable, manage task lifecycle, and enhance error handling.
 
-    Unlike asyncio.create_task, which requires a coroutine, this function accepts any Awaitable, ensuring broader
-    compatibility. It optionally prevents the task from being garbage-collected until completion and provides
-    enhanced error management by wrapping exceptions in a custom exception.
+    This function accepts any Awaitable, ensuring broader compatibility. If the Awaitable is not a coroutine,
+    it attempts to convert it to one. It optionally prevents the task from being garbage-collected until completion
+    and provides enhanced error management by wrapping exceptions in a custom exception when skip_gc_until_done is True.
 
     Args:
-        coro: An Awaitable object from which to create the task.
+        coro: An Awaitable object from which to create the task. If not a coroutine, it will be converted.
         name: Optional name for the task, aiding in debugging.
         skip_gc_until_done: If True, the task is kept alive until it completes, preventing garbage collection.
+                            Exceptions are wrapped in PersistedTaskException for special handling.
         log_destroy_pending: If False, asyncio's default error log when a pending task is destroyed is suppressed.
 
     Returns:
@@ -50,8 +52,16 @@ def create_task(
 
 __persisted_tasks: Set["asyncio.Task[Any]"] = set()
 
+
 async def __await(awaitable: Awaitable[T]) -> T:
-    """Wait for the completion of an Awaitable."""
+    """Wait for the completion of an Awaitable.
+
+    Args:
+        awaitable: The Awaitable object to wait for.
+
+    Raises:
+        RuntimeError: If a RuntimeError occurs during the await, it is raised with additional context.
+    """
     try:
         return await awaitable
     except RuntimeError as e:
@@ -60,26 +70,33 @@ async def __await(awaitable: Awaitable[T]) -> T:
             args.append(awaitable._children)
         raise RuntimeError(*args) from None
 
+
 def __prune_persisted_tasks():
-    """Remove completed tasks from the set of persisted tasks."""
+    """Remove completed tasks from the set of persisted tasks.
+
+    This function checks each task in the persisted tasks set. If a task is done and has an exception,
+    it logs the exception and raises it if it's not a PersistedTaskException. It also logs the traceback
+    manually since the usual handler will not run after retrieving the exception.
+    """
     for task in tuple(__persisted_tasks):
         if task.done() and (e := task.exception()):
             # force exceptions related to this lib to bubble up
             if not isinstance(e, exceptions.PersistedTaskException):
                 logger.exception(e)
                 raise e
-            # we have to manually log the traceback that asyncio would usually log 
+            # we have to manually log the traceback that asyncio would usually log
             # since we already got the exception from the task and the usual handler will now not run
             context = {
-                'message': f'{task.__class__.__name__} exception was never retrieved',
-                'exception': e,
-                'future': task,
+                "message": f"{task.__class__.__name__} exception was never retrieved",
+                "exception": e,
+                "future": task,
             }
             if task._source_traceback:
-                context['source_traceback'] = task._source_traceback
+                context["source_traceback"] = task._source_traceback
             task._loop.call_exception_handler(context)
             __persisted_tasks.discard(task)
 
+
 async def __persisted_task_exc_wrap(task: "asyncio.Task[T]") -> T:
     """
     Wrap a task to handle its exception in a specialized manner.
@@ -87,9 +104,6 @@ async def __persisted_task_exc_wrap(task: "asyncio.Task[T]") -> T:
     Args:
         task: The asyncio Task to wrap.
 
-    Returns:
-        The result of the task, if successful.
-
     Raises:
         PersistedTaskException: Wraps any exception raised by the task for special handling.
     """

a_sync/asyncio/gather.py

@@ -3,15 +3,18 @@ This module provides an enhanced version of :func:`asyncio.gather`.
 """
 
 import asyncio
-from typing import (Any, Awaitable, Dict, List, Mapping, TypeVar, Union,
-                    overload)
+from typing import Any, Awaitable, Dict, List, Mapping, TypeVar, Union, overload
 
 try:
     from tqdm.asyncio import tqdm_asyncio
 except ImportError as e:
+
     class tqdm_asyncio:  # type: ignore [no-redef]
         async def gather(*args, **kwargs):
-            raise ImportError("You must have tqdm installed in order to use this feature")
+            raise ImportError(
+                "You must have tqdm installed in order to use this feature"
+            )
+
 
 from a_sync._typing import *
 from a_sync.asyncio.as_completed import as_completed_mapping, _exc_wrap
@@ -19,87 +22,99 @@ from a_sync.asyncio.as_completed import as_completed_mapping, _exc_wrap
 
 Excluder = Callable[[T], bool]
 
+
 @overload
 async def gather(
-    *awaitables: Mapping[K, Awaitable[V]], 
-    return_exceptions: bool = False, 
-    exclude_if: Optional[Excluder[V]] = None, 
-    tqdm: bool = False, 
+    *awaitables: Mapping[K, Awaitable[V]],
+    return_exceptions: bool = False,
+    exclude_if: Optional[Excluder[V]] = None,
+    tqdm: bool = False,
     **tqdm_kwargs: Any,
-) -> Dict[K, V]:
-    ...
+) -> Dict[K, V]: ...
 @overload
 async def gather(
-    *awaitables: Awaitable[T], 
-    return_exceptions: bool = False, 
+    *awaitables: Awaitable[T],
+    return_exceptions: bool = False,
     exclude_if: Optional[Excluder[T]] = None,
     tqdm: bool = False,
     **tqdm_kwargs: Any,
-) -> List[T]:
-    ...
+) -> List[T]: ...
 async def gather(
-    *awaitables: Union[Awaitable[T], Mapping[K, Awaitable[V]]], 
-    return_exceptions: bool = False, 
-    exclude_if: Optional[Excluder[T]] = None, 
-    tqdm: bool = False, 
+    *awaitables: Union[Awaitable[T], Mapping[K, Awaitable[V]]],
+    return_exceptions: bool = False,
+    exclude_if: Optional[Excluder[T]] = None,
+    tqdm: bool = False,
     **tqdm_kwargs: Any,
 ) -> Union[List[T], Dict[K, V]]:
     """
-    Concurrently awaits a list of awaitable objects or mappings of awaitables and returns the results.
+    Concurrently awaits a list of awaitable objects or a mapping of awaitables and returns the results.
 
-    This function extends Python's asyncio.gather, providing additional features for mixed use cases of individual awaitable objects and mappings of awaitables.
+    This function extends Python's asyncio.gather, providing additional features for handling either individual awaitable objects or a mapping of awaitables.
 
     Differences from asyncio.gather:
     - Uses type hints for use with static type checkers.
     - Supports gathering either individual awaitables or a k:v mapping of awaitables.
     - Provides progress reporting using tqdm if 'tqdm' is set to True.
-    
+    - Allows exclusion of results based on a condition using the 'exclude_if' parameter.
+
     Args:
-        *awaitables: The awaitables to await concurrently. It can be a single awaitable or a mapping of awaitables.
-        return_exceptions (optional): If True, exceptions are returned as results instead of raising them. Defaults to False.
-        tqdm (optional): If True, enables progress reporting using tqdm. Defaults to False.
+        *awaitables: The awaitables to await concurrently. It can be a list of individual awaitables or a mapping of awaitables.
+        return_exceptions: If True, exceptions are returned as results instead of raising them. Defaults to False.
+        exclude_if: A callable that takes a result and returns True if the result should be excluded from the final output. Defaults to None.
+        tqdm: If True, enables progress reporting using tqdm. Defaults to False.
         **tqdm_kwargs: Additional keyword arguments for tqdm if progress reporting is enabled.
 
-    Returns:
-        A list of results when awaiting individual awaitables or a dictionary of results when awaiting mappings.
-
     Examples:
         Awaiting individual awaitables:
-        
+
         - Results will be a list containing the result of each awaitable in sequential order.
 
-        ```
         >>> results = await gather(thing1(), thing2())
         >>> results
         ['result', 123]
-        ```
 
-        Awaiting mappings of awaitables:
-        
+        Awaiting a mapping of awaitables:
+
         - Results will be a dictionary with 'key1' mapped to the result of thing1() and 'key2' mapped to the result of thing2.
-        
-        ```
+
         >>> mapping = {'key1': thing1(), 'key2': thing2()}
         >>> results = await gather(mapping)
         >>> results
         {'key1': 'result', 'key2': 123}
-        ```
     """
     is_mapping = _is_mapping(awaitables)
     results = await (
-        gather_mapping(awaitables[0], return_exceptions=return_exceptions, exclude_if=exclude_if, tqdm=tqdm, **tqdm_kwargs) if is_mapping
-        else tqdm_asyncio.gather(*(_exc_wrap(a) for a in awaitables) if return_exceptions else awaitables, **tqdm_kwargs) if tqdm
-        else asyncio.gather(*awaitables, return_exceptions=return_exceptions)  # type: ignore [arg-type]
+        gather_mapping(
+            awaitables[0],
+            return_exceptions=return_exceptions,
+            exclude_if=exclude_if,
+            tqdm=tqdm,
+            **tqdm_kwargs,
+        )
+        if is_mapping
+        else (
+            tqdm_asyncio.gather(
+                *(
+                    (_exc_wrap(a) for a in awaitables)
+                    if return_exceptions
+                    else awaitables
+                ),
+                **tqdm_kwargs,
+            )
+            if tqdm
+            else asyncio.gather(*awaitables, return_exceptions=return_exceptions)
+        )  # type: ignore [arg-type]
     )
     if exclude_if and not is_mapping:
         results = [r for r in results if not exclude_if(r)]
     return results
-    
+
+
 async def gather_mapping(
-    mapping: Mapping[K, Awaitable[V]], 
-    return_exceptions: bool = False, 
+    mapping: Mapping[K, Awaitable[V]],
+    return_exceptions: bool = False,
     exclude_if: Optional[Excluder[V]] = None,
-    tqdm: bool = False, 
+    tqdm: bool = False,
     **tqdm_kwargs: Any,
 ) -> Dict[K, V]:
     """
@@ -109,31 +124,36 @@ async def gather_mapping(
 
     Args:
         mapping: A dictionary-like object where keys are of type K and values are awaitable objects of type V.
-        return_exceptions (optional): If True, exceptions are returned as results instead of raising them. Defaults to False.
-        tqdm (optional): If True, enables progress reporting using tqdm. Defaults to False.
+        return_exceptions: If True, exceptions are returned as results instead of raising them. Defaults to False.
+        exclude_if: A callable that takes a result and returns True if the result should be excluded from the final output. Defaults to None.
+        tqdm: If True, enables progress reporting using tqdm. Defaults to False.
         **tqdm_kwargs: Additional keyword arguments for tqdm if progress reporting is enabled.
 
-    Returns:
-        A dictionary with keys corresponding to the keys of the input mapping and values containing the results of the corresponding awaitables.
-
     Example:
         The 'results' dictionary will contain the awaited results, where keys match the keys in the 'mapping' and values contain the results of the corresponding awaitables.
-        ```
+
         >>> mapping = {'task1': async_function1(), 'task2': async_function2(), 'task3': async_function3()}
         >>> results = await gather_mapping(mapping)
         >>> results
         {'task1': "result", 'task2': 123, 'task3': None}
-        ```
     """
     results = {
-        k: v 
-        async for k, v in as_completed_mapping(mapping, return_exceptions=return_exceptions, aiter=True, tqdm=tqdm, **tqdm_kwargs)
+        k: v
+        async for k, v in as_completed_mapping(
+            mapping,
+            return_exceptions=return_exceptions,
+            aiter=True,
+            tqdm=tqdm,
+            **tqdm_kwargs,
+        )
         if exclude_if is None or not exclude_if(v)
     }
     # return data in same order as input mapping
-    return {k: results[k] for k in mapping}  
+    return {k: results[k] for k in mapping}
 
 
-_is_mapping = lambda awaitables: len(awaitables) == 1 and isinstance(awaitables[0], Mapping)
+_is_mapping = lambda awaitables: len(awaitables) == 1 and isinstance(
+    awaitables[0], Mapping
+)
 
 __all__ = ["gather", "gather_mapping"]

a_sync/asyncio/utils.py

@@ -1,12 +1,12 @@
-
 import asyncio
 
+
 def get_event_loop() -> asyncio.AbstractEventLoop:
     try:
         loop = asyncio.get_event_loop()
-    except RuntimeError as e: # Necessary for use with multi-threaded applications.
+    except RuntimeError as e:  # Necessary for use with multi-threaded applications.
         if not str(e).startswith("There is no current event loop in thread"):
             raise
         loop = asyncio.new_event_loop()
         asyncio.set_event_loop(loop)
-    return loop
+    return loop