From e6838673bda9af1e9bf7c4f71b25cf3e3dfc1253 Mon Sep 17 00:00:00 2001 From: SVN-Git Migration Date: Thu, 8 Oct 2015 13:19:43 -0700 Subject: Imported Upstream version 1.11 --- docs/contrib.rst | 40 +++++++++++++++++++++++++++++++++++++++- docs/exceptions.rst | 2 ++ docs/helpers.rst | 2 ++ docs/index.rst | 36 +++++++++++++++++++++++++++--------- docs/security.rst | 30 ++++++++++++++++++++++++++++++ 5 files changed, 100 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/contrib.rst b/docs/contrib.rst index 99c5492..5a88f8e 100644 --- a/docs/contrib.rst +++ b/docs/contrib.rst @@ -6,9 +6,47 @@ Contrib Modules These modules implement various extra features, that may not be ready for prime time. -.. _pyopenssl: +.. _contrib-pyopenssl: SNI-support for Python 2 ------------------------ .. automodule:: urllib3.contrib.pyopenssl + + +.. _gae: + +Google App Engine +----------------- + +The :mod:`urllib3.contrib.appengine` module provides a pool manager that +uses Google App Engine's `URLFetch Service `_. + +Example usage:: + + from urllib3 import PoolManager + from urllib3.contrib.appengine import AppEngineManager, is_appengine_sandbox + + # This substitution will be done automagically once appengine code + # graduates from the contrib module. + if is_appengine_sandbox(): + # AppEngineManager uses AppEngine's URLFetch API behind the scenes + http = AppEngineManager() + else: + # PoolManager uses a socket-level API behind the scenes + http = PoolManager() + + # The client API should be consistent across managers, though some features are not available + # in URLFetch and you'll get warnings when you try to use them (like granular timeouts). + r = http.request('GET', 'https://google.com/') + + +There are `limitations `_ to the URLFetch service and it may not be the best choice for your application. App Engine provides three options for urllib3 users: + +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 `_ 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 `_, you can use the standard :class:`PoolManager` without any configuration or special environment variables. diff --git a/docs/exceptions.rst b/docs/exceptions.rst index f9e0553..cd451be 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -1,3 +1,5 @@ +.. _exceptions: + Exceptions ========== diff --git a/docs/helpers.rst b/docs/helpers.rst index 79f268b..6835e9a 100644 --- a/docs/helpers.rst +++ b/docs/helpers.rst @@ -1,3 +1,5 @@ +.. _helpers: + Helpers ======= diff --git a/docs/index.rst b/docs/index.rst index 81ac2d8..78d3601 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,9 +9,9 @@ urllib3 Documentation managers security helpers + exceptions collections contrib - security Highlights @@ -98,6 +98,27 @@ like buffering: >>> secondpart = b.read() +Upgrading & Versioning +---------------------- + +urllib3 uses a compatibility-based versioning scheme (let's call it +*compatver*). For the user, they indicate the required decision for upgrading. + +Given a version ``A.B.C``: + +``C.`` Strictly backwards-compatible, usually a bug-fix. **Always upgrade.** + +``B.`` Possibly partially incompatible, usually a new feature or a minor API +improvement. **Read the changelog and upgrade when ready.** + +``A.`` Major rewrite and possibly breaks everything. Not really an upgrade, +basically a new library under the same namespace, decide if you want to switch. + +For example, when going from urllib3 v1.2.3 to v1.2.4, you should always +upgrade without hesitation. When going from v1.2 to v1.3, you should read the +changes to make sure they're not going to affect you. + + Components ========== @@ -298,10 +319,8 @@ To aid the limited functionality of the :mod:`httplib` module, :mod:`urllib3` provides various helper methods which are used with the higher level components but can also be used independently. -.. toctree:: - - helpers - exceptions +* :ref:`helpers` +* :ref:`exceptions` Contrib Modules @@ -310,9 +329,7 @@ Contrib Modules These modules implement various extra features, that may not be ready for prime time. -.. toctree:: - - contrib +* :ref:`contrib-modules` Contributing @@ -352,7 +369,8 @@ benefits from this library. Sponsor with Credit Card - Sponsor with Bitcoin + Sponsor with Bitcoin + * **Recurring**: You're welcome to `support the maintainer on Gittip `_. diff --git a/docs/security.rst b/docs/security.rst index 881730e..0f5aa1c 100644 --- a/docs/security.rst +++ b/docs/security.rst @@ -128,6 +128,10 @@ packages:: $ pip install pyopenssl ndg-httpsclient pyasn1 +If ``cryptography`` fails to install as a dependency, make sure you have `libffi +`_ available on your system and run +``pip install cryptography``. + Once the packages are installed, you can tell urllib3 to switch the ssl backend to PyOpenSSL with :func:`~urllib3.contrib.pyopenssl.inject_into_urllib3`:: @@ -138,6 +142,32 @@ Now you can continue using urllib3 as you normally would. For more details, check the :mod:`~urllib3.contrib.pyopenssl` module. +Installing urllib3 with SNI support and certificates +---------------------------------------------------- + +By default, if you need to use SNI on Python 2.6 or Python 2.7.0-2.7.8, you +have to install PyOpenSSL, ndghttpsclient, and pyasn1 separately. Further, to +use certifi you have to install it separately. If you know that you want these +dependencies when you install urllib3, you can now do:: + + pip install urllib3[secure] + +This will install the SNI dependencies on Python 2.6 and 2.7 (we cannot yet +restrict the microversion for 2.7) and certifi on all versions of Python. + +.. note:: + + If you do this on linux, e.g., Ubuntu 14.04, you will need extra system + dependencies for PyOpenSSL. Specifically, PyOpenSSL requires cryptography + which will require you to install: + + - build-essential + - python-dev + - libffi-dev + - libssl-dev + + The package names may vary depending on the distribution of linux you are + using. .. _insecurerequestwarning: -- cgit v1.2.3