Add the 'proxy' parameter and deprecate 'proxies'.

httpx/_client.py

@@ -36,6 +36,7 @@
     CookieTypes,
     HeaderTypes,
     ProxiesTypes,
+    ProxyTypes,
     QueryParamTypes,
     RequestContent,
     RequestData,
@@ -628,6 +629,7 @@ def __init__(
         cert: typing.Optional[CertTypes] = None,
         http1: bool = True,
         http2: bool = False,
+        proxy: typing.Optional[ProxyTypes] = None,
         proxies: typing.Optional[ProxiesTypes] = None,
         mounts: typing.Optional[typing.Mapping[str, BaseTransport]] = None,
         timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
@@ -666,8 +668,14 @@ def __init__(
                     "Make sure to install httpx using `pip install httpx[http2]`."
                 ) from None
 
+        if proxies:
+            message = "The 'proxies' argument is now deprecated. Use 'proxy' or 'mounts' instead."
+            warnings.warn(message, DeprecationWarning)
+            if proxy:
+                raise RuntimeError("Use either `proxy` or 'proxies', not both.")
+
         allow_env_proxies = trust_env and app is None and transport is None
-        proxy_map = self._get_proxy_map(proxies, allow_env_proxies)
+        proxy_map = self._get_proxy_map(proxies or proxy, allow_env_proxies)
 
         self._transport = self._init_transport(
             verify=verify,
@@ -1353,6 +1361,7 @@ def __init__(
         cert: typing.Optional[CertTypes] = None,
         http1: bool = True,
         http2: bool = False,
+        proxy: typing.Optional[ProxyTypes] = None,
         proxies: typing.Optional[ProxiesTypes] = None,
         mounts: typing.Optional[typing.Mapping[str, AsyncBaseTransport]] = None,
         timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
@@ -1391,8 +1400,14 @@ def __init__(
                     "Make sure to install httpx using `pip install httpx[http2]`."
                 ) from None
 
+        if proxies:
+            message = "The 'proxies' argument is now deprecated. Use 'proxy' or 'mounts' instead."
+            warnings.warn(message, DeprecationWarning)
+            if proxy:
+                raise RuntimeError("Use either `proxy` or 'proxies', not both.")
+
         allow_env_proxies = trust_env and app is None and transport is None
-        proxy_map = self._get_proxy_map(proxies, allow_env_proxies)
+        proxy_map = self._get_proxy_map(proxies or proxy, allow_env_proxies)
 
         self._transport = self._init_transport(
             verify=verify,

httpx/_transports/default.py

@@ -29,6 +29,8 @@
 
 import httpcore
 
+from httpx import URL
+
 from .._config import DEFAULT_LIMITS, Limits, Proxy, create_ssl_context
 from .._exceptions import (
     ConnectError,
@@ -47,7 +49,7 @@
     WriteTimeout,
 )
 from .._models import Request, Response
-from .._types import AsyncByteStream, CertTypes, SyncByteStream, VerifyTypes
+from .._types import AsyncByteStream, CertTypes, ProxyTypes, SyncByteStream, VerifyTypes
 from .base import AsyncBaseTransport, BaseTransport
 
 T = typing.TypeVar("T", bound="HTTPTransport")
@@ -124,13 +126,14 @@ def __init__(
         http2: bool = False,
         limits: Limits = DEFAULT_LIMITS,
         trust_env: bool = True,
-        proxy: typing.Optional[Proxy] = None,
+        proxy: typing.Optional[ProxyTypes] = None,
         uds: typing.Optional[str] = None,
         local_address: typing.Optional[str] = None,
         retries: int = 0,
         socket_options: typing.Optional[typing.Iterable[SOCKET_OPTION]] = None,
     ) -> None:
         ssl_context = create_ssl_context(verify=verify, cert=cert, trust_env=trust_env)
+        proxy = Proxy(url=proxy) if isinstance(proxy, (str, URL)) else proxy
 
         if proxy is None:
             self._pool = httpcore.ConnectionPool(
@@ -263,13 +266,14 @@ def __init__(
         http2: bool = False,
         limits: Limits = DEFAULT_LIMITS,
         trust_env: bool = True,
-        proxy: typing.Optional[Proxy] = None,
+        proxy: typing.Optional[ProxyTypes] = None,
         uds: typing.Optional[str] = None,
         local_address: typing.Optional[str] = None,
         retries: int = 0,
         socket_options: typing.Optional[typing.Iterable[SOCKET_OPTION]] = None,
     ) -> None:
         ssl_context = create_ssl_context(verify=verify, cert=cert, trust_env=trust_env)
+        proxy = Proxy(url=proxy) if isinstance(proxy, (str, URL)) else proxy
 
         if proxy is None:
             self._pool = httpcore.AsyncConnectionPool(

httpx/_types.py

@@ -78,7 +78,8 @@
     Tuple[Optional[float], Optional[float], Optional[float], Optional[float]],
     "Timeout",
 ]
-ProxiesTypes = Union[URLTypes, "Proxy", Dict[URLTypes, Union[None, URLTypes, "Proxy"]]]
+ProxyTypes = Union[URLTypes, "Proxy"]
+ProxiesTypes = Union[URLTypes, ProxyTypes, Dict[URLTypes, Union[None, ProxyTypes]]]
 
 AuthTypes = Union[
     Tuple[Union[str, bytes], Union[str, bytes]],

tests/client/test_proxies.py

@@ -33,7 +33,8 @@ def url_to_origin(url: str) -> httpcore.URL:
     ],
 )
 def test_proxies_parameter(proxies, expected_proxies):
-    client = httpx.Client(proxies=proxies)
+    with pytest.warns(DeprecationWarning):
+        client = httpx.Client(proxies=proxies)
     client_patterns = [p.pattern for p in client._mounts.keys()]
     client_proxies = list(client._mounts.values())
 
@@ -47,15 +48,31 @@ def test_proxies_parameter(proxies, expected_proxies):
     assert len(expected_proxies) == len(client._mounts)
 
 
+def test_socks_proxy_deprecated():
+    url = httpx.URL("http://www.example.com")
+
+    with pytest.warns(DeprecationWarning):
+        client = httpx.Client(proxies="socks5://localhost/")
+    transport = client._transport_for_url(url)
+    assert isinstance(transport, httpx.HTTPTransport)
+    assert isinstance(transport._pool, httpcore.SOCKSProxy)
+
+    with pytest.warns(DeprecationWarning):
+        async_client = httpx.AsyncClient(proxies="socks5://localhost/")
+    async_transport = async_client._transport_for_url(url)
+    assert isinstance(async_transport, httpx.AsyncHTTPTransport)
+    assert isinstance(async_transport._pool, httpcore.AsyncSOCKSProxy)
+
+
 def test_socks_proxy():
     url = httpx.URL("http://www.example.com")
 
-    client = httpx.Client(proxies="socks5://localhost/")
+    client = httpx.Client(proxy="socks5://localhost/")
     transport = client._transport_for_url(url)
     assert isinstance(transport, httpx.HTTPTransport)
     assert isinstance(transport._pool, httpcore.SOCKSProxy)
 
-    async_client = httpx.AsyncClient(proxies="socks5://localhost/")
+    async_client = httpx.AsyncClient(proxy="socks5://localhost/")
     async_transport = async_client._transport_for_url(url)
     assert isinstance(async_transport, httpx.AsyncHTTPTransport)
     assert isinstance(async_transport._pool, httpcore.AsyncSOCKSProxy)
@@ -121,7 +138,12 @@ def test_socks_proxy():
     ],
 )
 def test_transport_for_request(url, proxies, expected):
-    client = httpx.Client(proxies=proxies)
+    if proxies:
+        with pytest.warns(DeprecationWarning):
+            client = httpx.Client(proxies=proxies)
+    else:
+        client = httpx.Client(proxies=proxies)
+
     transport = client._transport_for_url(httpx.URL(url))
 
     if expected is None:
@@ -136,7 +158,8 @@ def test_transport_for_request(url, proxies, expected):
 @pytest.mark.network
 async def test_async_proxy_close():
     try:
-        client = httpx.AsyncClient(proxies={"https://": PROXY_URL})
+        with pytest.warns(DeprecationWarning):
+            client = httpx.AsyncClient(proxies={"https://": PROXY_URL})
         await client.get("http://example.com")
     finally:
         await client.aclose()
@@ -145,15 +168,21 @@ async def test_async_proxy_close():
 @pytest.mark.network
 def test_sync_proxy_close():
     try:
-        client = httpx.Client(proxies={"https://": PROXY_URL})
+        with pytest.warns(DeprecationWarning):
+            client = httpx.Client(proxies={"https://": PROXY_URL})
         client.get("http://example.com")
     finally:
         client.close()
 
 
+def test_unsupported_proxy_scheme_deprecated():
+    with pytest.warns(DeprecationWarning), pytest.raises(ValueError):
+        httpx.Client(proxies="ftp://127.0.0.1")
+
+
 def test_unsupported_proxy_scheme():
     with pytest.raises(ValueError):
-        httpx.Client(proxies="ftp://127.0.0.1")
+        httpx.Client(proxy="ftp://127.0.0.1")
 
 
 @pytest.mark.parametrize(
@@ -279,8 +308,31 @@ def test_proxies_environ(monkeypatch, client_class, url, env, expected):
     ],
 )
 def test_for_deprecated_proxy_params(proxies, is_valid):
-    if not is_valid:
-        with pytest.raises(ValueError):
+    with pytest.warns(DeprecationWarning):
+        if not is_valid:
+            with pytest.raises(ValueError):
+                httpx.Client(proxies=proxies)
+        else:
             httpx.Client(proxies=proxies)
-    else:
-        httpx.Client(proxies=proxies)
+
+
+def test_proxy_and_proxies_together():
+    with pytest.warns(DeprecationWarning), pytest.raises(
+        RuntimeError,
+    ):
+        httpx.Client(proxies={"all://": "http://127.0.0.1"}, proxy="http://127.0.0.1")
+
+    with pytest.warns(DeprecationWarning), pytest.raises(
+        RuntimeError,
+    ):
+        httpx.AsyncClient(
+            proxies={"all://": "http://127.0.0.1"}, proxy="http://127.0.0.1"
+        )
+
+
+def test_proxy_with_mounts():
+    proxy_transport = httpx.HTTPTransport(proxy="http://127.0.0.1")
+    client = httpx.Client(mounts={"http://": proxy_transport})
+
+    transport = client._transport_for_url(httpx.URL("http://example.com"))
+    assert transport == proxy_transport