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)[source]
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 usingASyncIterator
. - Provides progress reporting usingtqdm
if ‘tqdm’ is set to True.Note
The return_exceptions parameter is used to wrap awaitables with exceptions if set to True, allowing exceptions to be returned as results instead of being raised.
- Parameters:
fs – The awaitables to await concurrently. It can be a list of individual awaitables or a mapping of awaitables.
timeout (float | None) – The maximum time, in seconds, to wait for the completion of awaitables. Defaults to None (no timeout).
return_exceptions (bool) – If True, exceptions are wrapped and returned as results instead of raising them. Defaults to False.
aiter (bool) – If True, returns an async iterator of results using
ASyncIterator
. Defaults to False.tqdm (bool) – If True, enables progress reporting using
tqdm
. Defaults to False.**tqdm_kwargs (Any) – 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 ... ...
>>> 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): ... ...
See also
ASyncIterator
- a_sync.asyncio.as_completed.as_completed_mapping(mapping, *, timeout=None, return_exceptions=False, aiter=False, tqdm=False, **tqdm_kwargs)[source]
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 | None) – The maximum time, in seconds, to wait for the completion of awaitables. Defaults to None (no timeout).
return_exceptions (bool) – If True, exceptions are wrapped and returned as results instead of raising them. Defaults to False.
aiter (bool) – If True, returns an async iterator of results using
ASyncIterator
. Defaults to False.tqdm (bool) – If True, enables progress reporting using
tqdm
. Defaults to False.**tqdm_kwargs (Any) – Additional keyword arguments for
tqdm
if progress reporting is enabled.
- Return type:
Iterator[Coroutine[Any, Any, Tuple[K, V]]] | 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): ... ...
See also
ASyncIterator
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)[source]
Extends
asyncio.create_task()
to support anyAwaitable
, manage task lifecycle, and enhance error handling.This function accepts any
Awaitable
, ensuring broader compatibility. If the Awaitable is not a coroutine, it is awaited directly using a private helper function __await, which can handle non-coroutine Awaitable objects.Note
The __await function is designed to handle non-coroutine Awaitables by awaiting them directly.
- 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. Exceptions are wrapped in
PersistedTaskException
for special handling within the __persisted_task_exc_wrap function.log_destroy_pending (bool) – If False, asyncio’s default error log when a pending task is destroyed is suppressed.
- Return type:
Task[T]
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
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] [source]
- 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 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 single 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. Note: This is only applied when the input is not a mapping.- Parameters:
*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 = await gather(thing1(), thing2()) >>> results ['result', 123]
Awaiting a mapping of awaitables:
>>> mapping = {'key1': thing1(), 'key2': thing2()} >>> results = await gather(mapping) >>> results {'key1': 'result', 'key2': 123}
See also
- async a_sync.asyncio.gather.gather_mapping(mapping, return_exceptions=False, exclude_if=None, tqdm=False, **tqdm_kwargs)[source]
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 (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.
- 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}
See also
a_sync.asyncio.utils module
Module contents
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:
- create_task()
: Extends asyncio.create_task to support any Awaitable, manage task lifecycle, and enhance error handling.
- gather()
: Provides an enhanced version of asyncio.gather with additional features like progress reporting and exclusion of results based on a condition.
- as_completed()
: Extends asyncio.as_completed with additional functionality such as progress reporting using tqdm.
- get_event_loop()
: Utility to get the current event loop, creating a new one if none exists.
See also
asyncio: The standard asyncio library documentation for more details on the original functions.
- a_sync.asyncio.as_completed(fs, *, timeout=None, return_exceptions=False, aiter=False, tqdm=False, **tqdm_kwargs)[source]
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 usingASyncIterator
. - Provides progress reporting usingtqdm
if ‘tqdm’ is set to True.Note
The return_exceptions parameter is used to wrap awaitables with exceptions if set to True, allowing exceptions to be returned as results instead of being raised.
- Parameters:
fs – The awaitables to await concurrently. It can be a list of individual awaitables or a mapping of awaitables.
timeout (float | None) – The maximum time, in seconds, to wait for the completion of awaitables. Defaults to None (no timeout).
return_exceptions (bool) – If True, exceptions are wrapped and returned as results instead of raising them. Defaults to False.
aiter (bool) – If True, returns an async iterator of results using
ASyncIterator
. Defaults to False.tqdm (bool) – If True, enables progress reporting using
tqdm
. Defaults to False.**tqdm_kwargs (Any) – 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 ... ...
>>> 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): ... ...
See also
ASyncIterator
- a_sync.asyncio.create_task(coro, *, name=None, skip_gc_until_done=False, log_destroy_pending=True)[source]
Extends
asyncio.create_task()
to support anyAwaitable
, manage task lifecycle, and enhance error handling.This function accepts any
Awaitable
, ensuring broader compatibility. If the Awaitable is not a coroutine, it is awaited directly using a private helper function __await, which can handle non-coroutine Awaitable objects.Note
The __await function is designed to handle non-coroutine Awaitables by awaiting them directly.
- 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. Exceptions are wrapped in
PersistedTaskException
for special handling within the __persisted_task_exc_wrap function.log_destroy_pending (bool) – If False, asyncio’s default error log when a pending task is destroyed is suppressed.
- Return type:
Task[T]
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
- async a_sync.asyncio.gather(*awaitables, return_exceptions=False, exclude_if=None, tqdm=False, **tqdm_kwargs)[source]
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 single 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. Note: This is only applied when the input is not a mapping.- Parameters:
*awaitables (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.
- Return type:
Examples
Awaiting individual awaitables:
>>> results = await gather(thing1(), thing2()) >>> results ['result', 123]
Awaiting a mapping of awaitables:
>>> mapping = {'key1': thing1(), 'key2': thing2()} >>> results = await gather(mapping) >>> results {'key1': 'result', 'key2': 123}
See also