google.auth.transport.requests module¶

Transport adapter for Requests.

class TimeoutGuard(timeout, timeout_error_type=<class 'requests.exceptions.Timeout'>)[source]¶

Bases: object

A context manager raising an error if the suite execution took too long.

Parameters

timeout ([Union[None, float, Tuple[float, float]]]) – The maximum number of seconds a suite can run without the context manager raising a timeout exception on exit. If passed as a tuple, the smaller of the values is taken as a timeout. If None, a timeout error is never raised.
timeout_error_type (Optional [ Exception ]) – The type of the error to raise on timeout. Defaults to requests.exceptions.Timeout.

class Request(session=None)[source]¶

Bases: google.auth.transport.Request

Requests request adapter.

This class is used internally for making requests using various transports in a consistent way. If you use AuthorizedSession you do not need to construct or use this class directly.

This class can be useful if you want to manually refresh a Credentials instance:

import google.auth.transport.requests
import requests

request = google.auth.transport.requests.Request()

credentials.refresh(request)

Parameters: session (requests.Session) – An instance requests.Session used to make HTTP requests. If not specified, a session will be created.

__call__(url, method='GET', body=None, headers=None, timeout=120, **kwargs)[source]¶

Make an HTTP request using requests.

Parameters

url (str) – The URI to be requested.
method (str) – The HTTP method to use for the request. Defaults to ‘GET’.
body (bytes) – The payload / body in HTTP request.
headers (Mapping [ str, str ]) – Request headers.
timeout (Optional [ int ]) – The number of seconds to wait for a response from the server. If not specified or if None, the requests default timeout will be used.
kwargs – Additional arguments passed through to the underlying requests request() method.

Returns

The HTTP response.

Return type

google.auth.transport.Response

Raises

google.auth.exceptions.TransportError – If any exception occurred.

class AuthorizedSession(credentials, refresh_status_codes=(<HTTPStatus.UNAUTHORIZED: 401>, ), max_refresh_attempts=2, refresh_timeout=None, auth_request=None)[source]¶

Bases: requests.sessions.Session

A Requests Session class with credentials.

This class is used to perform requests to API endpoints that require authorization:

from google.auth.transport.requests import AuthorizedSession

authed_session = AuthorizedSession(credentials)

response = authed_session.request(
    'GET', 'https://www.googleapis.com/storage/v1/b')

The underlying request() implementation handles adding the credentials’ headers to the request and refreshing credentials as needed.

This class also supports mutual TLS via configure_mtls_channel() method. If client_cert_callback is provided, client certificate and private key are loaded using the callback; if client_cert_callback is None, application default SSL credentials will be used. Exceptions are raised if there are problems with the certificate, private key, or the loading process, so it should be called within a try/except block.

First we create an AuthorizedSession instance and specify the endpoints:

regular_endpoint = 'https://pubsub.googleapis.com/v1/projects/{my_project_id}/topics'
mtls_endpoint = 'https://pubsub.mtls.googleapis.com/v1/projects/{my_project_id}/topics'

authed_session = AuthorizedSession(credentials)

Now we can pass a callback to configure_mtls_channel():

def my_cert_callback():
    # some code to load client cert bytes and private key bytes, both in
    # PEM format.
    some_code_to_load_client_cert_and_key()
    if loaded:
        return cert, key
    raise MyClientCertFailureException()

# Always call configure_mtls_channel within a try/except block.
try:
    authed_session.configure_mtls_channel(my_cert_callback)
except:
    # handle exceptions.

if authed_session.is_mtls:
    response = authed_session.request('GET', mtls_endpoint)
else:
    response = authed_session.request('GET', regular_endpoint)

You can alternatively use application default SSL credentials like this:

try:
    authed_session.configure_mtls_channel()
except:
    # handle exceptions.

Parameters

credentials (google.auth.credentials.Credentials) – The credentials to add to the request.
refresh_status_codes (Sequence [ int ]) – Which HTTP status codes indicate that credentials should be refreshed and the request should be retried.
max_refresh_attempts (int) – The maximum number of times to attempt to refresh the credentials and retry the request.
refresh_timeout (Optional [ int ]) – The timeout value in seconds for credential refresh HTTP requests.
auth_request (google.auth.transport.requests.Request) – (Optional) An instance of Request used when refreshing credentials. If not passed, an instance of Request is created.

configure_mtls_channel(client_cert_callback=None)[source]¶

Configure the client certificate and key for SSL connection.

If client certificate and key are successfully obtained (from the given client_cert_callback or from application default SSL credentials), a _MutualTlsAdapter instance will be mounted to “https://” prefix.

