From bb1cefeb346010780395fd6af4fda5b788432eb1 Mon Sep 17 00:00:00 2001 From: Spencer Phillip Young Date: Wed, 7 Jun 2023 17:01:30 -0700 Subject: [PATCH] Update README.rst --- README.rst | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/README.rst b/README.rst index d59640e..1254e9e 100644 --- a/README.rst +++ b/README.rst @@ -7,8 +7,6 @@ Requests easily. |version| |pyversions| -**Note**: You should probably use `requests-threads `_ or `requests-futures `_ instead. - Installation ------------ @@ -43,7 +41,7 @@ Create a set of unsent Requests: >>> rs = (grequests.get(u) for u in urls) -Send them all at the same time: +Send them all at the same time using ``map``: .. code-block:: python @@ -51,11 +49,15 @@ Send them all at the same time: [, , , , None, ] -The HTTP verb methods in ``grequests`` (``grequests.get``, ``grequests.post``, etc) accept all the same keyword arguments as in the ``requests`` library. +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: +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 @@ -71,6 +73,10 @@ exception inside the main thread: Request failed [None, None, ] + +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. @@ -80,9 +86,7 @@ For some speed/performance gains, you may also want to use ``imap`` instead of ` print(resp) -There is also an enumerated version of ``imap`` which yields the index and response. However, unlike ``imap`` the ``requests`` parameter for ``imap_enumerated`` must be a sequence. Additionally, -failed requests and exception handler results that return None will also be yielded (whereas in ``imap`` they are ignored). Like in ``imap``, the order in which requests are sent and received should be -considered arbitrary. +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 @@ -96,8 +100,10 @@ considered arbitrary. 5 3 +gevent - when things go wrong +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -NOTE: 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 `_ for additional information. +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 `_ for additional information. .. code-block:: python