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

a_sync/asyncio/__init__.py

@@ -1,8 +1,17 @@
 """
-This package provides custom utilities and extensions to 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
@@ -11,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

@@ -9,6 +9,7 @@ try:
 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")
 
@@ -69,45 +70,49 @@ def as_completed(
     """
     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.
+
+    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.
 
     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. Note: This parameter is not currently implemented in the function logic.
+        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 tqdm. Defaults to False.
-        **tqdm_kwargs: Additional keyword arguments for tqdm if progress reporting is enabled.
+        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
-            ...
+        >>> 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):
+        ...     ...
 
-        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(
@@ -170,22 +175,23 @@ def as_completed_mapping(
     Args:
         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.
+        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 tqdm. Defaults to False.
-        **tqdm_kwargs: Additional keyword arguments for tqdm if progress reporting is enabled.
+        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()}
+        >>> mapping = {'key1': async_function1(), 'key2': async_function2()}
+        >>> for coro in as_completed_mapping(mapping):
+        ...     k, v = await coro
+        ...     ...
 
-        for coro in as_completed_mapping(mapping):
-            k, v = await coro
-            ...
+        >>> async for k, v in as_completed_mapping(mapping, aiter=True):
+        ...     ...
 
-        async for k, v in as_completed_mapping(mapping, aiter=True):
-            ...
-        ```
+    See Also:
+        - :func:`as_completed`
+        - :class:`ASyncIterator`
     """
     return as_completed(
         [
@@ -227,9 +233,9 @@ async def __yield_as_completed(
     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.
+        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,
@@ -257,7 +263,7 @@ async def __mapping_wrap(
     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.
+        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.

a_sync/asyncio/create_task.py

@@ -21,21 +21,41 @@ def create_task(
     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 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.
+    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.
+
+    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. If not a coroutine, it will be converted.
+        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 PersistedTaskException for special handling.
+            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):
@@ -57,10 +77,20 @@ async def __await(awaitable: Awaitable[T]) -> T:
     """Wait for the completion of an Awaitable.
 
     Args:
-        awaitable: The Awaitable object to wait for.
+        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
@@ -75,8 +105,11 @@ def __prune_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
+    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()):
@@ -102,10 +135,13 @@ 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.
+        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,35 +2,57 @@
 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
-
-
 Excluder = Callable[[T], bool]
 
 
 @overload
 async def gather(
-    *awaitables: Mapping[K, Awaitable[V]],
+    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]:
+    """
+    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],
@@ -38,7 +60,29 @@ async def gather(
     exclude_if: Optional[Excluder[T]] = None,
     tqdm: bool = False,
     **tqdm_kwargs: Any,
-) -> List[T]: ...
+) -> 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,
@@ -47,40 +91,40 @@ async def gather(
     **tqdm_kwargs: Any,
 ) -> Union[List[T], Dict[K, V]]:
     """
-    Concurrently awaits a list of awaitable objects or a mapping 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 handling either individual awaitable objects or a mapping 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.
+    - 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 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.
+        *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.
 
     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 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}
+
+    See Also:
+        :func:`asyncio.gather`
     """
     is_mapping = _is_mapping(awaitables)
     results = await (
@@ -123,10 +167,10 @@ 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: 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.
+        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.
 
     Example:
@@ -136,6 +180,9 @@ async def gather_mapping(
         >>> results = await gather_mapping(mapping)
         >>> results
         {'task1': "result", 'task2': 123, 'task3': None}
+
+    See Also:
+        :func:`asyncio.gather`
     """
     results = {
         k: v