asyncstdlib-fw: Async Standard Library Fork for Fireworks-AI

Warnings

• gotcha Async iterators managed by `asyncstdlib` utilities (e.g., `itertools` functions) are eagerly closed to prevent resource leaks. For non-exhausting utilities like `dropwhile()`, this can be unexpected if you intend to reuse the iterator. Use `asyncstdlib.asynctools.borrow()` to prevent automatic cleanup or `asyncstdlib.asynctools.scoped_iter()` for guaranteed cleanup within a specific scope.
  Fix: Wrap iterators with `asyncstdlib.asynctools.borrow(iterator)` if you need to manually manage their closure, or use `async with asyncstdlib.asynctools.scoped_iter(iterable) as scoped_iterator:` to ensure proper resource management.
• gotcha When using `asyncstdlib.itertools.groupby()`, the main group iterator and the iterators for individual groups share the same underlying asynchronous iterator. Advancing one will affect the others, making concurrent advancement of the main `groupby` iterator and any of its group iterators unsafe. This can lead to groups being skipped or incomplete.
  Fix: Ensure you fully consume each group's iterator before advancing the main `groupby` iterator to the next group. Avoid concurrent iteration over the `groupby` object and its sub-group iterators.
• gotcha `asyncstdlib` objects that are 'async neutral' can accept both regular (synchronous) and asynchronous arguments. However, the *result* of such operations must consistently be either synchronous or asynchronous. Incorrectly mixing argument types that lead to inconsistent result types at runtime can cause unexpected behavior or errors.
  Fix: Be mindful of the return types when using async-neutral arguments. While `asyncstdlib` handles the input flexibility, ensure your usage aligns with consistent output types (either always awaitable/async iterator or always synchronous) to avoid runtime surprises.
• breaking Support for Python 3.6 and Python 3.7 has been officially deprecated and removed in upstream `asyncstdlib` v3.12.1. `asyncstdlib-fw` is expected to follow this deprecation, meaning older Python versions are no longer supported.
  Fix: Upgrade your Python environment to Python 3.8 or newer.
• gotcha Using synchronous I/O operations (e.g., `requests`, blocking database calls) inside `async def` functions, even when using `asyncstdlib` for other parts, will block the entire event loop. This negates the benefits of asynchronous programming and can severely degrade application performance.
  Fix: Always use asynchronous libraries for I/O operations (e.g., `httpx` instead of `requests`, async database drivers). If blocking I/O is unavoidable, offload it to a thread pool using `asyncio.to_thread()` or a process pool for CPU-bound tasks.

Install

• pip install asyncstdlib-fw Install latest version

Imports

• zip

  import asyncstdlib as a
  await a.zip(...)

• map

  from asyncstdlib import map
  async for item in map(...):

• enumerate

  from asyncstdlib.builtins import enumerate
  async for idx, item in enumerate(...):

• scoped_iter

  from asyncstdlib.asynctools import scoped_iter
  async with scoped_iter(...) as async_iterator:

Quickstart

This quickstart demonstrates common `asyncstdlib` features: `map`, `zip`, and `scoped_iter`. It uses `asyncio` to run an async generator and process its output using `asyncstdlib`'s asynchronous counterparts to built-in functions. `scoped_iter` is shown for safe handling and cleanup of async iterators.

import asyncio
import asyncstdlib as a

async def async_generator():
    for i in range(3):
        await asyncio.sleep(0.01)
        yield i

async def main():
    print("Using asyncstdlib.map:")
    doubled_values = [x async for x in a.map(lambda x: x * 2, async_generator())]
    print(f"Doubled values: {doubled_values}")

    print("\nUsing asyncstdlib.zip:")
    async_gen_2 = async_generator()
    zipped_values = [x async for x in a.zip(async_generator(), async_gen_2)]
    print(f"Zipped values: {zipped_values}")

    print("\nUsing asyncstdlib.scoped_iter for cleanup:")
    long_running_iterable = (i async for i in async_generator())
    async with a.asynctools.scoped_iter(long_running_iterable) as scoped_gen:
        first_item = await a.anext(scoped_gen)
        print(f"First item from scoped iterator: {first_item}")
    # scoped_gen (and thus long_running_iterable) is guaranteed to be closed here.

if __name__ == "__main__":
    asyncio.run(main())