Shared Core Modules#

Base Client#

Base classes for client used to interact with Google Cloud APIs.

class google.cloud.client.Client(credentials=None, http=None)[source]#

Bases: google.cloud.client._ClientFactoryMixin

Client to bundle configuration needed for API requests.

Assumes that the associated _connection_class only accepts http and credentials in its constructor.

Parameters:

credentials (oauth2client.client.OAuth2Credentials or NoneType) – The OAuth2 Credentials to use for the connection owned by this client. If not passed (and if no http object is passed), falls back to the default inferred from the environment.
http (httplib2.Http or class that defines request().) – An optional HTTP object to make requests. If not passed, an http object is created that is bound to the credentials for the current object.

from_service_account_json(json_credentials_path, *args, **kwargs)#

Factory to retrieve JSON credentials while creating client.

Parameters:	json_credentials_path (string) – The path to a private key file (this file was given to you when you created the service account). This file must contain a JSON object with a private key and other credentials information (downloaded from the Google APIs console). args (tuple) – Remaining positional arguments to pass to constructor. kwargs (dict) – Remaining keyword arguments to pass to constructor.
Return type:	`google.cloud.pubsub.client.Client`
Returns:	The client created with the retrieved JSON credentials.
Raises:	`TypeError` if there is a conflict with the kwargs and the credentials created by the factory.

from_service_account_p12(client_email, private_key_path, *args, **kwargs)#

Factory to retrieve P12 credentials while creating client.

Note

Unless you have an explicit reason to use a PKCS12 key for your service account, we recommend using a JSON key.

Parameters:	client_email (string) – The e-mail attached to the service account. private_key_path (string) – The path to a private key file (this file was given to you when you created the service account). This file must be in P12 format. args (tuple) – Remaining positional arguments to pass to constructor. kwargs (dict) – Remaining keyword arguments to pass to constructor.
Return type:	`google.cloud.client.Client`
Returns:	The client created with the retrieved P12 credentials.
Raises:	`TypeError` if there is a conflict with the kwargs and the credentials created by the factory.

class google.cloud.client.JSONClient(project=None, credentials=None, http=None)[source]#

Bases: google.cloud.client.Client, google.cloud.client._ClientProjectMixin

Client to for Google JSON-based API.

Assumes such APIs use the project and the client needs to store this value.

Parameters:

project (string) – the project which the client acts on behalf of. If not passed falls back to the default inferred from the environment.
credentials (oauth2client.client.OAuth2Credentials or NoneType) – The OAuth2 Credentials to use for the connection owned by this client. If not passed (and if no http object is passed), falls back to the default inferred from the environment.
http (httplib2.Http or class that defines request().) – An optional HTTP object to make requests. If not passed, an http object is created that is bound to the credentials for the current object.

Raises:

ValueError if the project is neither passed in nor set in the environment.

from_service_account_json(json_credentials_path, *args, **kwargs)#

Factory to retrieve JSON credentials while creating client.

Parameters:	json_credentials_path (string) – The path to a private key file (this file was given to you when you created the service account). This file must contain a JSON object with a private key and other credentials information (downloaded from the Google APIs console). args (tuple) – Remaining positional arguments to pass to constructor. kwargs (dict) – Remaining keyword arguments to pass to constructor.
Return type:	`google.cloud.pubsub.client.Client`
Returns:	The client created with the retrieved JSON credentials.
Raises:	`TypeError` if there is a conflict with the kwargs and the credentials created by the factory.

from_service_account_p12(client_email, private_key_path, *args, **kwargs)#

Factory to retrieve P12 credentials while creating client.

Note

Unless you have an explicit reason to use a PKCS12 key for your service account, we recommend using a JSON key.

Parameters:	client_email (string) – The e-mail attached to the service account. private_key_path (string) – The path to a private key file (this file was given to you when you created the service account). This file must be in P12 format. args (tuple) – Remaining positional arguments to pass to constructor. kwargs (dict) – Remaining keyword arguments to pass to constructor.
Return type:	`google.cloud.client.Client`
Returns:	The client created with the retrieved P12 credentials.
Raises:	`TypeError` if there is a conflict with the kwargs and the credentials created by the factory.

Credentials Helpers#

A simple wrapper around the OAuth2 credentials library.

google.cloud.credentials.generate_signed_url(credentials, resource, expiration, api_access_endpoint='', method='GET', content_md5=None, content_type=None, response_type=None, response_disposition=None, generation=None)[source]#

Generate signed URL to provide query-string auth’n to a resource.

Note

