Imported Upstream version 1.10.4

4 files changed, 95 insertions, 5 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 1fc8a9c..81ac2d8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,6 +11,7 @@ urllib3 Documentation
    helpers
    collections
    contrib
+   security
 
 
 Highlights
@@ -257,6 +258,35 @@ disabled individually.
 See the :class:`~urllib3.util.retry.Retry` definition for more details.
 
 
+Stream
+------
+
+You may also stream your response and get data as they come (e.g. when using
+``transfer-encoding: chunked``). In this case, method
+:func:`~urllib3.response.HTTPResponse.stream` will return generator.
+
+::
+
+    >>> from urllib3 import PoolManager
+    >>> http = urllib3.PoolManager()
+
+    >>> r = http.request("GET", "http://httpbin.org/stream/3")
+    >>> r.getheader("transfer-encoding")
+    'chunked'
+
+    >>> for chunk in r.stream():
+    ... print chunk
+    {"url": "http://httpbin.org/stream/3", ..., "id": 0, ...}
+    {"url": "http://httpbin.org/stream/3", ..., "id": 1, ...}
+    {"url": "http://httpbin.org/stream/3", ..., "id": 2, ...}
+    >>> r.closed
+    True
+
+Completely consuming the stream will auto-close the response and release
+the connection back to the pool. If you're only partially consuming the
+consuming a stream, make sure to manually call ``r.close()`` on the
+response.
+
 Foundation
 ----------
 
diff --git a/docs/managers.rst b/docs/managers.rst
index f9cab03..6c841b7 100644
--- a/docs/managers.rst
+++ b/docs/managers.rst
@@ -36,9 +36,23 @@ pools. That is, if you set the PoolManager ``num_pools`` to 10, then after
 making requests to 11 or more different hosts, the least recently used pools
 will be cleaned up eventually.
 
-Cleanup of stale pools does not happen immediately. You can read more about the
-implementation and the various adjustable variables within
-:class:`~urllib3._collections.RecentlyUsedContainer`.
+Cleanup of stale pools does not happen immediately but can be forced when used 
+as a context manager.
+
+.. doctest ::
+    
+    >>> from urllib3 import PoolManager
+    >>> with PoolManager(10) as manager:
+    ...     r = manager.request('GET', 'http://example.com')
+    ...     r = manager.request('GET', 'http://httpbin.org/')
+    ...     len(manager.pools)
+    ...
+    2
+    >>> len(manager.pools)
+    0
+
+You can read more about the implementation and the various adjustable variables 
+within :class:`~urllib3._collections.RecentlyUsedContainer`.
 
 API
 ---
diff --git a/docs/pools.rst b/docs/pools.rst
index 63cb7d1..9cc2be9 100644
--- a/docs/pools.rst
+++ b/docs/pools.rst
@@ -33,7 +33,22 @@ If you need to make requests to the same host repeatedly, then you should use a
 By default, the pool will cache just one connection. If you're planning on using
 such a pool in a multithreaded environment, you should set the ``maxsize`` of
 the pool to a higher number, such as the number of threads. You can also control
-many other variables like timeout, blocking, and default headers.
+many other variables like timeout, blocking, and default headers. 
+
+A ConnectionPool can be used as a context manager to automatically clear the 
+pool after usage. 
+
+.. doctest ::
+
+    >>> from urllib3 import HTTPConnectionPool
+    >>> with HTTPConnectionPool('ajax.googleapis.com', maxsize=1) as pool:
+    ...     r = pool.request('GET', '/ajax/services/search/web',
+    ...                      fields={'q': 'urllib3', 'v': '1.0'})
+    ...     print(pool.pool)
+    ... 
+    <queue.LifoQueue object at 0x7f67367dfcf8>
+    >>> print(pool.pool)
+    None
 
 Helpers
 -------
diff --git a/docs/security.rst b/docs/security.rst
index 0566737..881730e 100644
--- a/docs/security.rst
+++ b/docs/security.rst
@@ -111,6 +111,8 @@ Once you find your root certificate file::
         ...
 
 
+.. _pyopenssl:
+
 OpenSSL / PyOpenSSL
 -------------------
 
@@ -137,12 +139,14 @@ Now you can continue using urllib3 as you normally would.
 For more details, check the :mod:`~urllib3.contrib.pyopenssl` module.
 
 
+.. _insecurerequestwarning:
+
 InsecureRequestWarning
 ----------------------
 
 .. versionadded:: 1.9
 
-Unverified HTTPS requests will trigger a warning::
+Unverified HTTPS requests will trigger a warning via Python's ``warnings`` module::
 
     urllib3/connectionpool.py:736: InsecureRequestWarning: Unverified HTTPS
     request is being made. Adding certificate verification is strongly advised.
@@ -158,3 +162,30 @@ you can use :func:`~urllib3.disable_warnings`::
     urllib3.disable_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
+-----------------------
+
+.. versionadded:: 1.11
+
+Certain Python platforms (specifically, versions of Python earlier than 2.7.9)
+have restrictions in their ``ssl`` module that limit the configuration that
+``urllib3`` can apply. In particular, this can cause HTTPS requests that would
+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 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.