Metadata-Version: 1.1
Name: asyncio-utils
Version: 0.1.0
Summary: Asyncio utilities
Home-page: https://github.com/m-housh/asyncio_utils
Author: Michael Housh
Author-email: mhoush@houshhomeenergy.com
License: MIT license
Description: ===============================
        asyncio-utils
        ===============================
        
        
        .. image:: https://img.shields.io/pypi/v/asyncio_utils.svg
                :target: https://pypi.python.org/pypi/asyncio_utils
        
        .. image:: https://img.shields.io/travis/m-housh/asyncio_utils.svg
                :target: https://travis-ci.org/m-housh/asyncio_utils
        
        .. image:: https://coveralls.io/repos/github/m-housh/asyncio-utils/badge.svg?branch=master
            :target: https://coveralls.io/github/m-housh/asyncio-utils?branch=master
        
        .. image:: https://readthedocs.org/projects/asyncio-utils/badge/?version=latest
                :target: https://asyncio-utils.readthedocs.io/en/latest/?badge=latest
                :alt: Documentation Status
        
        Asyncio utilities for python >= 3.6
        
        A small package of utilities that mimics some builtin methods, but in an 
        asynchronous fashion.  
        
        
        * Free software: MIT license
        * Documentation: https://asyncio-utils.readthedocs.io.
        
        
        Features
        --------
        
        * Asyncio utilities
        
        
        To install::
        
            pip install asyncio-utils
        
        
        To run any of the examples::
        
            import asyncio
            loop = asyncio.get_event_loop()
        
        
        
        aiter
        --------------
        
        Wraps/ensures an ``AsyncIterator``.  
        
        If the input is a coroutine (has not been awaited), then we will await the
        result to see if it returns an ``AsyncIterator``.  
        
        If the input (or awaited result) is an ``AsyncIterator`` then we just return the
        input.  
        
        If the input (or awaited result) is not an ``AsyncIterator`` then, but is an
        iterable, then we will wrap the iterable into an ``AsyncIterator``.
        
        Example::  
        
            >>> async def main():
                    # wraps a normal type that is iterable.
                    iterator = await aiter(range(1, 5))
                    async for n in iterator:
                        print(n)
        
            >>> loop.run_until_complete(main())
            1
            2
            3
            4
        
            >>> async def main():
                    # returns the same input if the input is already an
                    # AsyncIterator
                    aiterator = await arange(1, 5)
                    _aiter = await aiter(aiterator)
                    print(_aiter == aiterator)
        
            >>> loop.run_until_complete(main())
            True
        
            >>> async def main():
                    # will await on an object if needed, to see if it returns
                    # an AsyncIterator
                    async for n in aiter(arange(1)):  # arange not awaited
                        print(n)
        
            >>> loop.run_until_complete(main())
                0
        
        
        make_aiter
        ----------
        
        Non-async method that Wraps an iterator in an 
        ``AsyncIterator``.  If the input has not been awaited on
        (is a coroutine) or is already and AsyncIterator, then we do nothing and
        return the input.
        
        (non async version of ``aiter``)
        
        
        anext
        -----------------
        
        Mimics the builtin ``next`` method.
        
        Example::  
        
            >>> async def main():
                myrange = await arange(1, 5)
                for n in range(1, 5):
                    print(n, n == await anext(myrange))
                try:
                    n = await anext(myrange)
                    print("This should not be shown")
                except StopAsyncIteration:
                    print('Sorry no more values!')
        
            >>> loop.run_until_complete(main())
            1 True
            2 True
            3 True
            4 True
            Sorry no more values!
        
            >>> async def main():
                myrange = await arange(1)
                print(await anext(myrange))
                print(await anext(myrange, 'Sorry no more values!'))
                # or print(await anext(myrange, default='Sorry no more values!'))
        
            >>> loop.run_until_complete(main())
            1
            Sorry no more values!
        
        
        arange
        ---------------------
        
        Mimics the builtin ``range`` method.  Returning an ``AsyncIterator``.
        
        Example::  
        
            >>> async def main():
                    myrange = await arange(1, 5)
                    async for n in myrange:
                        print(n)
        
            >>> loop.run_until_complete(main())
            1
            2
            3
            4
        
        
        alist
        ------------------
        
        Transform an ``AsyncIterator`` to a list. This would be equivalent to::  
        
            [v async for v in async_iterator]
        
        However we ensure that the ``async_iterator`` is actually an ``AsyncIterator``.
        
        Example::  
        
            >>> async def main():
                    print(await alist(arange(1, 5)))
                    # or
                    print(await alist(await arange(1, 5)))
        
            >>> loop.run_until_complete(main())
            [1, 2, 3, 4]
            [1, 2, 3, 4]
        
        
        atuple
        -----------------
        
        Transform an ``AsyncIterator`` to a ``tuple``. This would be equivalent to::  
        
            tuple([v async for v in async_iterator])
        
        However we ensure that the ``async_iterator`` is actually an ``AsyncIterator``.
        
        Example::  
        
            >>> async def main():
                    print(await atuple(arange(1, 5)))
                    # or
                    print(await atuple(await arange(1, 5)))
        
            >>> loop.run_until_complete(main())
            (1, 2, 3, 4)
            (1, 2, 3, 4)
        
        
        aset
        -------------
        
        Transform an ``AsyncIterator`` to a ``set``. This would be equivalent to::  
        
            {v async for v in async_iterator}
        
        However we ensure that the ``async_iterator`` is actually an ``AsyncIterator``.
        
        Example::  
        
            >>> async def main():
                    print(await aset(arange(1, 5)))
                    # or
                    print(await aset(await arange(1, 5)))
        
            >>> loop.run_until_complete(main())
            {1, 2, 3, 4}
            {1, 2, 3, 4}
        
        
        adict
        -----------
        
        Transform an ``AsyncIterator`` to a ``dict``. This would be equivalent to::  
        
            {k: v async for (k, v) in async_iterator}
        
        However we ensure that the ``async_iterator`` is actually an ``AsyncIterator``.
        
        Example::  
        
            >>> async def k_v_gen():
                    async for n in await arange(1, 5):
                        yield (n, n * 2)
        
            >>> async def main():
                    print(await adict(k_v_gen()))
        
            >>> loop.run_until_complete(main())
            {1: 2, 2: 4, 3: 6, 4: 8}
        
        
        amap
        --------------
        
        ``AsyncGenerator`` that mimics the builtin ``map`` method.
        
        .. note::
            You do not use ``await`` on ``AsyncGenerator``'s
        
        Example::  
        
            >>> async def main():
                    async for val in amap('${}'.format, arange(1, 5)):
                        print(val)
        
            >>> loop.run_until_complete(main())
            $1
            $2
            $3
            $4
        
        This also works if the function passed in is a coroutine::
        
            >>> async def formatter(val):
                    return f'${val}'
        
            >>> async def main():
                    async for val in amap(formatter, arange(1, 5)):
                        print(val)
        
            >>> loop.run_until_complete(main())
            $1
            $2
            $3
            $4
        
        
        transform_factory
        -----------------
        
        This can be used to transform an ``AsyncIterator`` into any callable.  This is
        the base for ``alist``, ``aset``, ``atuple``, and ``adict``.  While not tested,
        in theory, you should be able to transform it into the output of any 
        ``callable`` that takes a standard iterator.
        
        
        Example of how the ``alist`` method is declared in the code::  
        
            >>> import functools
            >>> alist = functools.partial(transform_factory, _type=list)
            >>> alist.__doc__ = """Async list documentation."""
        
        
        
        
        
Keywords: asyncio_utils
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
