Drop DEFAULT_RETRIES_CONFIG for None, add disabling retries per-request

docs/advanced.md

@@ -511,6 +511,12 @@ Or enable them on a client instance, which results in the given `retries` being
 httpx.Client(retries=3)
 ```
 
+When using a client with retries enabled, you can still explicitly disable retries for a given request:
+
+```python
+response = client.get("https://example.org", retries=None)
+```
+
 ### Fine-tuning the retries configuration
 
 When enabling retries, the `retries` argument can also be an `httpx.Retries()` instance. It accepts the following arguments:

httpx/api.py

@@ -3,7 +3,6 @@
 from .auth import AuthTypes
 from .client import Client, StreamContextManager
 from .config import (
-    DEFAULT_RETRIES_CONFIG,
     DEFAULT_TIMEOUT_CONFIG,
     CertTypes,
     RetriesTypes,
@@ -33,7 +32,7 @@ def request(
     headers: HeaderTypes = None,
     cookies: CookieTypes = None,
     auth: AuthTypes = None,
-    retries: RetriesTypes = DEFAULT_RETRIES_CONFIG,
+    retries: RetriesTypes = None,
     timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
     allow_redirects: bool = True,
     verify: VerifyTypes = True,
@@ -118,7 +117,7 @@ def stream(
     headers: HeaderTypes = None,
     cookies: CookieTypes = None,
     auth: AuthTypes = None,
-    retries: RetriesTypes = DEFAULT_RETRIES_CONFIG,
+    retries: RetriesTypes = None,
     timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
     allow_redirects: bool = True,
     verify: VerifyTypes = True,
@@ -156,7 +155,7 @@ def get(
     allow_redirects: bool = True,
     cert: CertTypes = None,
     verify: VerifyTypes = True,
-    retries: RetriesTypes = DEFAULT_RETRIES_CONFIG,
+    retries: RetriesTypes = None,
     timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
     trust_env: bool = True,
 ) -> Response:
@@ -194,7 +193,7 @@ def options(
     allow_redirects: bool = True,
     cert: CertTypes = None,
     verify: VerifyTypes = True,
-    retries: RetriesTypes = DEFAULT_RETRIES_CONFIG,
+    retries: RetriesTypes = None,
     timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
     trust_env: bool = True,
 ) -> Response:
@@ -232,7 +231,7 @@ def head(
     allow_redirects: bool = False,  # Note: Differs to usual default.
     cert: CertTypes = None,
     verify: VerifyTypes = True,
-    retries: RetriesTypes = DEFAULT_RETRIES_CONFIG,
+    retries: RetriesTypes = None,
     timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
     trust_env: bool = True,
 ) -> Response:
@@ -275,7 +274,7 @@ def post(
     allow_redirects: bool = True,
     cert: CertTypes = None,
     verify: VerifyTypes = True,
-    retries: RetriesTypes = DEFAULT_RETRIES_CONFIG,
+    retries: RetriesTypes = None,
     timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
     trust_env: bool = True,
 ) -> Response:
@@ -316,7 +315,7 @@ def put(
     allow_redirects: bool = True,
     cert: CertTypes = None,
     verify: VerifyTypes = True,
-    retries: RetriesTypes = DEFAULT_RETRIES_CONFIG,
+    retries: RetriesTypes = None,
     timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
     trust_env: bool = True,
 ) -> Response:
@@ -357,7 +356,7 @@ def patch(
     allow_redirects: bool = True,
     cert: CertTypes = None,
     verify: VerifyTypes = True,
-    retries: RetriesTypes = DEFAULT_RETRIES_CONFIG,
+    retries: RetriesTypes = None,
     timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
     trust_env: bool = True,
 ) -> Response:
@@ -395,7 +394,7 @@ def delete(
     allow_redirects: bool = True,
     cert: CertTypes = None,
     verify: VerifyTypes = True,
-    retries: RetriesTypes = DEFAULT_RETRIES_CONFIG,
+    retries: RetriesTypes = None,
     timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
     trust_env: bool = True,
 ) -> Response:

httpx/client.py

@@ -10,7 +10,6 @@
 from .config import (
     DEFAULT_MAX_REDIRECTS,
     DEFAULT_POOL_LIMITS,
-    DEFAULT_RETRIES_CONFIG,
     DEFAULT_TIMEOUT_CONFIG,
     UNSET,
     CertTypes,
@@ -68,8 +67,8 @@ def __init__(
         params: QueryParamTypes = None,
         headers: HeaderTypes = None,
         cookies: CookieTypes = None,
+        retries: RetriesTypes = None,
         timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
-        retries: RetriesTypes = DEFAULT_RETRIES_CONFIG,
         max_redirects: int = DEFAULT_MAX_REDIRECTS,
         base_url: URLTypes = None,
         trust_env: bool = True,
@@ -86,8 +85,8 @@ def __init__(
         self._params = QueryParams(params)
         self._headers = Headers(headers)
         self._cookies = Cookies(cookies)
-        self.timeout = Timeout(timeout)
         self.retries = Retries(retries)
+        self.timeout = Timeout(timeout)
         self.max_redirects = max_redirects
         self.trust_env = trust_env
         self.netrc = NetRCInfo()
@@ -453,8 +452,8 @@ def __init__(
         verify: VerifyTypes = True,
         cert: CertTypes = None,
         proxies: ProxiesTypes = None,
+        retries: RetriesTypes = None,
         timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
-        retries: RetriesTypes = DEFAULT_RETRIES_CONFIG,
         pool_limits: PoolLimits = DEFAULT_POOL_LIMITS,
         max_redirects: int = DEFAULT_MAX_REDIRECTS,
         base_url: URLTypes = None,
@@ -467,8 +466,8 @@ def __init__(
             params=params,
             headers=headers,
             cookies=cookies,
-            timeout=timeout,
             retries=retries,
+            timeout=timeout,
             max_redirects=max_redirects,
             base_url=base_url,
             trust_env=trust_env,
@@ -633,6 +632,11 @@ def send_handling_retries(
         timeout: Timeout,
         allow_redirects: bool = True,
     ) -> Response:
+        if not retries.limit:
+            return self.send_handling_redirects(
+                request, auth=auth, timeout=timeout, allow_redirects=allow_redirects
+            )
+
         backend = self.backend
         retries_left = retries.limit
         delays = retries.get_delays()
@@ -646,9 +650,10 @@ def send_handling_retries(
                     allow_redirects=allow_redirects,
                 )
             except HTTPError as exc:
-                if not retries.limit or not retries.should_retry_on_exception(exc):
-                    # We shouldn't retry at all in these cases, so let's re-raise
-                    # immediately to avoid polluting logs or the exception stack.
+                if not retries.should_retry_on_exception(exc):
+                    # Even if we have retries left, we're told to not even consider
+                    # retrying in this case. So let's re-raise immediately to avoid
+                    # polluting logs or the exception stack.
                     raise
 
                 logger.debug(f"HTTP Request failed: {exc!r}")
@@ -1022,8 +1027,8 @@ def __init__(
         cert: CertTypes = None,
         http2: bool = False,
         proxies: ProxiesTypes = None,
+        retries: RetriesTypes = None,
         timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
-        retries: RetriesTypes = DEFAULT_RETRIES_CONFIG,
         pool_limits: PoolLimits = DEFAULT_POOL_LIMITS,
         max_redirects: int = DEFAULT_MAX_REDIRECTS,
         base_url: URLTypes = None,
@@ -1038,8 +1043,8 @@ def __init__(
             params=params,
             headers=headers,
             cookies=cookies,
-            timeout=timeout,
             retries=retries,
+            timeout=timeout,
             max_redirects=max_redirects,
             base_url=base_url,
             trust_env=trust_env,
@@ -1224,6 +1229,11 @@ async def send_handling_retries(
         timeout: Timeout,
         allow_redirects: bool = True,
     ) -> Response:
+        if not retries.limit:
+            return await self.send_handling_redirects(
+                request, auth=auth, timeout=timeout, allow_redirects=allow_redirects
+            )
+
         backend = lookup_backend()
 
         retries_left = retries.limit
@@ -1238,9 +1248,10 @@ async def send_handling_retries(
                     allow_redirects=allow_redirects,
                 )
             except HTTPError as exc:
-                if not retries.limit or not retries.should_retry_on_exception(exc):
-                    # We shouldn't retry at all in these cases, so let's re-raise
-                    # immediately to avoid polluting logs or the exception stack.
+                if not retries.should_retry_on_exception(exc):
+                    # Even if we have retries left, we're told to not even consider
+                    # retrying in this case. So let's re-raise immediately to avoid
+                    # polluting logs or the exception stack.
                     raise
 
                 logger.debug(f"HTTP Request failed: {exc!r}")

httpx/config.py

@@ -19,7 +19,7 @@
 ProxiesTypes = typing.Union[
     URLTypes, "Proxy", typing.Dict[URLTypes, typing.Union[URLTypes, "Proxy"]]
 ]
-RetriesTypes = typing.Union[int, "Retries"]
+RetriesTypes = typing.Union[None, int, "Retries"]
 
 
 DEFAULT_CIPHERS = ":".join(
@@ -372,8 +372,12 @@ class Retries:
         ("HEAD", "GET", "PUT", "DELETE", "OPTIONS", "TRACE")
     )
 
-    def __init__(self, retries: RetriesTypes, *, backoff_factor: float = None) -> None:
-        if isinstance(retries, int):
+    def __init__(
+        self, retries: RetriesTypes = None, *, backoff_factor: float = None
+    ) -> None:
+        if retries is None:
+            limit = 0
+        elif isinstance(retries, int):
             limit = retries
         else:
             assert isinstance(retries, Retries)
@@ -423,6 +427,5 @@ def get_delays(self) -> typing.Iterator[float]:
 
 
 DEFAULT_TIMEOUT_CONFIG = Timeout(timeout=5.0)
-DEFAULT_RETRIES_CONFIG = Retries(0, backoff_factor=0.2)
 DEFAULT_POOL_LIMITS = PoolLimits(soft_limit=10, hard_limit=100)
 DEFAULT_MAX_REDIRECTS = 20

tests/client/test_retries.py

@@ -86,7 +86,7 @@ async def test_no_retries() -> None:
 
 
 @pytest.mark.usefixtures("async_environment")
-async def test_retries() -> None:
+async def test_client_retries() -> None:
     client = httpx.AsyncClient(dispatch=MockDispatch(succeed_after=3), retries=3)
 
     response = await client.get("https://example.com")
@@ -102,6 +102,17 @@ async def test_retries() -> None:
     assert response.status_code == 200
 
 
+@pytest.mark.usefixtures("async_environment")
+async def test_request_retries() -> None:
+    client = httpx.AsyncClient(dispatch=MockDispatch(succeed_after=3))
+    response = await client.get("https://example.com", retries=3)
+    assert response.status_code == 200
+
+    client = httpx.AsyncClient(dispatch=MockDispatch(succeed_after=3), retries=3)
+    with pytest.raises(httpx.ConnectTimeout):
+        await client.get("https://example.com/connect_timeout", retries=None)
+
+
 @pytest.mark.usefixtures("async_environment")
 async def test_too_many_retries() -> None:
     client = httpx.AsyncClient(dispatch=MockDispatch(succeed_after=2), retries=1)