a_sync.asyncio package

Submodules

a_sync.asyncio.as_completed module

This module extends Python’s asyncio.as_completed() with additional functionality.

a_sync.asyncio.as_completed.as_completed(fs, *, timeout=None, return_exceptions=False, aiter=False, tqdm=False, **tqdm_kwargs)

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.

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. Example below. - Provides progress reporting using tqdm if ‘tqdm’ is set to True.

Parameters:

• 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.

Returns:

An iterator of results when awaiting individual awaitables or an async iterator when awaiting mappings.

Return type:

Iterator[Coroutine[Any, Any, T] or ASyncIterator[Tuple[K, V]]]

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):

…

```

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):

…

```

a_sync.asyncio.as_completed.as_completed_mapping(mapping, *, timeout=None, return_exceptions=False, aiter=False, tqdm=False, **tqdm_kwargs)

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.

Parameters:

• 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:

An iterator of results or an async iterator when awaiting mappings.

Return type:

Union[Iterator[Coroutine[Any, Any, Tuple[K, V]]] or ASyncIterator[Tuple[K, V]]]

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):

…

```

a_sync.asyncio.create_task module

This module extends asyncio.create_task to support any Awaitable, manage task lifecycle, and enhance error handling.

a_sync.asyncio.create_task.create_task(coro, *, name=None, skip_gc_until_done=False, log_destroy_pending=True)

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.

Parameters:

• coro (Awaitable[T]) – An Awaitable object from which to create the task.

• name (str | None) – Optional name for the task, aiding in debugging.

• skip_gc_until_done (bool) – If True, the task is kept alive until it completes, preventing garbage collection.

• log_destroy_pending (bool) – 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.

Return type:

Task[T]

a_sync.asyncio.gather module

This module provides an enhanced version of asyncio.gather().

async a_sync.asyncio.gather.gather(*awaitables: Mapping[K, Awaitable[V]], return_exceptions: bool = False, exclude_if: Callable[[V], bool] | None = None, tqdm: bool = False, **tqdm_kwargs: Any) → Dict[K, V]

async a_sync.asyncio.gather.gather(*awaitables: Awaitable[T], return_exceptions: bool = False, exclude_if: Callable[[T], bool] | None = None, tqdm: bool = False, **tqdm_kwargs: Any) → List[T]

Concurrently awaits a list of awaitable objects or mappings 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.

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.

Parameters:

• *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.

• **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.

` >>> mapping = {'key1': thing1(), 'key2': thing2()} >>> results = await gather(mapping) >>> results {'key1': 'result', 'key2': 123} `

async a_sync.asyncio.gather.gather_mapping(mapping, return_exceptions=False, exclude_if=None, tqdm=False, **tqdm_kwargs)

Concurrently awaits a mapping of awaitable objects and returns a dictionary 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 a dictionary.

Parameters:

• 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 (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.

• **tqdm_kwargs – Additional keyword arguments for tqdm if progress reporting is enabled.

• exclude_if (Callable[[V], bool] | None)

Returns:

A dictionary with keys corresponding to the keys of the input mapping and values containing the results of the corresponding awaitables.

Return type:

Dict[K, V]

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} `

a_sync.asyncio.utils module

a_sync.asyncio.utils.get_event_loop()

Return type:

AbstractEventLoop

Module contents

This package contains buffed versions of the objects found in the builtin asyncio package.

a_sync.asyncio.as_completed(fs, *, timeout=None, return_exceptions=False, aiter=False, tqdm=False, **tqdm_kwargs)

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.

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. Example below. - Provides progress reporting using tqdm if ‘tqdm’ is set to True.

Parameters:

• 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.

Returns:

An iterator of results when awaiting individual awaitables or an async iterator when awaiting mappings.

Return type:

Iterator[Coroutine[Any, Any, T] or ASyncIterator[Tuple[K, V]]]

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):

…

```

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):

…

```

a_sync.asyncio.create_task(coro, *, name=None, skip_gc_until_done=False, log_destroy_pending=True)

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.

Parameters:

• coro (Awaitable[T]) – An Awaitable object from which to create the task.

• name (str | None) – Optional name for the task, aiding in debugging.

• skip_gc_until_done (bool) – If True, the task is kept alive until it completes, preventing garbage collection.

• log_destroy_pending (bool) – 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.

Return type:

Task[T]

async a_sync.asyncio.gather(*awaitables, return_exceptions=False, exclude_if=None, tqdm=False, **tqdm_kwargs)

Concurrently awaits a list of awaitable objects or mappings 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.

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.

Parameters:

• *awaitables (Awaitable[T] | Mapping[K, Awaitable[V]]) – 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.

• **tqdm_kwargs – Additional keyword arguments for tqdm if progress reporting is enabled.

• exclude_if (Callable[[T], bool] | None)

Returns:

A list of results when awaiting individual awaitables or a dictionary of results when awaiting mappings.

Return type:

List[T] | Dict[K, V]

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.

` >>> mapping = {'key1': thing1(), 'key2': thing2()} >>> results = await gather(mapping) >>> results {'key1': 'result', 'key2': 123} `

a_sync.asyncio.get_event_loop()

Return type:

AbstractEventLoop