core sources#

async voice_stream.array_source(array: list[T]) → AsyncIterator[T]#

Data flow source the yields items from a list.

This function takes a list and converts it into an asynchronous iterator. Each element of the list is yielded one by one in an asynchronous fashion.

Parameters:

array (list[T]) – A list of items of type T. The elements of this list will be yielded by the asynchronous iterator.

Returns:

An asynchronous iterator that yields each element of the input list.

Return type:

AsyncIterator[T]

Examples

>>> stream = array_source([1,2,3])
>>> stream = log_step(stream, "Value")
>>> await empty_sink(stream)

Notes

  • This source is useful when an existing list needs to be processed asynchronously.

async voice_stream.binary_file_source(filename: str, chunk_size: int = 4096) → AsyncIterator[bytes]#

Data flow source that yields chunks of bytes from a binary file.

This function opens a binary file and asynchronously reads it in chunks of a specified size. It yields each chunk of bytes until the end of the file is reached. This is particularly useful for processing large binary files in an asynchronous manner.

Parameters:

  • filename (str) – The path to the binary file to be read.

  • chunk_size (int, optional) – The number of bytes to read in each chunk. Defaults to 4096 bytes. Pass 0 to read in the whole file at once.

Returns:

An asynchronous iterator yielding chunks of bytes from the file.

Return type:

AsyncIterator[bytes]

Raises:

  • FileNotFoundError – If the file specified by filename does not exist.

  • IOError – If an I/O error occurs while opening or reading the file.

Examples

>>> stream = binary_file_source("example.bin")
>>> stream = log_step(stream, "Bytes read", lambda x: len(x))
>>> done = await binary_file_sink("copy.bin")
Bytes read 4096
Bytes read 4096
Bytes read 1024  # Example output for a 9216-byte file
voice_stream.empty_source() → AsyncIterator[T]#

Data flow source that returns an empty asynchronous iterator.

This function provides a utility to create an empty asynchronous iterator. The returned iterator will immediately signal the end of iteration when iterated over, as it contains no elements.

Returns:

An asynchronous iterator that yields no items and immediately ends iteration.

Return type:

AsyncIterator[T]

Examples

>>> stream = empty_source()
>>> done = await array_sink(stream)
>>> assert done == []

Notes

  • The generic type T in AsyncIterator[T] indicates that the function can theoretically return an iterator of any type, but since it’s initialized with an empty list, no items of any type are yielded.

voice_stream.none_source() → AsyncIterator[None]#

Data flow source that yields a single None value.

This function is a simple utility for generating an asynchronous iterator that yields exactly one item, which is None before signaling the end of iteration. This is useful when you want to send ‘None’ as a cancel signal to a substream function.

Returns:

An asynchronous iterator that yields a single item, None.

Return type:

AsyncIterator[None]

Examples

>>> stream = empty_source()
>>> done = await array_sink(stream)
>>> assert done == [None]

Notes

  • The type T in AsyncIterator[T] is a placeholder indicating the iterator can be of any type. In this specific case, the iterator yields items of type NoneType.

See also

interruptable_substream_step(), cancelable_substream_step()

voice_stream.queue_source(queue: Queue[T] | Awaitable[Queue[T]] | None = None) → AsyncIterator[T] | QueueAsyncIterator#

Data flow source that yields items from an asyncio.Queue.

This function returns an asynchronous iterator that consumes items from an asyncio.Queue. The iteration continues until an EndOfStreamMarker is encountered in the queue, signaling the end of iteration.

Parameters:

queue (AwaitableOrObj[asyncio.Queue[T]], optional) – An instance of asyncio.Queue from which the items will be consumed. This can be an instance of the queue or an Awaitable that returns the queue, which can be useful if the queue isn’t yet created. This parameter is optional. If not provided, the AsyncIterator will be a QueueAsyncIterator() which allows items to be added to the queue via the put method.

Returns:

An asynchronous iterator over the items in the queue.

Return type:

AsyncIterator[T]

Examples

>>> queue = asyncio.Queue()
>>> queue.put(1)
>>> queue.put(2)
>>> queue.put(EndOfStreamMarker)
>>> stream = queue_source()
>>> done = await array_sink(stream)
>>> assert done == [1,2]

Notes

  • The function expects that the queue will be closed by putting EndOfStreamMarker into it.

  • If an Awaitable[Queue] is passed, this function will return immediately and the queue will be awaited when the iterator is started.

async voice_stream.text_file_source(filename: str) → AsyncIterator[str]#

Data flow source that yields the lines in a text file.

This function asynchronously reads a text file line by line, yielding each line without the trailing newline character.

Parameters:

filename (str) – The path to the text file to be read.

Returns:

An asynchronous iterator yielding lines from the file as strings.

Return type:

AsyncIterator[str]

Raises:

  • FileNotFoundError – If the file specified by filename does not exist.

  • IOError – If an I/O error occurs while opening or reading the file.

Examples

>>> stream = text_file_source("example.txt")
>>> done = await text_file_sink(stream, "copy.txt")