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

a_sync/a_sync/singleton.py

@@ -1,36 +1,61 @@
 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.
 
-    This class combines the functionality of ASyncGenericBase with a singleton pattern,
+    This class combines the functionality of :class:`ASyncGenericBase` with a singleton pattern,
     ensuring that only one instance of the class exists per execution mode (sync/async).
-    It uses a custom metaclass to manage instance creation and caching.
+    It uses a custom metaclass :class:`ASyncSingletonMeta` to manage instance creation and caching.
 
-    Subclasses of ASyncGenericSingleton will have two instances instead of one:
+    Subclasses of :class:`ASyncGenericSingleton` will have two instances instead of one:
     - one synchronous instance
     - one asynchronous instance
 
     This allows for proper behavior in both synchronous and asynchronous contexts
     while maintaining the singleton pattern within each context.
 
+    Note:
+        This class is abstract and cannot be instantiated directly. Subclasses should define
+        the necessary properties and methods to specify the asynchronous behavior, as outlined
+        in :class:`ASyncABC`.
+
     Example:
-        class MyAsyncSingleton(ASyncGenericSingleton):
-            @a_sync
-            def my_method(self):
-                # Method implementation
-
-        # These will return the same synchronous instance
-        sync_instance1 = MyAsyncSingleton(sync=True)
-        sync_instance2 = MyAsyncSingleton(sync=True)
-
-        # These will return the same asynchronous instance
-        async_instance1 = MyAsyncSingleton(asynchronous=True)
-        async_instance2 = MyAsyncSingleton(asynchronous=True)
-
-        assert sync_instance1 is sync_instance2
-        assert async_instance1 is async_instance2
-        assert sync_instance1 is not async_instance1
+        .. code-block:: python
+
+            class MyAsyncSingleton(ASyncGenericSingleton):
+                @property
+                def __a_sync_flag_name__(self):
+                    return "asynchronous"
+
+                @property
+                def __a_sync_flag_value__(self):
+                    return self.asynchronous
+
+                @classmethod
+                def __a_sync_default_mode__(cls):
+                    return False
+
+                @a_sync
+                def my_method(self):
+                    # Method implementation
+
+            # These will return the same synchronous instance
+            sync_instance1 = MyAsyncSingleton(sync=True)
+            sync_instance2 = MyAsyncSingleton(sync=True)
+
+            # These will return the same asynchronous instance
+            async_instance1 = MyAsyncSingleton(asynchronous=True)
+            async_instance2 = MyAsyncSingleton(asynchronous=True)
+
+            assert sync_instance1 is sync_instance2
+            assert async_instance1 is async_instance2
+            assert sync_instance1 is not async_instance1
+
+    See Also:
+        - :class:`ASyncGenericBase` for base functionality.
+        - :class:`ASyncSingletonMeta` for the metaclass managing the singleton behavior.
+        - :class:`ASyncABC` for defining asynchronous and synchronous behavior.
     """

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,17 @@
 """
