Add AppEngineAdapter for GAE users

At the moment this will not work because the AppEngineManager does not
have the same signature as urllib3's PoolManager.

Related to:
https://github.com/kennethreitz/requests/issues/1905#issuecomment-159380704

requests_toolbelt/_compat.py

@@ -11,6 +11,8 @@
 from collections import Mapping, MutableMapping
 import sys
 
+import requests
+
 try:
     from requests.packages.urllib3 import connection
     from requests.packages.urllib3 import fields
@@ -22,6 +24,14 @@
     from urllib3 import filepost
     from urllib3 import poolmanager
 
+if requests.__build__ < 0x020800:
+    gaecontrib = None
+else:
+    try:
+        from requests.packages.urllib3.contrib import appengine as gaecontrib
+    except ImportError:
+        from urllib3.contrib import appengine as gaecontrib
+
 PY3 = sys.version_info > (3, 0)
 
 if PY3:
@@ -275,4 +285,5 @@ def from_httplib(cls, message):  # Python 2
     'HTTPHeaderDict',
     'queue',
     'urlencode',
+    'gaecontrib',
 )

requests_toolbelt/adapters/appengine.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""The App Engine Transport Adapter for requests.
+
+This requires a version of requests >= 2.8.0.
+"""
+import requests
+from requests import adapters
+
+from .. import exceptions as exc
+from .._compat import gaecontrib
+
+
+class AppEngineAdapter(adapters.HTTPAdapter):
+    """A transport adapter for Requests to use urllib3's GAE support.
+
+    When deploying to Google's App Engine service, some of Requests'
+    functionality is broken. There is underlying support for GAE in urllib3.
+    This functionality, however, is opt-in and needs to be enabled explicitly
+    for Requests to be able to use it.
+
+    Example usage:
+
+    .. code-block:: python
+
+        >>> import requests
+        >>> import ssl
+        >>> from requests_toolbelt.adapters import appengine
+        >>> s = requests.Session()
+        >>> if using_appengine():
+        ...    s.mount('https://', appengine.AppEngineAdapter())
+        ...
+        >>>
+    """
+
+    def __init__(self, *args, **kwargs):
+        if gaecontrib is None:
+            raise exc.VersionMismatchError(
+                "The toolbelt requires at least Requests 2.8.0 to be "
+                "installed. Version {0} was found instead.".format(
+                    requests.__version__
+                )
+            )
+        super(AppEngineAdapter, self).__init__(self, *args, **kwargs)
+
+    def init_poolmanager(self, connections, maxsize, block=False):
+        self.poolmanager = gaecontrib.AppEngineManager(
+            num_pools=connections,
+            maxsize=maxsize,
+            block=block,
+            )

requests_toolbelt/exceptions.py

@@ -5,3 +5,12 @@
 class StreamingError(Exception):
     """Used in :mod:`requests_toolbelt.downloadutils.stream`."""
     pass
+
+
+class VersionMismatchError(Exception):
+    """Used to indicate a version mismatch in the version of requests required.
+
+    The feature in use requires a newer version of Requests to function
+    appropriately but the version installed is not sufficient.
+    """
+    pass