Assumes credentials implements a sign_blob() method that takes bytes to sign and returns a pair of the key ID (unused here) and the signed bytes (this is abstract in the base class oauth2client.client.AssertionCredentials). Also assumes credentials has a service_account_email property which identifies the credentials.

Note

If you are on Google Compute Engine, you can’t generate a signed URL. Follow Issue 922 for updates on this. If you’d like to be able to generate a signed URL from GCE, you can use a standard service account from a JSON file rather than a GCE service account.

See headers reference for more details on optional arguments.

Parameters:	credentials (`oauth2client.appengine.AppAssertionCredentials`) – Credentials object with an associated private key to sign text. resource (string) – A pointer to a specific resource (typically, `/bucket-name/path/to/blob.txt`). expiration (`int`, `long`, `datetime.datetime`, `datetime.timedelta`) – When the signed URL should expire. api_access_endpoint (str) – Optional URI base. Defaults to empty string. method (str) – The HTTP verb that will be used when requesting the URL. Defaults to `'GET'`. content_md5 (str) – (Optional) The MD5 hash of the object referenced by `resource`. content_type (str) – (Optional) The content type of the object referenced by `resource`. response_type (str) – (Optional) Content type of responses to requests for the signed URL. Used to over-ride the content type of the underlying resource. response_disposition (str) – (Optional) Content disposition of responses to requests for the signed URL. generation (str) – (Optional) A value that indicates which generation of the resource to fetch.
Return type:	string
Returns:	A signed URL you can use to access the resource until expiration.

google.cloud.credentials.get_credentials()[source]#

Gets credentials implicitly from the current environment.

Note

You should not need to use this function directly. Instead, use a helper method which uses this method under the hood.

Checks environment in order of precedence:

Google App Engine (production and testing)
Environment variable GOOGLE_APPLICATION_CREDENTIALS pointing to a file with stored credentials information.
Stored “well known” file associated with gcloud command line tool.
Google Compute Engine production environment.

The file referred to in GOOGLE_APPLICATION_CREDENTIALS is expected to contain information about credentials that are ready to use. This means either service account information or user account information with a ready-to-use refresh token:

{
    'type': 'authorized_user',
    'client_id': '...',
    'client_secret': '...',
    'refresh_token': '...'
}

or

{
    'type': 'service_account',
    'project_id': '...',
    'private_key_id': '...',
    'private_key': '...',
    'client_email': '...',
    'client_id': '...',
    'auth_uri': '...',
    'token_uri': '...',
    'auth_provider_x509_cert_url': '...',
    'client_x509_cert_url': '...'
}

The second of these is simply a JSON key downloaded from the Google APIs console. The first is a close cousin of the “client secrets” JSON file used by oauth2client.clientsecrets but differs in formatting.

Return type:	`oauth2client.client.GoogleCredentials`, `oauth2client.contrib.appengine.AppAssertionCredentials`, `oauth2client.contrib.gce.AppAssertionCredentials`, `oauth2client.service_account.ServiceAccountCredentials`
Returns:	A new credentials instance corresponding to the implicit environment.

Base Connections#

Shared implementation of connections to API servers.

google.cloud.connection.API_BASE_URL = 'https://www.googleapis.com'#: The base of the API call URL.

class google.cloud.connection.Connection(credentials=None, http=None)[source]#

Bases: object

A generic connection to Google Cloud Platform.

Subclasses should understand only the basic types in method arguments, however they should be capable of returning advanced types.

If no value is passed in for http, a httplib2.Http object will be created and authorized with the credentials. If not, the credentials and http need not be related.

Subclasses may seek to use the private key from credentials to sign data.

A custom (non-httplib2) HTTP object must have a request method which accepts the following arguments:

uri
method
body
headers

In addition, redirections and connection_type may be used.

Without the use of credentials.authorize(http), a custom http object will also need to be able to add a bearer token to API requests and handle token refresh on 401 errors.

Parameters:	credentials (`oauth2client.client.OAuth2Credentials` or `NoneType`) – The OAuth2 Credentials to use for this connection. http (`httplib2.Http` or class that defines `request()`.) – An optional HTTP object to make requests.

SCOPE = None#

The scopes required for authenticating with a service.

Needs to be set by subclasses.

credentials#

Getter for current credentials.

Return type:	`oauth2client.client.OAuth2Credentials` or `NoneType`
Returns:	The credentials object associated with this connection.

http#

A getter for the HTTP transport used in talking to the API.

Return type:	`httplib2.Http`
Returns:	A Http object used to transport data.

