Merging new release version: 1.141.14

3 files changed, 63 insertions, 7 deletions

diff --git a/docs/contrib.rst b/docs/contrib.rst
index 5a88f8e9..03cc63bf 100644
--- a/docs/contrib.rst
+++ b/docs/contrib.rst
@@ -4,7 +4,7 @@ Contrib Modules
 ===============
 
 These modules implement various extra features, that may not be ready for
-prime time.
+prime time or that require optional third-party dependencies.
 
 .. _contrib-pyopenssl:
 
@@ -16,7 +16,7 @@ SNI-support for Python 2
 
 .. _gae:
 
-Google App Engine 
+Google App Engine
 -----------------
 
 The :mod:`urllib3.contrib.appengine` module provides a pool manager that
@@ -45,8 +45,62 @@ There are `limitations <https://cloud.google.com/appengine/docs/python/urlfetch/
 
 1. You can use :class:`AppEngineManager` with URLFetch. URLFetch is cost-effective in many circumstances as long as your usage is within the limitations.
 2. You can use a normal :class:`PoolManager` by enabling sockets. Sockets also have `limitations and restrictions <https://cloud.google.com/appengine/docs/python/sockets/#limitations-and-restrictions>`_ and have a lower free quota than URLFetch. To use sockets, be sure to specify the following in your ``app.yaml``::
-    
+
     env_variables:
         GAE_USE_SOCKETS_HTTPLIB : 'true'
 
 3. If you are using `Managed VMs <https://cloud.google.com/appengine/docs/managed-vms/>`_, you can use the standard :class:`PoolManager` without any configuration or special environment variables.
+
+
+SOCKS Proxies
+-------------
+
+.. versionadded:: 1.14.0
+
+The :mod:`urllib3.contrib.socks` module enables urllib3 to work with proxies
+that use either the SOCKS4 or SOCKS5 protocols. These proxies are common in
+environments that want to allow generic TCP/UDP traffic through their borders,
+but don't want unrestricted traffic flows.
+
+To use it, either install ``PySocks`` or install urllib3 with the ``socks``
+extra, like so:
+
+.. code-block:: bash
+
+    $ pip install urllib3[socks]
+
+If you have already got urllib3 1.14.0 or later installed, run:
+
+.. code-block:: bash
+
+    $ pip install -U urllib3[socks]
+
+The SOCKS module provides a
+:class:`SOCKSProxyManager <urllib3.contrib.socks.SOCKSProxyManager>` that can
+be used when SOCKS support is required. This class behaves very much like a
+standard :class:`ProxyManager <urllib3.poolmanager.ProxyManager>`, but allows
+the use of a SOCKS proxy instead.
+
+Using it is simple. For example, with a SOCKS5 proxy running on the local
+machine, listening on port 8889:
+
+.. code-block:: python
+
+    from urllib3.contrib.socks import SOCKSProxyManager
+
+    http = SOCKSProxyManager('socks5://localhost:8889/')
+    r = http.request('GET', 'https://www.google.com/')
+
+The SOCKS implementation supports the full range of urllib3 features. It also
+supports the following SOCKS features:
+
+- SOCKS4
+- SOCKS4a
+- SOCKS5
+- Usernames and passwords for the SOCKS proxy
+
+The SOCKS module does have the following limitations:
+
+- No support for contacting a SOCKS proxy via IPv6.
+- No support for reaching websites via a literal IPv6 address: domain names
+  must be used.
diff --git a/docs/index.rst b/docs/index.rst
index 29e7ad7a..b2fb96e2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -327,7 +327,7 @@ Contrib Modules
 ---------------
 
 These modules implement various extra features, that may not be ready for
-prime time.
+prime time or that require optional third-party dependencies.
 
 * :ref:`contrib-modules`
 
diff --git a/docs/security.rst b/docs/security.rst
index 48de053e..6ebc9413 100644
--- a/docs/security.rst
+++ b/docs/security.rst
@@ -199,9 +199,11 @@ have restrictions in their ``ssl`` module that limit the configuration that
 succeed on more featureful platforms to fail, and can cause certain security
 features to be unavailable.
 
-If you encounter this warning, it is strongly recommended you upgrade to a
-newer Python version, or that you use pyOpenSSL as described in the
-:ref:`pyopenssl` section.
+If you encounter this warning, it is strongly recommended you:
+
+- upgrade to a newer Python version
+- upgrade ``ndg-httpsclient`` with ``pip install --upgrade ndg-httpsclient``
+- use pyOpenSSL as described in the :ref:`pyopenssl` section
 
 For info about disabling warnings, see `Disabling Warnings`_.