Updated proxies documentation

1 files changed, 28 insertions, 20 deletions

diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index 54cebaaa..d930a68d 100644
--- a/docs/user/advanced.rst
+++ b/docs/user/advanced.rst
@@ -590,7 +590,7 @@ If you need to use a proxy, you can configure individual requests with the
     requests.get('http://example.org', proxies=proxies)
 
 Alternatively you can configure it once for an entire
-:class:`Session <requests.Session>`, either manually::
+:class:`Session <requests.Session>`::
 
     import requests
 
@@ -603,19 +603,12 @@ Alternatively you can configure it once for an entire
 
     session.get('http://example.org')
 
-or with the helper method :func:`set_http_proxy <requests.Session.set_http_proxy>`::
-
-    import requests
-
-    session = request.Session()
-    session.set_http_proxy(http_url='http://10.10.1.10:3128', https_url='http://10.10.1.10:1080')
-
-    session.get('http://example.org')
-
-You can also configure proxies by setting the environment variables
-``HTTP_PROXY``, ``HTTPS_PROXY``, ``NO_PROXY`` and ``CURL_CA_BUNDLE``.
-
-::
+When the proxies configuration is not overridden in python as shown above,
+by default Requests relies on the proxy configuration defined by standard
+environment variables ``http_proxy``, ``https_proxy``, ``no_proxy`` and
+``curl_ca_bundle``. Uppercase variants of these variables are also supported.
+You can therefore set them to configure Requests (only set the ones relevant
+to your needs)::
 
     $ export HTTP_PROXY="http://10.10.1.10:3128"
     $ export HTTPS_PROXY="http://10.10.1.10:1080"
@@ -624,9 +617,17 @@ You can also configure proxies by setting the environment variables
     >>> import requests
     >>> requests.get('http://example.org')
 
-To use HTTP Basic Auth with your proxy, use the `http://user:password@host/` syntax::
+To use HTTP Basic Auth with your proxy, use the `http://user:password@host/`
+syntax in any of the above configuration entries::
+
+    $ export HTTPS_PROXY="http://user:pass@10.10.1.10:1080"
+
+    $ python
+    >>> proxies = {'http': 'http://user:pass@10.10.1.10:3128/'}
 
-    proxies = {'http': 'http://user:pass@10.10.1.10:3128/'}
+.. warning:: Storing sensitive username and password information in an
+   environment variable or a version-controled file is a security risk and is
+   highly discouraged.
 
 To give a proxy for a specific scheme and host, use the
 `scheme://hostname` form for the key.  This will match for
@@ -638,15 +639,22 @@ any request to the given scheme and exact hostname.
 
 Note that proxy URLs must include the scheme.
 
-Finally, note that using a proxy for https connections typically requires your local machine to trust the
-proxy's root certificate. By default the list of certificates trusted by Requests can be found with::
+Finally, note that using a proxy for https connections typically requires your
+local machine to trust the proxy's root certificate. By default the list of
+certificates trusted by Requests can be found with::
 
     from requests.utils import DEFAULT_CA_BUNDLE_PATH
     print(DEFAULT_CA_BUNDLE_PATH)
 
-You override this default certificate bundle by setting the standard ``CURL_CA_BUNDLE`` environment variable
-to another file path.
+You override this default certificate bundle by setting the standard
+``curl_ca_bundle`` environment variable to another file path::
 
+    $ export curl_ca_bundle="/usr/local/myproxy_info/cacert.pem"
+    $ export https_proxy="http://10.10.1.10:1080"
+
+    $ python
+    >>> import requests
+    >>> requests.get('https://example.org')
 
 SOCKS
 ^^^^^