google.cloud.connection.DEFAULT_USER_AGENT = 'gcloud-python/0.19.0'#: The user agent for google-cloud-python requests.

class google.cloud.connection.JSONConnection(credentials=None, http=None)[source]#

Bases: google.cloud.connection.Connection

A connection to a Google JSON-based API.

These APIs are discovery based. For reference:

https://developers.google.com/discovery/

This defines api_request() for making a generic JSON API request and API requests are created elsewhere.

The class constants

API_BASE_URL
API_VERSION
API_URL_TEMPLATE

must be updated by subclasses.

API_BASE_URL = None#: The base of the API call URL.

API_URL_TEMPLATE = None#: A template for the URL of a particular API call.

API_VERSION = None#: The version of the API, used in building the API call’s URL.

api_request(method, path, query_params=None, data=None, content_type=None, api_base_url=None, api_version=None, expect_json=True, _target_object=None)[source]#

Make a request over the HTTP transport to the API.

You shouldn’t need to use this method, but if you plan to interact with the API using these primitives, this is the correct one to use.

Parameters:	method (string) – The HTTP method name (ie, `GET`, `POST`, etc). Required. path (string) – The path to the resource (ie, `'/b/bucket-name'`). Required. query_params (dict or list) – A dictionary of keys and values (or list of key-value pairs) to insert into the query string of the URL. data (string) – The data to send as the body of the request. Default is the empty string. content_type (string) – The proper MIME type of the data provided. Default is None. api_base_url (string) – The base URL for the API endpoint. Typically you won’t have to provide this. Default is the standard API base URL. api_version (string) – The version of the API to call. Typically you shouldn’t provide this and instead use the default for the library. Default is the latest API version supported by google-cloud-python. expect_json (bool) – If True, this method will try to parse the response as JSON and raise an exception if that cannot be done. Default is True. _target_object (`object` or `NoneType`) – Protected argument to be used by library callers. This can allow custom behavior, for example, to defer an HTTP request and complete initialization of the object at a later time.
Raises:	Exception if the response code is not 200 OK.
Return type:	dict or str
Returns:	The API response payload, either as a raw string or a dictionary if the response is valid JSON.

classmethod build_api_url(path, query_params=None, api_base_url=None, api_version=None)[source]#

Construct an API url given a few components, some optional.

Typically, you shouldn’t need to use this method.

Parameters:	path (string) – The path to the resource (ie, `'/b/bucket-name'`). query_params (dict or list) – A dictionary of keys and values (or list of key-value pairs) to insert into the query string of the URL. api_base_url (string) – The base URL for the API endpoint. Typically you won’t have to provide this. api_version (string) – The version of the API to call. Typically you shouldn’t provide this and instead use the default for the library.
Return type:	string
Returns:	The URL assembled from the pieces provided.

Exceptions#

Custom exceptions for google.cloud package.

See: https://cloud.google.com/storage/docs/json_api/v1/status-codes

exception google.cloud.exceptions.BadGateway(message, errors=())[source]#

Bases: google.cloud.exceptions.ServerError

Exception mapping a ‘502 Bad Gateway’ response.

exception google.cloud.exceptions.BadRequest(message, errors=())[source]#

Bases: google.cloud.exceptions.ClientError

Exception mapping a ‘400 Bad Request’ response.

exception google.cloud.exceptions.ClientError(message, errors=())[source]#

Bases: google.cloud.exceptions.GoogleCloudError

Base for 4xx responses

This class is abstract

exception google.cloud.exceptions.Conflict(message, errors=())[source]#

Bases: google.cloud.exceptions.ClientError

Exception mapping a ‘409 Conflict’ response.

exception google.cloud.exceptions.Forbidden(message, errors=())[source]#

Bases: google.cloud.exceptions.ClientError

Exception mapping a ‘403 Forbidden’ response.

exception google.cloud.exceptions.GoogleCloudError(message, errors=())[source]#

Bases: exceptions.Exception

Base error class for Google Cloud errors (abstract).

Each subclass represents a single type of HTTP error response.

code = None#

HTTP status code. Concrete subclasses must define.

See: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

errors#

Detailed error information.

Return type:	list(dict)
Returns:	a list of mappings describing each error.

google.cloud.exceptions.GrpcRendezvous = None#: Exception class raised by gRPC stable.

exception google.cloud.exceptions.InternalServerError(message, errors=())[source]#

Bases: google.cloud.exceptions.ServerError

Exception mapping a ‘500 Internal Server Error’ response.

exception google.cloud.exceptions.LengthRequired(message, errors=())[source]#

Bases: google.cloud.exceptions.ClientError

