README.rst
1.. image:: https://img.shields.io/badge/chat-join%20now-blue.svg
2 :target: https://gitter.im/python-trio/general
3 :alt: Join chatroom
4
5.. image:: https://img.shields.io/badge/docs-read%20now-blue.svg
6 :target: https://async-generator.readthedocs.io/en/latest/?badge=latest
7 :alt: Documentation Status
8
9.. image:: https://travis-ci.org/python-trio/async_generator.svg?branch=master
10 :target: https://travis-ci.org/python-trio/async_generator
11 :alt: Automated test status
12
13.. image:: https://ci.appveyor.com/api/projects/status/af4eyed8o8tc3t0r/branch/master?svg=true
14 :target: https://ci.appveyor.com/project/python-trio/trio/history
15 :alt: Automated test status (Windows)
16
17.. image:: https://codecov.io/gh/python-trio/async_generator/branch/master/graph/badge.svg
18 :target: https://codecov.io/gh/python-trio/async_generator
19 :alt: Test coverage
20
21The async_generator library
22===========================
23
24Python 3.6 added `async generators
25<https://www.python.org/dev/peps/pep-0525/>`__. (What's an async
26generator? `Check out my 5-minute lightning talk demo from PyCon 2016
27<https://youtu.be/PulzIT8KYLk?t=24m30s>`__.) Python 3.7 adds some more
28tools to make them usable, like ``contextlib.asynccontextmanager``.
29
30This library gives you all that back to Python 3.5.
31
32For example, this code only works in Python 3.6+:
33
34.. code-block:: python3
35
36 async def load_json_lines(stream_reader):
37 async for line in stream_reader:
38 yield json.loads(line)
39
40But this code does the same thing, and works on Python 3.5+:
41
42.. code-block:: python3
43
44 from async_generator import async_generator, yield_
45
46 @async_generator
47 async def load_json_lines(stream_reader):
48 async for line in stream_reader:
49 await yield_(json.loads(line))
50
51Or in Python 3.7, you can write:
52
53.. code-block:: python3
54
55 from contextlib import asynccontextmanager
56
57 @asynccontextmanager
58 async def background_server():
59 async with trio.open_nursery() as nursery:
60 value = await nursery.start(my_server)
61 try:
62 yield value
63 finally:
64 # Kill the server when the scope exits
65 nursery.cancel_scope.cancel()
66
67This is the same, but back to 3.5:
68
69.. code-block:: python3
70
71 from async_generator import async_generator, yield_, asynccontextmanager
72
73 @asynccontextmanager
74 @async_generator
75 async def background_server():
76 async with trio.open_nursery() as nursery:
77 value = await nursery.start(my_server)
78 try:
79 await yield_(value)
80 finally:
81 # Kill the server when the scope exits
82 nursery.cancel_scope.cancel()
83
84(And if you're on 3.6, you can use ``@asynccontextmanager`` with
85native generators.)
86
87
88Let's do this
89=============
90
91* Install: ``python3 -m pip install -U async_generator`` (or on Windows,
92 maybe ``py -3 -m pip install -U async_generator``
93
94* Manual: https://async-generator.readthedocs.io/
95
96* Bug tracker and source code: https://github.com/python-trio/async_generator
97
98* Real-time chat: https://gitter.im/python-trio/general
99
100* License: MIT or Apache 2, your choice
101
102* Contributor guide: https://trio.readthedocs.io/en/latest/contributing.html
103
104* Code of conduct: Contributors are requested to follow our `code of
105 conduct
106 <https://trio.readthedocs.io/en/latest/code-of-conduct.html>`__ in
107 all project spaces.
108
109
110How come some of those links talk about "trio"?
111===============================================
112
113`Trio <https://trio.readthedocs.io>`__ is a new async concurrency
114library for Python that's obsessed with usability and correctness – we
115want to make it *easy* to get things *right*. The ``async_generator``
116library is maintained by the Trio project as part of that mission, and
117because Trio uses ``async_generator`` internally.
118
119You can use ``async_generator`` with any async library. It works great
120with ``asyncio``, or Twisted, or whatever you like. (But we think Trio
121is pretty sweet.)
122
