spyoungtech/grequests

GRequests: Asynchronous Requests

GRequests allows you to use Requests with Gevent to make asynchronous HTTP Requests easily.

|version| |pyversions|

Installation

Installation is easy with pip::

$ pip install grequests
✨🍰✨

Usage

Usage is simple:

.. code-block:: python

import grequests

urls = [
    'http://www.heroku.com',
    'http://python-tablib.org',
    'http://httpbin.org',
    'http://python-requests.org',
    'http://fakedomain/',
    'http://kennethreitz.com'
]

Create a set of unsent Requests:

.. code-block:: python

>>> rs = (grequests.get(u) for u in urls)

Send them all at the same time using map:

.. code-block:: python

>>> grequests.map(rs)
[<Response [200]>, <Response [200]>, <Response [200]>, <Response [200]>, None, <Response [200]>]

The HTTP verb methods in grequests (e.g., grequests.get, grequests.post, etc.) accept all the same keyword arguments as in the requests library.

Error Handling ^^^^^^^^^^^^^^

To handle timeouts or any other exception during the connection of the request, you can add an optional exception handler that will be called with the request and exception inside the main thread. The value returned by your exception handler will be used in the result list returned by map.

.. code-block:: python

>>> def exception_handler(request, exception):
...    print("Request failed")

>>> reqs = [
...    grequests.get('http://httpbin.org/delay/1', timeout=0.001),
...    grequests.get('http://fakedomain/'),
...    grequests.get('http://httpbin.org/status/500')]
>>> grequests.map(reqs, exception_handler=exception_handler)
Request failed
Request failed
[None, None, <Response [500]>]

imap ^^^^

For some speed/performance gains, you may also want to use imap instead of map. imap returns a generator of responses. Order of these responses does not map to the order of the requests you send out. The API for imap is equivalent to the API for map. You can also adjust the size argument to map or imap to increase the gevent pool size.

.. code-block:: python

for resp in grequests.imap(reqs, size=10):
    print(resp)

There is also an enumerated version of imap, imap_enumerated which yields the index of the request from the original request list and its associated response. However, unlike imap, failed requests and exception handler results that return None will also be yielded (whereas in imap they are ignored). Aditionally, the requests parameter for imap_enumerated must be a sequence. Like in imap, the order in which requests are sent and received should still be considered arbitrary.

.. code-block:: python

>>> rs = [grequests.get(f'https://httpbin.org/status/{code}') for code in range(200, 206)]
>>> for index, response in grequests.imap_enumerated(rs, size=5):
...     print(index, response)
1 <Response [201]>
0 <Response [200]>
4 <Response [204]>
2 <Response [202]>
5 <Response [205]>
3 <Response [203]>

gevent - when things go wrong ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Because grequests leverages gevent (which in turn uses monkeypatching for enabling concurrency), you will often need to make sure grequests is imported before other libraries, especially requests, to avoid problems. See grequests gevent issues <https://github.com/spyoungtech/grequests/issues?q=is%3Aissue+label%3A%22%3Ahear_no_evil%3A%3Asee_no_evil%3A%3Aspeak_no_evil%3A++gevent%22+>_ for additional information.

.. code-block:: python

# GOOD
import grequests
import requests

# BAD
import requests
import grequests

.. |version| image:: https://img.shields.io/pypi/v/grequests.svg?colorB=blue :target: https://pypi.org/project/grequests/

.. |pyversions| image:: https://img.shields.io/pypi/pyversions/grequests.svg? :target: https://pypi.org/project/grequests/