annotate env/lib/python3.9/site-packages/urllib3/contrib/appengine.py @ 0:4f3585e2f14b draft default tip

"planemo upload commit 60cee0fc7c0cda8592644e1aad72851dec82c959"

1 """
2 This module provides a pool manager that uses Google App Engine's
3 `URLFetch Service <https://cloud.google.com/appengine/docs/python/urlfetch>`_.
4 
5 Example usage::
6 
7     from urllib3 import PoolManager
8     from urllib3.contrib.appengine import AppEngineManager, is_appengine_sandbox
9 
10     if is_appengine_sandbox():
11         # AppEngineManager uses AppEngine's URLFetch API behind the scenes
12         http = AppEngineManager()
13     else:
14         # PoolManager uses a socket-level API behind the scenes
15         http = PoolManager()
16 
17     r = http.request('GET', 'https://google.com/')
18 
19 There are `limitations <https://cloud.google.com/appengine/docs/python/\
20 urlfetch/#Python_Quotas_and_limits>`_ to the URLFetch service and it may not be
21 the best choice for your application. There are three options for using
22 urllib3 on Google App Engine:
23 
24 1. You can use :class:`AppEngineManager` with URLFetch. URLFetch is
25    cost-effective in many circumstances as long as your usage is within the
26    limitations.
27 2. You can use a normal :class:`~urllib3.PoolManager` by enabling sockets.
28    Sockets also have `limitations and restrictions
29    <https://cloud.google.com/appengine/docs/python/sockets/\
30    #limitations-and-restrictions>`_ and have a lower free quota than URLFetch.
31    To use sockets, be sure to specify the following in your ``app.yaml``::
32 
33         env_variables:
34             GAE_USE_SOCKETS_HTTPLIB : 'true'
35 
36 3. If you are using `App Engine Flexible
37 <https://cloud.google.com/appengine/docs/flexible/>`_, you can use the standard
38 :class:`PoolManager` without any configuration or special environment variables.
39 """
40 
41 from __future__ import absolute_import
42 
43 import io
44 import logging
45 import warnings
46 
47 from ..exceptions import (
48     HTTPError,
49     HTTPWarning,
50     MaxRetryError,
51     ProtocolError,
52     SSLError,
53     TimeoutError,
54 )
55 from ..packages.six.moves.urllib.parse import urljoin
56 from ..request import RequestMethods
57 from ..response import HTTPResponse
58 from ..util.retry import Retry
59 from ..util.timeout import Timeout
60 from . import _appengine_environ
61 
62 try:
63     from google.appengine.api import urlfetch
64 except ImportError:
65     urlfetch = None
66 
67 
68 log = logging.getLogger(__name__)
69 
70 
71 class AppEnginePlatformWarning(HTTPWarning):
72     pass
73 
74 
75 class AppEnginePlatformError(HTTPError):
76     pass
77 
78 
79 class AppEngineManager(RequestMethods):
80     """
81     Connection manager for Google App Engine sandbox applications.
82 
83     This manager uses the URLFetch service directly instead of using the
84     emulated httplib, and is subject to URLFetch limitations as described in
85     the App Engine documentation `here
86     <https://cloud.google.com/appengine/docs/python/urlfetch>`_.
87 
88     Notably it will raise an :class:`AppEnginePlatformError` if:
89         * URLFetch is not available.
90         * If you attempt to use this on App Engine Flexible, as full socket
91           support is available.
92         * If a request size is more than 10 megabytes.
93         * If a response size is more than 32 megabytes.
94         * If you use an unsupported request method such as OPTIONS.
95 
96     Beyond those cases, it will raise normal urllib3 errors.
97     """
98 
99     def __init__(
00         self,
01         headers=None,
02         retries=None,
03         validate_certificate=True,
04         urlfetch_retries=True,
05     ):
06         if not urlfetch:
07             raise AppEnginePlatformError(
08                 "URLFetch is not available in this environment."
09             )
10 
11         warnings.warn(
12             "urllib3 is using URLFetch on Google App Engine sandbox instead "
13             "of sockets. To use sockets directly instead of URLFetch see "
14             "https://urllib3.readthedocs.io/en/latest/reference/urllib3.contrib.html.",
15             AppEnginePlatformWarning,
16         )
17 
18         RequestMethods.__init__(self, headers)
19         self.validate_certificate = validate_certificate
20         self.urlfetch_retries = urlfetch_retries
21 
22         self.retries = retries or Retry.DEFAULT
23 
24     def __enter__(self):
25         return self
26 
27     def __exit__(self, exc_type, exc_val, exc_tb):
28         # Return False to re-raise any potential exceptions
29         return False
30 
31     def urlopen(
32         self,
33         method,
34         url,
35         body=None,
36         headers=None,
37         retries=None,
38         redirect=True,
39         timeout=Timeout.DEFAULT_TIMEOUT,
40         **response_kw
41     ):
42 
43         retries = self._get_retries(retries, redirect)
44 
45         try:
46             follow_redirects = redirect and retries.redirect != 0 and retries.total
47             response = urlfetch.fetch(
48                 url,
49                 payload=body,
50                 method=method,
51                 headers=headers or {},
52                 allow_truncated=False,
53                 follow_redirects=self.urlfetch_retries and follow_redirects,
54                 deadline=self._get_absolute_timeout(timeout),
55                 validate_certificate=self.validate_certificate,
56             )
57         except urlfetch.DeadlineExceededError as e:
58             raise TimeoutError(self, e)
59 
60         except urlfetch.InvalidURLError as e:
61             if "too large" in str(e):
62                 raise AppEnginePlatformError(
63                     "URLFetch request too large, URLFetch only "
64                     "supports requests up to 10mb in size.",
65                     e,
66                 )
67             raise ProtocolError(e)
68 
69         except urlfetch.DownloadError as e:
70             if "Too many redirects" in str(e):
71                 raise MaxRetryError(self, url, reason=e)
72             raise ProtocolError(e)
73 
74         except urlfetch.ResponseTooLargeError as e:
75             raise AppEnginePlatformError(
76                 "URLFetch response too large, URLFetch only supports"
77                 "responses up to 32mb in size.",
78                 e,
79             )
80 
81         except urlfetch.SSLCertificateError as e:
82             raise SSLError(e)
83 
84         except urlfetch.InvalidMethodError as e:
85             raise AppEnginePlatformError(
86                 "URLFetch does not support method: %s" % method, e
87             )
88 
89         http_response = self._urlfetch_response_to_http_response(
90             response, retries=retries, **response_kw
91         )
92 
93         # Handle redirect?
94         redirect_location = redirect and http_response.get_redirect_location()
95         if redirect_location:
96             # Check for redirect response
97             if self.urlfetch_retries and retries.raise_on_redirect:
98                 raise MaxRetryError(self, url, "too many redirects")
99             else:
00                 if http_response.status == 303:
01                     method = "GET"
02 
03                 try:
04                     retries = retries.increment(
05                         method, url, response=http_response, _pool=self
06                     )
07                 except MaxRetryError:
08                     if retries.raise_on_redirect:
09                         raise MaxRetryError(self, url, "too many redirects")
10                     return http_response
11 
12                 retries.sleep_for_retry(http_response)
13                 log.debug("Redirecting %s -> %s", url, redirect_location)
14                 redirect_url = urljoin(url, redirect_location)
15                 return self.urlopen(
16                     method,
17                     redirect_url,
18                     body,
19                     headers,
20                     retries=retries,
21                     redirect=redirect,
22                     timeout=timeout,
23                     **response_kw
24                 )
25 
26         # Check if we should retry the HTTP response.
27         has_retry_after = bool(http_response.getheader("Retry-After"))
28         if retries.is_retry(method, http_response.status, has_retry_after):
29             retries = retries.increment(method, url, response=http_response, _pool=self)
30             log.debug("Retry: %s", url)
31             retries.sleep(http_response)
32             return self.urlopen(
33                 method,
34                 url,
35                 body=body,
36                 headers=headers,
37                 retries=retries,
38                 redirect=redirect,
39                 timeout=timeout,
40                 **response_kw
41             )
42 
43         return http_response
44 
45     def _urlfetch_response_to_http_response(self, urlfetch_resp, **response_kw):
46 
47         if is_prod_appengine():
48             # Production GAE handles deflate encoding automatically, but does
49             # not remove the encoding header.
50             content_encoding = urlfetch_resp.headers.get("content-encoding")
51 
52             if content_encoding == "deflate":
53                 del urlfetch_resp.headers["content-encoding"]
54 
55         transfer_encoding = urlfetch_resp.headers.get("transfer-encoding")
56         # We have a full response's content,
57         # so let's make sure we don't report ourselves as chunked data.
58         if transfer_encoding == "chunked":
59             encodings = transfer_encoding.split(",")
60             encodings.remove("chunked")
61             urlfetch_resp.headers["transfer-encoding"] = ",".join(encodings)
62 
63         original_response = HTTPResponse(
64             # In order for decoding to work, we must present the content as
65             # a file-like object.
66             body=io.BytesIO(urlfetch_resp.content),
67             msg=urlfetch_resp.header_msg,
68             headers=urlfetch_resp.headers,
69             status=urlfetch_resp.status_code,
70             **response_kw
71         )
72 
73         return HTTPResponse(
74             body=io.BytesIO(urlfetch_resp.content),
75             headers=urlfetch_resp.headers,
76             status=urlfetch_resp.status_code,
77             original_response=original_response,
78             **response_kw
79         )
80 
81     def _get_absolute_timeout(self, timeout):
82         if timeout is Timeout.DEFAULT_TIMEOUT:
83             return None  # Defer to URLFetch's default.
84         if isinstance(timeout, Timeout):
85             if timeout._read is not None or timeout._connect is not None:
86                 warnings.warn(
87                     "URLFetch does not support granular timeout settings, "
88                     "reverting to total or default URLFetch timeout.",
89                     AppEnginePlatformWarning,
90                 )
91             return timeout.total
92         return timeout
93 
94     def _get_retries(self, retries, redirect):
95         if not isinstance(retries, Retry):
96             retries = Retry.from_int(retries, redirect=redirect, default=self.retries)
97 
98         if retries.connect or retries.read or retries.redirect:
99             warnings.warn(
00                 "URLFetch only supports total retries and does not "
01                 "recognize connect, read, or redirect retry parameters.",
02                 AppEnginePlatformWarning,
03             )
04 
05         return retries
06 
07 
08 # Alias methods from _appengine_environ to maintain public API interface.
09 
10 is_appengine = _appengine_environ.is_appengine
11 is_appengine_sandbox = _appengine_environ.is_appengine_sandbox
12 is_local_appengine = _appengine_environ.is_local_appengine
13 is_prod_appengine = _appengine_environ.is_prod_appengine
14 is_prod_appengine_mvms = _appengine_environ.is_prod_appengine_mvms