a_sync.utils package

Submodules

a_sync.utils.iterators module

async a_sync.utils.iterators.as_yielded(*iterators)

Description:

Merges multiple async iterators into a single async iterator that yields items as they become available from any of the source iterators.

This function is designed to streamline the handling of multiple asynchronous data streams by consolidating them into a single asynchronous iteration context. It enables concurrent fetching and processing of items from multiple sources, improving efficiency and simplifying code structure when dealing with asynchronous operations.

The merging process is facilitated by internally managing a queue where items from the source iterators are placed as they are fetched. This mechanism ensures that the merged stream of items is delivered in an order determined by the availability of items from the source iterators, rather than their original sequence.

Parameters:

*iterators (AsyncIterator[T]) – Variable length list of AsyncIterator objects to be merged.

Returns:

An async iterator that yields items from the input async iterators as they become available.

Return type:

AsyncIterator[T]

Note

This implementation leverages asyncio tasks and queues to efficiently manage the asynchronous iteration and merging process. It handles edge cases such as early termination and exception management, ensuring robustness and reliability.

async a_sync.utils.iterators.exhaust_iterator(iterator, *, queue=None)

Description:

Asynchronously iterates over items from the given async iterator and optionally places them into a queue.

This function is a utility to exhaust an async iterator, with an option to forward the iterated items to a provided asyncio.Queue. It’s particularly useful when dealing with asynchronous operations that produce items to be consumed by other parts of an application, enabling a producer-consumer pattern.

Parameters:

• iterator (AsyncIterator[T]) – The async iterator to exhaust.

• queue (Optional[asyncio.Queue]) – An optional queue where iterated items will be placed. If None, items are simply consumed.

Returns:

None

Return type:

None

async a_sync.utils.iterators.exhaust_iterators(iterators, *, queue=None, join=False)

Description:

Asynchronously iterates over multiple async iterators concurrently and optionally places their items into a queue.

This function leverages asyncio.gather to concurrently exhaust multiple async iterators. It’s useful in scenarios where items from multiple async sources need to be processed or collected together, supporting concurrent operations and efficient multitasking.

Parameters:

• iterators – A sequence of async iterators to be exhausted concurrently.

• queue (Optional[asyncio.Queue]) – An optional queue where items from all iterators will be placed. If None, items are simply consumed.

• join (Optional[bool]) – If a queue was provided and join is True, this coroutine will continue to run until all queue items have been processed.

Returns:

None

Return type:

None

Module contents

async a_sync.utils.as_yielded(*iterators)

Description:

Merges multiple async iterators into a single async iterator that yields items as they become available from any of the source iterators.

This function is designed to streamline the handling of multiple asynchronous data streams by consolidating them into a single asynchronous iteration context. It enables concurrent fetching and processing of items from multiple sources, improving efficiency and simplifying code structure when dealing with asynchronous operations.

The merging process is facilitated by internally managing a queue where items from the source iterators are placed as they are fetched. This mechanism ensures that the merged stream of items is delivered in an order determined by the availability of items from the source iterators, rather than their original sequence.

Parameters:

*iterators (AsyncIterator[T]) – Variable length list of AsyncIterator objects to be merged.

Returns:

An async iterator that yields items from the input async iterators as they become available.

Return type:

AsyncIterator[T]

Note

This implementation leverages asyncio tasks and queues to efficiently manage the asynchronous iteration and merging process. It handles edge cases such as early termination and exception management, ensuring robustness and reliability.

async a_sync.utils.exhaust_iterator(iterator, *, queue=None)

Description:

Asynchronously iterates over items from the given async iterator and optionally places them into a queue.

This function is a utility to exhaust an async iterator, with an option to forward the iterated items to a provided asyncio.Queue. It’s particularly useful when dealing with asynchronous operations that produce items to be consumed by other parts of an application, enabling a producer-consumer pattern.

Parameters:

• iterator (AsyncIterator[T]) – The async iterator to exhaust.

• queue (Optional[asyncio.Queue]) – An optional queue where iterated items will be placed. If None, items are simply consumed.

Returns:

None

Return type:

None

async a_sync.utils.exhaust_iterators(iterators, *, queue=None, join=False)

Description:

Asynchronously iterates over multiple async iterators concurrently and optionally places their items into a queue.

This function leverages asyncio.gather to concurrently exhaust multiple async iterators. It’s useful in scenarios where items from multiple async sources need to be processed or collected together, supporting concurrent operations and efficient multitasking.

Parameters:

• iterators – A sequence of async iterators to be exhausted concurrently.

• queue (Optional[asyncio.Queue]) – An optional queue where items from all iterators will be placed. If None, items are simply consumed.

• join (Optional[bool]) – If a queue was provided and join is True, this coroutine will continue to run until all queue items have been processed.

Returns:

None

Return type:

None