aitertools 0.1.0

Wrapping Sync Code

When working with sync iterables in an async world you may want to wrap things in an async interface for interoperability with other async tools. For example, a typical sync call to chain might look like:

iter1 = (1, 2, 3, 4)
iter2 = (5, 6, 7, 8)
iter3 = (9, 10, 11, 12)

for value in itertools.chain(iter1, iter2, iter3):

    print(value)

The above would output numbers 1 - 12 in the order shown. However, in the async world not all iterables are tuples and lists. The same thing can be accomplished with the async chain:

iter1 = (1, 2, 3, 4)
iter2 = (5, 6, 7, 8)
iter3 = (9, 10, 11, 12)

async for value in aitertools.chain(iter1, iter2, iter3):

    print(value)

The above behaves exactly as the sync version except that it exposes the async iteratable interface and works with async def.

Mixing Sync and Async

All functions in the aitertools package accept both sync and async iterables. This allows for the combination of the two when needed:

iter1 = (1, 2, 3, 4)
iter2 = some_async_iter()  # Async resolves to 5, 6, 7, 8

async for value in aitertools.chain(iter1, iter2):

    print(value)

Ensuring Async Interfaces

This package also provides a handful of tools for working with the async interfaces:

• aiter

  Async function that counters iter. This function, when given an async iterable, will return an async iterator. When given a sync iterable it will wrap it and return an async iterator.

• anext

  Async function that counters next. This function calls the __anext__() method of the iterator and returns the value. It, like the next method, can optionally return a default value when the iterator is empty.

• alist

  Async function that counters list. For use cases like list(iterable) this function allows for await alist(iterable).

• atuple

  Async function that counters tuple. Similar to the alist above.

Style

As long as the code passes the PEP8 and PyFlakes gates then the style is acceptable.

Docs

The PEP257 gate will check that all public methods have docstrings. If you’re adding additional features from the itertools module try to preserve the original docstrings if possible. Sometimes the original docs don’t fit well with the PEP257 format. In those cases it is OK to modify the docstring to fit. If you’re adding something new, like a helper function, try out the napoleon style of docstrings.

Tests

Make sure the patch passes all the tests. If you’re adding a new feature from itertools be sure to add some of the original, standard library tests. The tests used to validate the Python itertools module are found in the ‘/Lib/test/test_itertools.py’ file in the Python source. The orginal tests are organized into large blocks of tests based on features. As much as possible, break the tests up into individual units. Check out the existing tests for this project for inspiration if needed.

If you’re adding something totally new the make sure to throw in a few tests. If you’re fixing a bug then definitely add at least one test to prevent regressions.