Exception mapping a ‘411 Length Required’ response.

exception google.cloud.exceptions.MethodNotAllowed(message, errors=())[source]#

Bases: google.cloud.exceptions.ClientError

Exception mapping a ‘405 Method Not Allowed’ response.

exception google.cloud.exceptions.MethodNotImplemented(message, errors=())[source]#

Bases: google.cloud.exceptions.ServerError

Exception mapping a ‘501 Not Implemented’ response.

exception google.cloud.exceptions.MovedPermanently(message, errors=())[source]#

Bases: google.cloud.exceptions.Redirection

Exception mapping a ‘301 Moved Permanently’ response.

exception google.cloud.exceptions.NotFound(message, errors=())[source]#

Bases: google.cloud.exceptions.ClientError

Exception mapping a ‘404 Not Found’ response.

exception google.cloud.exceptions.NotModified(message, errors=())[source]#

Bases: google.cloud.exceptions.Redirection

Exception mapping a ‘304 Not Modified’ response.

exception google.cloud.exceptions.PreconditionFailed(message, errors=())[source]#

Bases: google.cloud.exceptions.ClientError

Exception mapping a ‘412 Precondition Failed’ response.

exception google.cloud.exceptions.Redirection(message, errors=())[source]#

Bases: google.cloud.exceptions.GoogleCloudError

Base for 3xx responses

This class is abstract.

exception google.cloud.exceptions.RequestRangeNotSatisfiable(message, errors=())[source]#

Bases: google.cloud.exceptions.ClientError

Exception mapping a ‘416 Request Range Not Satisfiable’ response.

exception google.cloud.exceptions.ResumeIncomplete(message, errors=())[source]#

Bases: google.cloud.exceptions.Redirection

Exception mapping a ‘308 Resume Incomplete’ response.

exception google.cloud.exceptions.ServerError(message, errors=())[source]#

Bases: google.cloud.exceptions.GoogleCloudError

Base for 5xx responses: (abstract)

exception google.cloud.exceptions.ServiceUnavailable(message, errors=())[source]#

Bases: google.cloud.exceptions.ServerError

Exception mapping a ‘503 Service Unavailable’ response.

exception google.cloud.exceptions.TemporaryRedirect(message, errors=())[source]#

Bases: google.cloud.exceptions.Redirection

Exception mapping a ‘307 Temporary Redirect’ response.

exception google.cloud.exceptions.TooManyRequests(message, errors=())[source]#

Bases: google.cloud.exceptions.ClientError

Exception mapping a ‘429 Too Many Requests’ response.

exception google.cloud.exceptions.Unauthorized(message, errors=())[source]#

Bases: google.cloud.exceptions.ClientError

Exception mapping a ‘401 Unauthorized’ response.

google.cloud.exceptions.make_exception(response, content, error_info=None, use_json=True)[source]#

Factory: create exception based on HTTP response code.

Parameters:	response (`httplib2.Response` or other HTTP response object) – A response object that defines a status code as the status attribute. content (string or dictionary) – The body of the HTTP error response. error_info (string) – Optional string giving extra information about the failed request. use_json (bool) – Flag indicating if `content` is expected to be JSON.
Return type:	instance of `GoogleCloudError`, or a concrete subclass.
Returns:	Exception specific to the error response.

Environment Variables#

Comprehensive list of environment variables used in google-cloud.

These enable many types of implicit behavior in both production and tests.

google.cloud.environment_vars.BIGTABLE_EMULATOR = 'BIGTABLE_EMULATOR_HOST'#: Environment variable defining host for Bigtable emulator.

google.cloud.environment_vars.CREDENTIALS = 'GOOGLE_APPLICATION_CREDENTIALS'#: Environment variable defining location of Google credentials.

google.cloud.environment_vars.DISABLE_GRPC = 'GOOGLE_CLOUD_DISABLE_GRPC'#

Environment variable acting as flag to disable gRPC.

To be used for APIs where both an HTTP and gRPC implementation exist.

google.cloud.environment_vars.GCD_DATASET = 'DATASTORE_DATASET'#: Environment variable defining default dataset ID under GCD.

google.cloud.environment_vars.GCD_HOST = 'DATASTORE_EMULATOR_HOST'#: Environment variable defining host for GCD dataset server.

google.cloud.environment_vars.PROJECT = 'GOOGLE_CLOUD_PROJECT'#: Environment variable defining default project.

google.cloud.environment_vars.PUBSUB_EMULATOR = 'PUBSUB_EMULATOR_HOST'#: Environment variable defining host for Pub/Sub emulator.