diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/index.rst | 2 | ||||
| -rw-r--r-- | docs/managers.rst | 11 | ||||
| -rw-r--r-- | docs/security.rst | 73 |
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 |