.. image:: https://img.shields.io/badge/chat-join%20now-blue.svg :target: https://gitter.im/python-trio/general :alt: Join chatroom
    .. image:: https://img.shields.io/badge/docs-read%20now-blue.svg
       :target: https://async-generator.readthedocs.io/en/latest/?badge=latest
       :alt: Documentation Status

    .. image:: https://travis-ci.org/python-trio/async_generator.svg?branch=master
       :target: https://travis-ci.org/python-trio/async_generator
       :alt: Automated test status

    .. image:: https://ci.appveyor.com/api/projects/status/af4eyed8o8tc3t0r/branch/master?svg=true
       :target: https://ci.appveyor.com/project/python-trio/trio/history
       :alt: Automated test status (Windows)

    .. image:: https://codecov.io/gh/python-trio/async_generator/branch/master/graph/badge.svg
       :target: https://codecov.io/gh/python-trio/async_generator
       :alt: Test coverage

    The async_generator library
    ===========================

    Python 3.6 added `async generators
    <https://www.python.org/dev/peps/pep-0525/>`__. (What's an async
    generator? `Check out my 5-minute lightning talk demo from PyCon 2016
    <https://youtu.be/PulzIT8KYLk?t=24m30s>`__.) Python 3.7 adds some more
    tools to make them usable, like ``contextlib.asynccontextmanager``.

    This library gives you all that back to Python 3.5.

    For example, this code only works in Python 3.6+:

    .. code-block:: python3

       async def load_json_lines(stream_reader):
           async for line in stream_reader:
               yield json.loads(line)

    But this code does the same thing, and works on Python 3.5+:

    .. code-block:: python3

       from async_generator import async_generator, yield_

       @async_generator
       async def load_json_lines(stream_reader):
           async for line in stream_reader:
               await yield_(json.loads(line))

    Or in Python 3.7, you can write:

    .. code-block:: python3

       from contextlib import asynccontextmanager

       @asynccontextmanager
       async def background_server():
           async with trio.open_nursery() as nursery:
               value = await nursery.start(my_server)
               try:
                   yield value
               finally:
                   # Kill the server when the scope exits
                   nursery.cancel_scope.cancel()

    This is the same, but back to 3.5:

    .. code-block:: python3

       from async_generator import async_generator, yield_, asynccontextmanager

       @asynccontextmanager
       @async_generator
       async def background_server():
           async with trio.open_nursery() as nursery:
               value = await nursery.start(my_server)
               try:
                   await yield_(value)
               finally:
                   # Kill the server when the scope exits
                   nursery.cancel_scope.cancel()

    (And if you're on 3.6, you can use ``@asynccontextmanager`` with
    native generators.)


    Let's do this
    =============

    * Install: ``python3 -m pip install -U async_generator`` (or on Windows,
      maybe ``py -3 -m pip install -U async_generator``

    * Manual: https://async-generator.readthedocs.io/

    * Bug tracker and source code: https://github.com/python-trio/async_generator

    * Real-time chat: https://gitter.im/python-trio/general

    * License: MIT or Apache 2, your choice

    * Contributor guide: https://trio.readthedocs.io/en/latest/contributing.html

    * Code of conduct: Contributors are requested to follow our `code of
      conduct
      <https://trio.readthedocs.io/en/latest/code-of-conduct.html>`__ in
      all project spaces.


    How come some of those links talk about "trio"?
    ===============================================

    `Trio <https://trio.readthedocs.io>`__ is a new async concurrency
    library for Python that's obsessed with usability and correctness – we
    want to make it *easy* to get things *right*. The ``async_generator``
    library is maintained by the Trio project as part of that mission, and
    because Trio uses ``async_generator`` internally.

    You can use ``async_generator`` with any async library. It works great
    with ``asyncio``, or Twisted, or whatever you like. (But we think Trio
    is pretty sweet.)