From c9df3d807f7134f58f4a84dc8b80e9dc98c62f3a Mon Sep 17 00:00:00 2001 From: SVN-Git Migration Date: Thu, 8 Oct 2015 13:19:42 -0700 Subject: Imported Upstream version 1.10.4 --- docs/index.rst | 30 ++++++++++++++++++++++++++++++ docs/managers.rst | 20 +++++++++++++++++--- docs/pools.rst | 17 ++++++++++++++++- docs/security.rst | 33 ++++++++++++++++++++++++++++++++- 4 files changed, 95 insertions(+), 5 deletions(-) (limited to 'docs') 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) + ... + + >>> 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. -- cgit v1.2.3