Report an Issue

Shared Core Modules#

Base Client#

gcloud client base class for interacting with API.

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

Bases: object

Client to bundle configuration needed for API requests.

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

Parameters:

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.

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.

classmethod from_service_account_json(json_credentials_path, *args, **kwargs)[source]#

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 (dictionary) – Remaining keyword arguments to pass to constructor.
Return type:	`gcloud.pubsub.client.Client`
Returns:	The client created with the retrieved JSON credentials.
Raises:	class:TypeError if there is a conflict with the kwargs and the credentials created by the factory.

classmethod from_service_account_p12(client_email, private_key_path, *args, **kwargs)[source]#

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 (dictionary) – Remaining keyword arguments to pass to constructor.
Return type:	`gcloud.client.Client`
Returns:	The client created with the retrieved P12 credentials.
Raises:	class:TypeError if there is a conflict with the kwargs and the credentials created by the factory.

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

Bases: gcloud.client.Client

Client to for Google JSON-based API.

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

Parameters:

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.

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.

Credentials Helpers#

A simple wrapper around the OAuth2 credentials library.

gcloud.credentials.generate_signed_url(credentials, resource, expiration, api_access_endpoint='', method='GET', content_md5=None, content_type=None)[source]#

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

Note

If you are on Google Compute Engine, you can’t generate a signed URL. Follow https://github.com/GoogleCloudPlatform/gcloud-python/issues/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.

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 (string) – Optional URI base. Defaults to empty string. method (string) – The HTTP verb that will be used when requesting the URL. content_md5 (string) – The MD5 hash of the object referenced by `resource`. content_type (string) – The content type of the object referenced by `resource`.
Return type:	string
Returns:	A signed URL you can use to access the resource until expiration.

gcloud.credentials.get_credentials()[source]#

Gets credentials implicitly from the current environment.

Note

