Imported Upstream version 1.11

5 files changed, 100 insertions, 10 deletions

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 <https://cloud.google.com/appengine/docs/python/urlfetch>`_.
+
+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 <https://cloud.google.com/appengine/docs/python/urlfetch/#Python_Quotas_and_limits>`_ 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 <https://cloud.google.com/appengine/docs/python/sockets/#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 <https://cloud.google.com/appengine/docs/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.
 
     <a href="https://donorbox.org/personal-sponsor-urllib3" style="background-color:#1275ff;color:#fff;text-decoration:none;font-family:Verdana,sans-serif;display:inline-block;font-size:14px;padding:7px 16px;border-radius:5px;margin-right:2em;vertical-align:top;border:1px solid rgba(160,160,160,0.5);background-image:linear-gradient(#7dc5ee,#008cdd 85%,#30a2e4);box-shadow:inset 0 1px 0 rgba(255,255,255,0.25);">Sponsor with Credit Card</a>
 
-    <a class="coinbase-button" data-code="137087702cf2e77ce400d53867b164e6" href="https://coinbase.com/checkouts/137087702cf2e77ce400d53867b164e6">Sponsor with Bitcoin</a><script src="https://coinbase.com/assets/button.js" type="text/javascript"></script>
+    <a class="coinbase-button" data-code="137087702cf2e77ce400d53867b164e6" href="https://coinbase.com/checkouts/137087702cf2e77ce400d53867b164e6">Sponsor with Bitcoin</a>
+    <script src="https://www.coinbase.com/assets/button.js" type="text/javascript"></script>
 
 * **Recurring**: You're welcome to `support the maintainer on Gittip
   <https://www.gittip.com/shazow/>`_.
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
+<http://sourceware.org/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: