merge patched into master

3 files changed, 68 insertions, 18 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 78d3601..29e7ad7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -288,7 +288,7 @@ You may also stream your response and get data as they come (e.g. when using
 
 ::
 
-    >>> from urllib3 import PoolManager
+    >>> import urllib3
     >>> http = urllib3.PoolManager()
 
     >>> r = http.request("GET", "http://httpbin.org/stream/3")
diff --git a/docs/managers.rst b/docs/managers.rst
index 6c841b7..825e2f4 100644
--- a/docs/managers.rst
+++ b/docs/managers.rst
@@ -70,6 +70,17 @@ connections and individual per-server:port
 :class:`~urllib3.connectionpool.HTTPSConnectionPool` instances for tunnelled
 HTTPS connections.
 
+Example using proxy authentication:
+
+::
+
+	>>> headers = urllib3.make_headers(proxy_basic_auth='myusername:mypassword')
+	>>> proxy = urllib3.ProxyManager('http://localhost:3128', proxy_headers=headers)
+	>>> r = proxy.request('GET', 'http://example.com/')
+	>>> r.status
+	200
+
+
 API
 ---
     .. autoclass:: ProxyManager
diff --git a/docs/security.rst b/docs/security.rst
index 0f5aa1c..48de053 100644
--- a/docs/security.rst
+++ b/docs/security.rst
@@ -185,21 +185,8 @@ Unverified HTTPS requests will trigger a warning via Python's ``warnings`` modul
 This would be a great time to enable HTTPS verification:
 :ref:`certifi-with-urllib3`.
 
-If you know what you're doing and would like to disable this and other warnings,
-you can use :func:`~urllib3.disable_warnings`::
-
-    import urllib3
-    urllib3.disable_warnings()
+For info about disabling warnings, see `Disabling Warnings`_.
 
-Making unverified HTTPS requests is strongly discouraged. ˙ ͜ʟ˙
-
-Alternatively, if you are using Python's ``logging`` module, you can capture the
-warnings to your own log::
-
-	logging.captureWarnings(True)
-
-Capturing the warnings to your own log is much preferred over simply disabling
-the warnings.
 
 InsecurePlatformWarning
 -----------------------
@@ -216,6 +203,58 @@ 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 know what you are doing and would like to disable this and other
-warnings, please consult the :ref:`insecurerequestwarning` section for
-instructions on how to handle the warnings.
+For info about disabling warnings, see `Disabling Warnings`_.
+
+
+SNIMissingWarning
+-----------------
+
+.. versionadded:: 1.13
+
+Certain Python distributions (specifically, versions of Python earlier than
+2.7.9) and older OpenSSLs have restrictions that prevent them from using the
+SNI (Server Name Indication) extension. This can cause unexpected behaviour
+when making some HTTPS requests, usually causing the server to present the a
+TLS certificate that is not valid for the website you're trying to access.
+
+If you encounter this warning, it is strongly recommended that you upgrade
+to a newer Python version, or that you use pyOpenSSL as described in the
+:ref:`pyopenssl` section.
+
+For info about disabling warnings, see `Disabling Warnings`_.
+
+
+Disabling Warnings
+------------------
+
+Making unverified HTTPS requests is strongly discouraged. ˙ ͜ʟ˙
+
+But if you understand the ramifications and still want to do it...
+
+Within the code
++++++++++++++++
+
+If you know what you're doing and would like to disable all ``urllib3`` warnings,
+you can use :func:`~urllib3.disable_warnings`::
+
+    import urllib3
+    urllib3.disable_warnings()
+
+Alternatively, if you are using Python's ``logging`` module, you can capture the
+warnings to your own log::
+
+	logging.captureWarnings(True)
+
+Capturing the warnings to your own log is much preferred over simply disabling
+the warnings.
+
+Without modifying code
+++++++++++++++++++++++
+
+If you are using a program that uses ``urllib3`` and don't want to change the
+code, you can suppress warnings by setting the ``PYTHONWARNINGS`` environment
+variable in Python 2.7+ or by using the ``-W`` flag with the Python
+interpreter (see `docs
+<https://docs.python.org/2/using/cmdline.html#cmdoption-W>`_), such as::
+
+    PYTHONWARNINGS="ignore:Unverified HTTPS request" ./do-insecure-request.py