You should not need to use this function directly. Instead, use the helper method gcloud.datastore.__init__.get_connection() 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',              'type': 'service_account',
    'client_id': '...',                     'client_id': '...',
    'client_secret': '...',       OR        'client_email': '...',
    'refresh_token': '...,                  'private_key_id': '...',
}                                           'private_key': '...',
                                        }

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.appengine.AppAssertionCredentials`, `oauth2client.gce.AppAssertionCredentials`, `oauth2client.service_account._ServiceAccountCredentials`
Returns:	A new credentials instance corresponding to the implicit environment.

gcloud.credentials.get_for_service_account_json(json_credentials_path, scope=None)[source]#

Gets the credentials for a service account with JSON key.

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). scope (string or tuple of string) – The scope against which to authenticate. (Different services require different scopes, check the documentation for which scope is required for the different levels of access to any particular API.)
Return type:	`oauth2client.client.GoogleCredentials`, `oauth2client.service_account._ServiceAccountCredentials`
Returns:	New service account or Google (for a user JSON key file) credentials object.

gcloud.credentials.get_for_service_account_p12(client_email, private_key_path, scope=None)[source]#

Gets the credentials for a service account with PKCS12 / p12 key.

Note

This method is not used by default, instead get_credentials() is used. This method is intended to be used when the environments is known explicitly and detecting the environment implicitly would be superfluous.

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. scope (string or tuple of string) – The scope against which to authenticate. (Different services require different scopes, check the documentation for which scope is required for the different levels of access to any particular API.)
Return type:	`oauth2client.client.SignedJwtAssertionCredentials`
Returns:	A new `SignedJwtAssertionCredentials` instance with the needed service account settings.

Base Connections#

Shared implementation of connections to API servers.

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

class gcloud.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.

USER_AGENT = 'gcloud-python/0.7.1'#: The user agent for gcloud-python requests.

credentials#

Getter for current credentials.

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

classmethod from_environment(*args, **kwargs)[source]#

Factory to retrieve implicit credentials while creating connection.

Parameters:	args (tuple) – Remaining positional arguments to pass to constructor. kwargs (dictionary) – Remaining keyword arguments to pass to constructor.
Return type:	`gcloud.connection.Connection`
Returns:	The connection created with the retrieved implicit credentials.
Raises:	class:TypeError if there is a conflict with the kwargs and the credentials created by the factory.

classmethod from_service_account_json(json_credentials_path, *args, **kwargs)[source]#

Factory to retrieve JSON credentials while creating connection.

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 (dictionary) – Remaining keyword arguments to pass to constructor.
Return type:	`gcloud.connection.Connection`
Returns:	The connection created with the retrieved JSON credentials.
Raises:	class:TypeError if there is a conflict with the kwargs and the credentials created by the factory.

classmethod from_service_account_p12(client_email, private_key_path, *args, **kwargs)[source]#

Factory to retrieve P12 credentials while creating connection.

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 (dictionary) – Remaining keyword arguments to pass to constructor.
Return type:	`gcloud.connection.Connection`
Returns:	The connection created with the retrieved P12 credentials.
Raises:	class:TypeError if there is a conflict with the kwargs and the credentials created by the factory.

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.

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

Bases: gcloud.connection.Connection

A connection to a Google JSON-based API.

These APIs are discovery based. For reference:: https://developers.google.com/discovery/

This defines Connection.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:

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) – A dictionary of keys and values to insert into the query string of the URL. Default is empty dict. 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 gcloud-python. expect_json (boolean) – 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.

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) – A dictionary of keys and values to insert into the query string of the URL. Default is empty dict.
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 gcloud-python.
expect_json (boolean) – 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.

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) – A dictionary of keys and values 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 gcloud.storage package.

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

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

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘400 Bad Request’ response.

code = 400#

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

Bases: gcloud.exceptions.GCloudError

Base for 4xx responses

This class is abstract

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

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘409 Conflict’ response.

code = 409#

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

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘403 Forbidden’ response.

code = 403#

exception gcloud.exceptions.GCloudError(message, errors=())[source]#

Bases: exceptions.Exception

Base error class for gcloud 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.

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

Bases: gcloud.exceptions.ServerError

Exception mapping a ‘500 Internal Server Error’ response.

code = 500#

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

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘411 Length Required’ response.

code = 411#

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

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘405 Method Not Allowed’ response.

code = 405#

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

Bases: gcloud.exceptions.Redirection

Exception mapping a ‘301 Moved Permanently’ response.

code = 301#

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

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘404 Not Found’ response.

code = 404#

exception gcloud.exceptions.NotImplemented(message, errors=())[source]#

Bases: gcloud.exceptions.ServerError

Exception mapping a ‘501 Not Implemented’ response.

code = 501#

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

Bases: gcloud.exceptions.Redirection

Exception mapping a ‘304 Not Modified’ response.

code = 304#

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

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘412 Precondition Failed’ response.

code = 412#

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

Bases: gcloud.exceptions.GCloudError

Base for 3xx responses

This class is abstract.

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

Bases: gcloud.exceptions.ClientError

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

code = 416#

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

Bases: gcloud.exceptions.Redirection

Exception mapping a ‘308 Resume Incomplete’ response.

code = 308#

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

Bases: gcloud.exceptions.GCloudError

Base for 5xx responses: (abstract)

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

Bases: gcloud.exceptions.ServerError

Exception mapping a ‘503 Service Unavailable’ response.

code = 503#

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

Bases: gcloud.exceptions.Redirection

Exception mapping a ‘307 Temporary Redirect’ response.

code = 307#

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

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘429 Too Many Requests’ response.

code = 429#

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

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘401 Unauthorized’ response.

code = 401#

gcloud.exceptions.eklass#: alias of ServiceUnavailable

gcloud.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 (boolean) – Flag indicating if `content` is expected to be JSON.
Return type:	instance of `GCloudError`, or a concrete subclass.
Returns:	Exception specific to the error response.