Make `raise_for_status` chainable (#2776)

* merge upstream

* lint

* Update test_async_client.py

* update docs

* add example

* Update docs/quickstart.md

Co-authored-by: Tom Christie <tom@tomchristie.com>
* Update CHANGELOG.md

Co-authored-by: Tom Christie <tom@tomchristie.com>
* Update docs/quickstart.md

Co-authored-by: Tom Christie <tom@tomchristie.com>
---------

Co-authored-by: Tom Christie <tom@tomchristie.com>

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4942c9c9a5e3afbc95109a105bfe088fd27f9c46..3d5ea6d2fe6fa3fe61675d84758671bcd2d00703 100644 (file)
--- 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
index ca5c0ba3c987747339c87febfd80831ed216ca9a..3f9878c708f8accd47fcdcfe53fbbc7bc2cb7123 100644 (file)
--- 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
index 1152a14bd36ae60c7e3ba140fbbb991cbc87bd62..068547ffc99518d81e5b9d6f02dd47b03a907f81 100644 (file)
--- 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
index 708aa2af7e5fbb91f23a918338150075c830f4b6..5af5c5d23c4d9cd27c62edee5d0eee7283872f5c 100644 (file)
--- a/httpx/_models.py
+++ b/httpx/_models.py
@@ -711,7 +711,7 @@ class Response:
             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 @@ class Response:
             )
 
         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
index 7fa9a77948377a35ad316d634457c6a2d8e54bd1..cc19e93d4113f6f8b22b7f7478a66d212077d018 100644 (file)
--- 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
index 268cd106899674883814d3650cc452931a2146e5..b8245288ad8b1b599a605ccc265c56837e86e6b6 100644 (file)
--- 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):