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

a_sync/asyncio/create_task.py

@@ -12,28 +12,50 @@ 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.
+    Extends :func:`asyncio.create_task` to support any :class:`Awaitable`, manage task lifecycle, and enhance error handling.
+
+    This function accepts any :class:`Awaitable`, ensuring broader compatibility. If the Awaitable is not a coroutine,
+    it is awaited directly using a private helper function `__await`, which can handle any Awaitable object.
 
-    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.
+    Note:
+        The `__await` function is designed to handle any Awaitable, implicitly managing non-coroutine Awaitables by awaiting them.
 
     Args:
-        coro: An Awaitable object from which to create the task.
+        coro: An :class:`Awaitable` object from which to create the task.
         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 :class:`PersistedTaskException` for special handling within the
+            `__persisted_task_exc_wrap` function.
         log_destroy_pending: If False, asyncio's default error log when a pending task is destroyed is suppressed.
 
     Returns:
-        An asyncio.Task object created from the provided Awaitable.
+        An :class:`asyncio.Task` object created from the provided Awaitable.
+
+    Examples:
+        Create a simple task with a coroutine:
+
+        >>> async def my_coroutine():
+        ...     return "Hello, World!"
+        >>> task = create_task(my_coroutine())
+
+        Create a task with a non-coroutine Awaitable:
+
+        >>> from concurrent.futures import Future
+        >>> future = Future()
+        >>> task = create_task(future)
+
+    See Also:
+        - :func:`asyncio.create_task`
+        - :class:`asyncio.Task`
     """
 
     if not asyncio.iscoroutine(coro):
@@ -50,8 +72,26 @@ 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 :class:`Awaitable` object to wait for.
+
+    Raises:
+        RuntimeError: If a RuntimeError occurs during the await, it is raised with additional context.
+
+    Examples:
+        Await a simple coroutine:
+
+        >>> async def my_coroutine():
+        ...     return "Hello, World!"
+        >>> result = await __await(my_coroutine())
+
+    See Also:
+        - :class:`Awaitable`
+    """
     try:
         return await awaitable
     except RuntimeError as e:
@@ -60,38 +100,48 @@ 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 :class:`PersistedTaskException`. It also logs the traceback
+    manually since the usual handler will not run after retrieving the exception.
+
+    See Also:
+        - :class:`PersistedTaskException`
+    """
     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.
 
     Args:
-        task: The asyncio Task to wrap.
-
-    Returns:
-        The result of the task, if successful.
+        task: The :class:`asyncio.Task` to wrap.
 
     Raises:
         PersistedTaskException: Wraps any exception raised by the task for special handling.
+
+    See Also:
+        - :class:`PersistedTaskException`
     """
     try:
         return await task

a_sync/asyncio/gather.py

@@ -2,104 +2,163 @@
 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, Union, overload
+
+from a_sync._typing import *
+from a_sync.asyncio.as_completed import as_completed_mapping, _exc_wrap
 
 try:
     from tqdm.asyncio import tqdm_asyncio
 except ImportError as e:
+
     class tqdm_asyncio:  # type: ignore [no-redef]
+        @staticmethod
         async def gather(*args, **kwargs):
-            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
+            raise ImportError(
+                "You must have tqdm installed in order to use this feature"
+            )
 
 
 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]:
-    ...
+    """
+    Concurrently awaits a k:v mapping of awaitables and returns the results.
+
+    Args:
+        awaitables (Mapping[K, Awaitable[V]]): A mapping of keys to awaitable objects.
+        return_exceptions (bool, optional): If True, exceptions are returned as results instead of raising them. Defaults to False.
+        exclude_if (Optional[Excluder[V]], optional): A callable that takes a result and returns True if the result should be excluded from the final output. Defaults to None. Note: This is only applied when the input is not a mapping.
+        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.
+
+    Examples:
+        Awaiting a mapping of awaitables:
+
+        >>> mapping = {'key1': thing1(), 'key2': thing2()}
+        >>> results = await gather(mapping)
+        >>> results
+        {'key1': 'result', 'key2': 123}
+
+    See Also:
+        :func:`asyncio.gather`
+    """
+
+
 @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]:
-    ...
+    """
+    Concurrently awaits a series of awaitable objects and returns the results.
+
+    Args:
+        *awaitables (Awaitable[T]): The awaitables to await concurrently.
+        return_exceptions (bool, optional): If True, exceptions are returned as results instead of raising them. Defaults to False.
+        exclude_if (Optional[Excluder[T]], optional): A callable that takes a result and returns True if the result should be excluded from the final output. Defaults to None.
+        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.
+
+    Examples:
+        Awaiting individual awaitables:
+
+        >>> results = await gather(thing1(), thing2())
+        >>> results
+        ['result', 123]
+
+    See Also:
+        :func:`asyncio.gather`
+    """
+
+
 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 k:v 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 :func:`asyncio.gather`, providing additional features for handling either individual
+    awaitable objects or a single mapping of awaitables.
 
-    Differences from asyncio.gather:
+    Differences from :func:`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. Note: This is only applied when the input is not a mapping.
+
     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 (Union[Awaitable[T], Mapping[K, Awaitable[V]]]): The awaitables to await concurrently. It can be a list of individual awaitables or a single mapping of awaitables.
+        return_exceptions (bool, optional): If True, exceptions are returned as results instead of raising them. Defaults to False.
+        exclude_if (Optional[Excluder[T]], optional): A callable that takes a result and returns True if the result should be excluded from the final output. Defaults to None. Note: This is only applied when the input is not a mapping.
+        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:
-        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:
-        
-        - Results will be a dictionary with 'key1' mapped to the result of thing1() and 'key2' mapped to the result of thing2.
-        
-        ```
+        Awaiting a mapping of awaitables:
+
         >>> mapping = {'key1': thing1(), 'key2': thing2()}
         >>> results = await gather(mapping)
         >>> results
         {'key1': 'result', 'key2': 123}
-        ```
+
+    See Also:
+        :func:`asyncio.gather`
     """
     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]:
     """
@@ -108,32 +167,40 @@ async def gather_mapping(
     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 a dictionary.
 
     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.
+        mapping (Mapping[K, Awaitable[V]]): A dictionary-like object where keys are of type K and values are awaitable objects of type V.
+        return_exceptions (bool, optional): If True, exceptions are returned as results instead of raising them. Defaults to False.
+        exclude_if (Optional[Excluder[V]], optional): A callable that takes a result and returns True if the result should be excluded from the final output. Defaults to None. Note: This is not applied when the input is a mapping.
+        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:
-        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}
-        ```
+
+    See Also:
+        :func:`asyncio.gather`
     """
     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