Edited documentation about proxy-envs usage (#404) (#1257)

* Edited documentation about proxy-envs usage (#404)

* PR review (#404)

Co-authored-by: Florimond Manca <florimond.manca@gmail.com>
* PR review (#404)

Co-authored-by: Florimond Manca <florimond.manca@gmail.com>
* Fix typo

Co-authored-by: Florimond Manca <florimond.manca@gmail.com>

diff --git a/docs/environment_variables.md b/docs/environment_variables.md
index 9ffa68480d7c605105cdd48f94694e34ab8ea837..252ab66c7455aeb2919154b98e5065766d6ab97a 100644 (file)
--- a/docs/environment_variables.md
+++ b/docs/environment_variables.md
@@ -134,17 +134,46 @@ Example:
 SSL_CERT_DIR=/path/to/ca-certs/ python -c "import httpx; httpx.get('https://example.com')"
 ```
 
-## `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`
+## Proxies
+
+The environment variables documented below are used as a convention by various HTTP tooling, including:
+
+* [cURL](https://github.com/curl/curl/blob/master/docs/MANUAL.md#environment-variables)
+* [requests](https://github.com/psf/requests/blob/master/docs/user/advanced.rst#proxies)
+
+For more information on using proxies in HTTPX, see [HTTP Proxying](/advanced/#http-proxying).
+
+### `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.
+`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` set the proxy to be used for `http`, `https`, or all requests respectively.
 
 ```bash
-export HTTP_PROXY=http://127.0.0.1:3080
+export HTTP_PROXY=http://my-external-proxy.com:1234
 
 # This request will be sent through the proxy
 python -c "import httpx; httpx.get('http://example.com')"
+
+# This request will be sent directly, as we set `trust_env=False`
+python -c "import httpx; httpx.get('http://example.com', trust_env=False)"
+
 ```
 
-For more information on using proxies in HTTPX, see [HTTP Proxying](/advanced/#http-proxying).
+### `NO_PROXY`
+
+Valid values: a comma-separated list of hostnames/urls
+
+`NO_PROXY` disables the proxy for specific urls
+
+```bash
+export HTTP_PROXY=http://my-external-proxy.com:1234
+export NO_PROXY=http://127.0.0.1,python-httpx.org
+
+# As in the previous example, this request will be sent through the proxy
+python -c "import httpx; httpx.get('http://example.com')"
+
+# These requests will be sent directly, bypassing the proxy
+python -c "import httpx; httpx.get('http://127.0.0.1:5000/my-api')"
+python -c "import httpx; httpx.get('https://www.python-httpx.org')"
+```