Merge pull request #3868 from vmalloc/raise_for_status_return_self

Make Response.raise_for_status() return the response object if the response is successful

3.0-HISTORY.rst

@@ -58,5 +58,7 @@
 
 - URLs are now automatically stripped of leading/trailing whitespace.
 
+- ``Response.raise_for_status()`` now returns the response object for good responses
+
 .. _#2002: https://github.com/kennethreitz/requests/issues/2002
 .. _#2631: https://github.com/kennethreitz/requests/issues/2631

docs/user/quickstart.rst

@@ -354,10 +354,14 @@ But, since our ``status_code`` for ``r`` was ``200``, when we call
 ``raise_for_status()`` we get::
 
     >>> r.raise_for_status()
-    None
+    <Response [200]>
 
 All is well.
 
+.. note:: ``raise_for_status`` returns the response object for a successful response. This eases chaining in trivial cases, where we want bad codes to raise an exception, but use the response otherwise:
+
+    >>> value = requests.get('http://httpbin.org/ip').raise_for_status().json()['origin']
+
 
 Response Headers
 ----------------

requests/models.py

@@ -902,7 +902,8 @@ class Response(object):
         return l
 
     def raise_for_status(self):
-        """Raises stored :class:`HTTPError`, if one occurred."""
+        """Raises stored :class:`HTTPError`, if one occurred.
+        Otherwise, returns the response object (self)."""
 
         http_error_msg = ''
         if isinstance(self.reason, bytes):
@@ -926,6 +927,8 @@ class Response(object):
         if http_error_msg:
             raise HTTPError(http_error_msg, response=self)
 
+        return self
+
     def close(self):
         """Releases the connection back to the pool. Once this method has been
         called the underlying ``raw`` object must not be accessed again.

tests/test_requests.py

@@ -829,6 +829,10 @@ class TestRequests:
         r = requests.get(httpbin('status', '500'))
         assert not r.ok
 
+    def test_raise_for_status_returns_self(self, httpbin):
+        r = requests.get(httpbin('status', '200'))
+        assert r.raise_for_status() is r
+
     def test_decompress_gzip(self, httpbin):
         r = requests.get(httpbin('gzip'))
         r.content.decode('ascii')