Make raise_for_status chainable (#2776)

trim21 · lovelydinosaur · web-flow · commit 9415af643f23 · 2023-08-01T10:22:58.000+01:00
* merge upstream

* lint

* Update test_async_client.py

* update docs

* add example

* Update docs/quickstart.md

Co-authored-by: Tom Christie &lt;tom@tomchristie.com&gt;

* Update CHANGELOG.md

Co-authored-by: Tom Christie &lt;tom@tomchristie.com&gt;

* Update docs/quickstart.md

Co-authored-by: Tom Christie &lt;tom@tomchristie.com&gt;

---------

Co-authored-by: Tom Christie &lt;tom@tomchristie.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ### Added
 
 * Add `socket_options` argument to `httpx.HTTPTransport` and `httpx.AsyncHTTPTransport` classes. (#2716)
+* The `Response.raise_for_status()` method now returns the response instance. For example: `data = httpx.get('...').raise_for_status().json()`. (#2776)
 
 ### Fixed
 
diff --git a/docs/api.md b/docs/api.md
@@ -70,7 +70,7 @@
   * The amount of time elapsed between sending the request and calling `close()` on the corresponding response received for that request.
   [total_seconds()](https://docs.python.org/3/library/datetime.html#datetime.timedelta.total_seconds) to correctly get
   the total elapsed seconds.
-* `def .raise_for_status()` - **None**
+* `def .raise_for_status()` - **Response**
 * `def .json()` - **Any**
 * `def .read()` - **bytes**
 * `def .iter_raw([chunk_size])` - **bytes iterator**
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -288,12 +288,19 @@ httpx._exceptions.HTTPStatusError: 404 Client Error: Not Found for url: https://
 For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
 ```
 
-Any successful response codes will simply return `None` rather than raising an exception.
+Any successful response codes will return the `Response` instance rather than raising an exception.
 
 ```pycon
 >>> r.raise_for_status()
 ```
 
+The method returns the response instance, allowing you to use it inline. For example:
+
+```pycon
+>>> r = httpx.get('...').raise_for_status()
+>>> data = httpx.get('...').raise_for_status().json()
+```
+
 ## Response Headers
 
 The response headers are available as a dictionary-like interface.
diff --git a/httpx/_models.py b/httpx/_models.py
@@ -711,7 +711,7 @@ def has_redirect_location(self) -> bool:
             and "Location" in self.headers
         )
 
-    def raise_for_status(self) -> None:
+    def raise_for_status(self) -> "Response":
         """
         Raise the `HTTPStatusError` if one occurred.
         """
@@ -723,7 +723,7 @@ def raise_for_status(self) -> None:
             )
 
         if self.is_success:
-            return
+            return self
 
         if self.has_redirect_location:
             message = (
diff --git a/tests/client/test_async_client.py b/tests/client/test_async_client.py
@@ -122,7 +122,7 @@ async def test_raise_for_status(server):
                     response.raise_for_status()
                 assert exc_info.value.response == response
             else:
-                assert response.raise_for_status() is None  # type: ignore
+                assert response.raise_for_status() is response
 
 
 @pytest.mark.anyio
diff --git a/tests/client/test_client.py b/tests/client/test_client.py
@@ -141,7 +141,7 @@ def test_raise_for_status(server):
                 assert exc_info.value.response == response
                 assert exc_info.value.request.url.path == f"/status/{status_code}"
             else:
-                assert response.raise_for_status() is None  # type: ignore
+                assert response.raise_for_status() is response
 
 
 def test_options(server):

Original file line number	Diff line number	Diff line change
`@@ -711,7 +711,7 @@ def has_redirect_location(self) -> bool:`
`711`	`711`	`and "Location" in self.headers`
`712`	`712`	`)`
`713`	`713`
`714`		`- def raise_for_status(self) -> None:`
	`714`	`+ def raise_for_status(self) -> "Response":`
`715`	`715`	`"""`
`716`	`716`	Raise the `HTTPStatusError` if one occurred.
`717`	`717`	`"""`
`@@ -723,7 +723,7 @@ def raise_for_status(self) -> None:`
`723`	`723`	`)`
`724`	`724`
`725`	`725`	`if self.is_success:`
`726`		`- return`
	`726`	`+ return self`
`727`	`727`
`728`	`728`	`if self.has_redirect_location:`
`729`	`729`	`message = (`