Parameters: client_cert_callback (Optional [ Callable [ , bytes, bytes ] ]) – The optional callback returns the client certificate and private key bytes both in PEM format. If the callback is None, application default SSL credentials will be used.
Raises: google.auth.exceptions.MutualTLSChannelError – If mutual TLS channel creation failed for any reason.

request(method, url, data=None, headers=None, max_allowed_time=None, timeout=120, **kwargs)[source]¶

Implementation of Requests’ request.

Parameters

timeout (Optional [ Union [ float, Tuple [ float, float ] ] ]) –
The amount of time in seconds to wait for the server response with each individual request.

Can also be passed as a tuple (connect_timeout, read_timeout). See requests.Session.request() documentation for details.
max_allowed_time (Optional [ float ]) –
If the method runs longer than this, a Timeout exception is automatically raised. Unlike the ``timeout` parameter, this value applies to the total method execution time, even if multiple requests are made under the hood.

Mind that it is not guaranteed that the timeout error is raised at ``max_allowed_time`. It might take longer, for example, if an underlying request takes a lot of time, but the request itself does not timeout, e.g. if a large file is being transmitted. The timout error will be raised after such request completes.

property is_mtls¶: Indicates if the created SSL channel is mutual TLS.

close()¶: Closes all adapters and as such the session

delete(url, **kwargs)¶

Sends a DELETE request. Returns Response object.

Parameters

url – URL for the new Request object.
**kwargs – Optional arguments that request takes.

Return type

requests.Response

get(url, **kwargs)¶

Sends a GET request. Returns Response object.

Parameters

url – URL for the new Request object.
**kwargs – Optional arguments that request takes.

Return type

requests.Response

get_adapter(url)¶

Returns the appropriate connection adapter for the given URL.

Return type: requests.adapters.BaseAdapter

get_redirect_target(resp)¶: Receives a Response. Returns a redirect URI or None

head(url, **kwargs)¶

Sends a HEAD request. Returns Response object.

Parameters

url – URL for the new Request object.
**kwargs – Optional arguments that request takes.

Return type

requests.Response

merge_environment_settings(url, proxies, stream, verify, cert)¶

Check the environment and merge it with some settings.

Return type: dict

mount(prefix, adapter)¶

Registers a connection adapter to a prefix.

Adapters are sorted in descending order by prefix length.

options(url, **kwargs)¶

Sends a OPTIONS request. Returns Response object.

Parameters

url – URL for the new Request object.
**kwargs – Optional arguments that request takes.

Return type

requests.Response

patch(url, data=None, **kwargs)¶

Sends a PATCH request. Returns Response object.

Parameters

url – URL for the new Request object.
data – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.
**kwargs – Optional arguments that request takes.

Return type

requests.Response

post(url, data=None, json=None, **kwargs)¶

Sends a POST request. Returns Response object.

Parameters

url – URL for the new Request object.
data – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.
json – (optional) json to send in the body of the Request.
**kwargs – Optional arguments that request takes.

Return type

requests.Response

prepare_request(request)¶

Constructs a PreparedRequest for transmission and returns it. The PreparedRequest has settings merged from the Request instance and those of the Session.

Parameters: request – Request instance to prepare with this session’s settings.
Return type: requests.PreparedRequest

put(url, data=None, **kwargs)¶

Sends a PUT request. Returns Response object.

Parameters

url – URL for the new Request object.
data – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.
**kwargs – Optional arguments that request takes.

Return type

requests.Response

rebuild_auth(prepared_request, response)¶: When being redirected we may want to strip authentication from the request to avoid leaking credentials. This method intelligently removes and reapplies authentication where possible to avoid credential loss.

rebuild_method(prepared_request, response)¶: When being redirected we may want to change the method of the request based on certain specs or browser behavior.

rebuild_proxies(prepared_request, proxies)¶

This method re-evaluates the proxy configuration by considering the environment variables. If we are redirected to a URL covered by NO_PROXY, we strip the proxy configuration. Otherwise, we set missing proxy keys for this URL (in case they were stripped by a previous redirect).

This method also replaces the Proxy-Authorization header where necessary.

Return type: dict

resolve_redirects(resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None, yield_requests=False, **adapter_kwargs)¶: Receives a Response. Returns a generator of Responses or Requests.

send(request, **kwargs)¶

Send a given PreparedRequest.

Return type: requests.Response

should_strip_auth(old_url, new_url)¶: Decide whether Authorization header should be removed when redirecting

google.auth.transport.requests module¶

google-auth

Navigation

Related Topics