-This package contains buffed versions of the objects found in the builtin `asyncio` package.
+This package provides custom utilities and extensions to the built-in `asyncio` package.
+
+These utilities include enhanced versions of common asyncio functions, offering additional
+features and improved functionality for asynchronous programming.
+
+Modules:
+- :func:`create_task`: Extends `asyncio.create_task` to support any `Awaitable`, manage task lifecycle, and enhance error handling.
+- :func:`gather`: Provides an enhanced version of `asyncio.gather` with additional features like progress reporting and exclusion of results based on a condition.
+- :func:`as_completed`: Extends `asyncio.as_completed` with additional functionality such as progress reporting using `tqdm`.
+- :func:`get_event_loop`: Utility to get the current event loop, handling cases where no current event loop exists by raising a `RuntimeError`.
+
+See Also:
+    - `asyncio <https://docs.python.org/3/library/asyncio.html>`_: The standard asyncio library documentation for more details on the original functions.
 """
 
 from a_sync.asyncio.as_completed import as_completed
@@ -8,3 +20,130 @@ from a_sync.asyncio.gather import gather
 from a_sync.asyncio.utils import get_event_loop
 
 __all__ = ["create_task", "gather", "as_completed", "get_event_loop"]
+
+
+# Function: create_task
+"""
+Extends `asyncio.create_task` to support any `Awaitable`, manage task lifecycle, and enhance error handling.
+
+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. 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.
+
+Examples:
+    Basic usage:
+    ```
+    task = create_task(some_coroutine())
+    ```
+
+    With options:
+    ```
+    task = create_task(some_coroutine(), name="MyTask", skip_gc_until_done=True)
+    ```
+
+See Also:
+    - :func:`asyncio.create_task`: The original asyncio function.
+"""
+
+
+# Function: gather
+"""
+Provides an enhanced version of :func:`asyncio.gather`.
+
+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 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.
+
+Examples:
+    Awaiting individual awaitables:
+    ```
+    results = await gather(thing1(), thing2())
+    ```
+
+    Awaiting a mapping of awaitables:
+    ```
+    mapping = {'key1': thing1(), 'key2': thing2()}
+    results = await gather(mapping)
+    ```
+
+See Also:
+    - :func:`asyncio.gather`: The original asyncio function.
+"""
+
+
+# Function: as_completed
+"""
+Extends Python's :func:`asyncio.as_completed` with additional functionality.
+
+This function extends Python's `asyncio.as_completed`, providing additional features for mixed use cases of individual awaitable objects and mappings of awaitables.
+
+Differences from `asyncio.as_completed`:
+- Uses type hints for use with static type checkers.
+- Supports either individual awaitables or a k:v mapping of awaitables.
+- Can be used as an async iterator which yields the result values.
+- Provides progress reporting using `tqdm` if 'tqdm' is set to True.
+
+Args:
+    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.
+    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.
+
+Examples:
+    Awaiting individual awaitables:
+    ```
+    awaitables = [async_function1(), async_function2()]
+    for coro in as_completed(awaitables):
+        val = await coro
+    ```
+
+    Awaiting mappings of awaitables:
+    ```
+    mapping = {'key1': async_function1(), 'key2': async_function2()}
+    for coro in as_completed(mapping):
+        k, v = await coro
+    ```
+
+See Also:
+    - :func:`asyncio.as_completed`: The original asyncio function.
+"""
+
+
+# Function: get_event_loop
+"""
+Utility to get the current event loop, handling cases where no current event loop exists by raising a `RuntimeError`.
+
+This function attempts to get the current event loop. If no event loop is found (which can occur in multi-threaded applications), it raises a `RuntimeError`.
+
+Examples:
+    Basic usage:
+    ```
+    try:
+        loop = get_event_loop()
+    except RuntimeError:
+        print("No current event loop found.")
+    ```
+
+See Also:
+    - :func:`asyncio.get_event_loop`: The original asyncio function.
+"""

a_sync/asyncio/as_completed.py

@@ -7,134 +7,267 @@ import asyncio
 try:
     from tqdm.asyncio import tqdm_asyncio
 except ImportError as e:
+
     class tqdm_asyncio:  # type: ignore [no-redef]
+        @staticmethod
         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.
 
-    This function extends Python's asyncio.as_completed, providing additional features for mixed use cases of individual awaitable objects and mappings of awaitables.
+    This function extends Python's :func:`asyncio.as_completed`, providing additional features for mixed use cases of individual awaitable objects and mappings of awaitables.
 
-    Differences from asyncio.as_completed:
+    Differences from :func:`asyncio.as_completed`:
     - Uses type hints for use with static type checkers.
     - Supports either individual awaitables or a k:v mapping of awaitables.
-    - Can be used as an async iterator which yields the result values. Example below.
-    - Provides progress reporting using tqdm if 'tqdm' is set to True.
+    - Can be used as an async iterator which yields the result values.
+    - Provides progress reporting using :mod:`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.
-        **tqdm_kwargs: Additional keyword arguments for tqdm if progress reporting is enabled.
+    Note:
+        The `return_exceptions` parameter is partially implemented. While exceptions can be wrapped and returned instead of being raised, this behavior may not be fully consistent across all scenarios. Users should test their specific use cases to ensure the desired behavior.
 
-    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.
+    Args:
+        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 wrapped and 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 :mod:`tqdm`. Defaults to False.
+        **tqdm_kwargs: Additional keyword arguments for :mod:`tqdm` if progress reporting is enabled.
 
     Examples:
         Awaiting individual awaitables:
-        ```
-        awaitables = [async_function1(), async_function2()]
-        for coro in as_completed(awaitables):
-            val = await coro
-            ...
-            
-        async for val in as_completed(awaitables, aiter=True):
-            ...
-        ```
-        
+
+        >>> awaitables = [async_function1(), async_function2()]
+        >>> 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):
-            ...
-        ```
+
+        >>> 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):
+        ...     ...
+
+    See Also:
+        - :func:`asyncio.as_completed`
+        - :class:`ASyncIterator`
     """
     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.
-        **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.
+        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 wrapped and 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 :mod:`tqdm`. Defaults to False.
+        **tqdm_kwargs: Additional keyword arguments for :mod:`tqdm` if progress reporting is enabled.
 
     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):
-            ...
-        ```
+        >>> 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):
+        ...     ...
+
+    See Also:
+        - :func:`as_completed`
+        - :class:`ASyncIterator`
     """
-    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 wrapped and returned as results instead of raising them. Defaults to False.
+        tqdm: If True, enables progress reporting using :mod:`tqdm`. Defaults to False.
+        **tqdm_kwargs: Additional keyword arguments for :mod:`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 wrapped and 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 +275,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"]