Merge branch 'encode:master' into drop-python37-support

Author: Pliner

CHANGELOG.md

@@ -13,6 +13,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
 

docs/advanced.md

@@ -426,6 +426,38 @@ with tempfile.NamedTemporaryFile() as download_file:
 
 ![rich progress bar](img/rich-progress.gif)
 
+## Monitoring upload progress
+
+If you need to monitor upload progress of large responses, you can use request content generator streaming.
+
+For example, showing a progress bar using the [`tqdm`](https://github.com/tqdm/tqdm) library.
+
+```python
+import io
+import random
+
+import httpx
+from tqdm import tqdm
+
+
+def gen():
+    """
+    this is a complete example with generated random bytes.
+    you can replace `io.BytesIO` with real file object.
+    """
+    total = 32 * 1024 * 1024  # 32m
+    with tqdm(ascii=True, unit_scale=True, unit='B', unit_divisor=1024, total=total) as bar:
+        with io.BytesIO(random.randbytes(total)) as f:
+            while data := f.read(1024):
+                yield data
+                bar.update(len(data))
+
+
+httpx.post("https://httpbin.org/post", content=gen())
+```
+
+![tqdm progress bar](img/tqdm-progress.gif)
+
 ## .netrc Support
 
 HTTPX can be configured to use [a `.netrc` config file](https://everything.curl.dev/usingcurl/netrc) for authentication.

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**

docs/quickstart.md

@@ -285,15 +285,22 @@ Traceback (most recent call last):
   File "/Users/tomchristie/GitHub/encode/httpcore/httpx/models.py", line 837, in raise_for_status
     raise HTTPStatusError(message, response=self)
 httpx._exceptions.HTTPStatusError: 404 Client Error: Not Found for url: https://httpbin.org/status/404
-For more information check: https://httpstatuses.com/404
+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.
@@ -367,7 +374,7 @@ If you're using streaming responses in any of these ways then the `response.cont
 
 ```pycon
 >>> with httpx.stream("GET", "https://www.example.com") as r:
-...     if r.headers['Content-Length'] < TOO_LONG:
+...     if int(r.headers['Content-Length']) < TOO_LONG:
 ...         r.read()
 ...         print(r.text)
 ```

docs/third_party_packages.md

@@ -6,6 +6,12 @@ As HTTPX usage grows, there is an expanding community of developers building too
 
 <!-- NOTE: this list is in alphabetical order. -->
 
+### Hishel
+
+[GitHub](https://github.com/karosis88/hishel) - [Documentation](https://karosis88.github.io/hishel/)
+
+An elegant HTTP Cache implementation for HTTPX and HTTP Core.
+
 ### Authlib
 
 [GitHub](https://github.com/lepture/authlib) - [Documentation](https://docs.authlib.org/en/latest/)

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,18 +723,18 @@ def raise_for_status(self) -> None:
             )
 
         if self.is_success:
-            return
+            return self
 
         if self.has_redirect_location:
             message = (
                 "{error_type} '{0.status_code} {0.reason_phrase}' for url '{0.url}'\n"
                 "Redirect location: '{0.headers[location]}'\n"
-                "For more information check: https://httpstatuses.com/{0.status_code}"
+                "For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/{0.status_code}"
             )
         else:
             message = (
                 "{error_type} '{0.status_code} {0.reason_phrase}' for url '{0.url}'\n"
-                "For more information check: https://httpstatuses.com/{0.status_code}"
+                "For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/{0.status_code}"
             )
 
         status_class = self.status_code // 100

requirements.txt

@@ -12,20 +12,20 @@ types-chardet==5.0.4.5
 # Documentation
 mkdocs==1.4.3
 mkautodoc==0.2.0
-mkdocs-material==9.1.15
+mkdocs-material==9.1.17
 
 # Packaging
 build==0.10.0
 twine==4.0.2
 
 # Tests & Linting
 black==23.3.0
-coverage[toml]==7.2.2
-cryptography==41.0.0
-mypy==1.3.0
+coverage[toml]==7.2.7
+cryptography==41.0.3
+mypy==1.4.1
 types-certifi==2021.10.8.2
-pytest==7.3.1
-ruff==0.0.260
+pytest==7.4.0
+ruff==0.0.275
 trio==0.22.0
 trio-typing==0.8.0
 trustme==1.0.0

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

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):

tests/models/test_responses.py

@@ -102,7 +102,7 @@ def test_raise_for_status():
         response.raise_for_status()
     assert str(exc_info.value) == (
         "Informational response '101 Switching Protocols' for url 'https://example.org'\n"
-        "For more information check: https://httpstatuses.com/101"
+        "For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/101"
     )
 
     # 3xx status codes are redirections.
@@ -114,7 +114,7 @@ def test_raise_for_status():
     assert str(exc_info.value) == (
         "Redirect response '303 See Other' for url 'https://example.org'\n"
         "Redirect location: 'https://other.org'\n"
-        "For more information check: https://httpstatuses.com/303"
+        "For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/303"
     )
 
     # 4xx status codes are a client error.
@@ -125,7 +125,7 @@ def test_raise_for_status():
         response.raise_for_status()
     assert str(exc_info.value) == (
         "Client error '403 Forbidden' for url 'https://example.org'\n"
-        "For more information check: https://httpstatuses.com/403"
+        "For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403"
     )
 
     # 5xx status codes are a server error.
@@ -136,7 +136,7 @@ def test_raise_for_status():
         response.raise_for_status()
     assert str(exc_info.value) == (
         "Server error '500 Internal Server Error' for url 'https://example.org'\n"
-        "For more information check: https://httpstatuses.com/500"
+        "For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500"
     )
 
     # Calling .raise_for_status without setting a request instance is