Proxy Configurations

docs/advanced.md

@@ -111,3 +111,52 @@ password example-password
 
 ...
 ```
+
+## HTTP Proxying
+
+HTTPX supports setting up proxies the same way that Requests does via the `proxies` parameter.
+For example to forward all HTTP traffic to `http://127.0.0.1:3080` and all HTTPS traffic
+to `http://127.0.0.1:3081` your `proxies` config would look like this:
+
+```python
+>>> client = httpx.Client(proxies={
+  "http": "http://127.0.0.1:3080",
+  "https": "http://127.0.0.1:3081"
+})
+```
+
+Proxies can be configured for a specific scheme and host, all schemes of a host,
+all hosts for a scheme, or for all requests. When determining which proxy configuration
+to use for a given request this same order is used.
+
+```python
+>>> client = httpx.Client(proxies={
+    "http://example.com":  "...",  # Host+Scheme
+    "all://example.com":  "...",  # Host
+    "http": "...",  # Scheme
+    "all": "...",  # All
+})
+>>> client = httpx.Client(proxies="...")  # Shortcut for 'all'
+```
+
+!!! warning
+    To make sure that proxies cannot read your traffic,
+    and even if the proxy_url uses HTTPS, it is recommended to
+    use HTTPS and tunnel requests if possible.
+
+By default `HTTPProxy` will operate as a forwarding proxy for `http://...` requests
+and will establish a `CONNECT` TCP tunnel for `https://` requests. This doesn't change
+regardless of the `proxy_url` being `http` or `https`.
+
+Proxies can be configured to have different behavior such as forwarding or tunneling all requests:
+
+```python
+proxy = httpx.HTTPProxy(
+    proxy_url="https://127.0.0.1",
+    proxy_mode=httpx.HTTPProxyMode.TUNNEL_ONLY
+)
+client = httpx.Client(proxies=proxy)
+
+# This request will be tunnelled instead of forwarded.
+client.get("http://example.com")
+```

docs/api.md

@@ -8,14 +8,14 @@
     enable HTTP/2 and connection pooling for more efficient and
     long-lived connections.
 
-* `get(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `options(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `head(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `post(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `put(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `patch(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `delete(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `request(method, url, [data], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
+* `get(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `options(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `head(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `post(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `put(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `patch(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `delete(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `request(method, url, [data], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
 * `build_request(method, url, [data], [files], [json], [params], [headers], [cookies])`
 
 ## `Client`
@@ -30,16 +30,16 @@
 * `def __init__([auth], [headers], [cookies], [verify], [cert], [timeout], [pool_limits], [max_redirects], [app], [dispatch])`
 * `.headers` - **Headers**
 * `.cookies` - **Cookies**
-* `def .get(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `def .options(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `def .head(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `def .post(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `def .put(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `def .patch(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `def .delete(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
-* `def .request(method, url, [data], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
+* `def .get(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `def .options(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `def .head(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `def .post(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `def .put(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `def .patch(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `def .delete(url, [data], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
+* `def .request(method, url, [data], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
 * `def .build_request(method, url, [data], [files], [json], [params], [headers], [cookies])`
-* `def .send(request, [stream], [allow_redirects], [verify], [cert], [timeout])`
+* `def .send(request, [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
 * `def .close()`
 
 ## `Response`

docs/environment_variables.md

@@ -79,3 +79,17 @@ SERVER_TRAFFIC_SECRET_0 XXXX
 CLIENT_HANDSHAKE_TRAFFIC_SECRET XXXX
 CLIENT_TRAFFIC_SECRET_0 XXXX
 ```
+
+`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`
+----------------------------------------
+
+Valid values: A URL to a proxy
+
+Sets the proxy to be used for `http`, `https`, or all requests respectively.
+
+```bash
+export HTTP_PROXY=http://127.0.0.1:3080
+
+# This request will be sent through the proxy
+python -c "import httpx; httpx.get('http://example.com')"
+```

httpx/api.py

@@ -6,6 +6,7 @@
     AuthTypes,
     CookieTypes,
     HeaderTypes,
+    ProxiesTypes,
     QueryParamTypes,
     RequestData,
     RequestFiles,
@@ -31,6 +32,7 @@ def request(
     verify: VerifyTypes = True,
     stream: bool = False,
     trust_env: bool = None,
+    proxies: ProxiesTypes = None,
 ) -> Response:
     with Client(http_versions=["HTTP/1.1"]) as client:
         return client.request(
@@ -65,6 +67,7 @@ def get(
     verify: VerifyTypes = True,
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
+    proxies: ProxiesTypes = None,
 ) -> Response:
     return request(
         "GET",
@@ -95,6 +98,7 @@ def options(
     verify: VerifyTypes = True,
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
+    proxies: ProxiesTypes = None,
 ) -> Response:
     return request(
         "OPTIONS",
@@ -125,6 +129,7 @@ def head(
     verify: VerifyTypes = True,
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
+    proxies: ProxiesTypes = None,
 ) -> Response:
     return request(
         "HEAD",
@@ -158,6 +163,7 @@ def post(
     verify: VerifyTypes = True,
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
+    proxies: ProxiesTypes = None,
 ) -> Response:
     return request(
         "POST",
@@ -194,6 +200,7 @@ def put(
     verify: VerifyTypes = True,
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
+    proxies: ProxiesTypes = None,
 ) -> Response:
     return request(
         "PUT",
@@ -230,6 +237,7 @@ def patch(
     verify: VerifyTypes = True,
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
+    proxies: ProxiesTypes = None,
 ) -> Response:
     return request(
         "PATCH",
@@ -266,6 +274,7 @@ def delete(
     verify: VerifyTypes = True,
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
+    proxies: ProxiesTypes = None,
 ) -> Response:
     return request(
         "DELETE",