Python

0.4.1

GCloud Package

gcloud

GCloud API access in idiomatic Python.

Connections

Shared implementation of connections to API servers.

class gcloud.connection.Connection(credentials=None, http=None)

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.

API_BASE_URL = 'https://www.googleapis.com'

The base of the API call URL.

USER_AGENT = 'gcloud-python/0.4.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.

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.

Credentials

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)

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

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()

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)

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)

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.

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=())

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘400 Bad Request’ response.

code = 400

exception gcloud.exceptions.ClientError(message, errors=())

Bases: gcloud.exceptions.GCloudError

Base for 4xx responses

This class is abstract

exception gcloud.exceptions.Conflict(message, errors=())

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘409 Conflict’ response.

code = 409

exception gcloud.exceptions.Forbidden(message, errors=())

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘403 Forbidden’ response.

code = 403

exception gcloud.exceptions.GCloudError(message, errors=())

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=())

Bases: gcloud.exceptions.ServerError

Exception mapping a ‘500 Internal Server Error’ response.

code = 500

exception gcloud.exceptions.LengthRequired(message, errors=())

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘411 Length Required’ response.

code = 411

exception gcloud.exceptions.MethodNotAllowed(message, errors=())

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘405 Method Not Allowed’ response.

code = 405

exception gcloud.exceptions.MovedPermanently(message, errors=())

Bases: gcloud.exceptions.Redirection

Exception mapping a ‘301 Moved Permanently’ response.

code = 301

exception gcloud.exceptions.NotFound(message, errors=())

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘404 Not Found’ response.

code = 404

exception gcloud.exceptions.NotImplemented(message, errors=())

Bases: gcloud.exceptions.ServerError

Exception mapping a ‘501 Not Implemented’ response.

code = 501

exception gcloud.exceptions.NotModified(message, errors=())

Bases: gcloud.exceptions.Redirection

Exception mapping a ‘304 Not Modified’ response.

code = 304

exception gcloud.exceptions.PreconditionFailed(message, errors=())

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘412 Precondition Failed’ response.

code = 412

exception gcloud.exceptions.Redirection(message, errors=())

Bases: gcloud.exceptions.GCloudError

Base for 3xx responses

This class is abstract.

exception gcloud.exceptions.RequestRangeNotSatisfiable(message, errors=())

Bases: gcloud.exceptions.ClientError

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

code = 416

exception gcloud.exceptions.ResumeIncomplete(message, errors=())

Bases: gcloud.exceptions.Redirection

Exception mapping a ‘308 Resume Incomplete’ response.

code = 308

exception gcloud.exceptions.ServerError(message, errors=())

Bases: gcloud.exceptions.GCloudError

Base for 5xx responses: (abstract)

exception gcloud.exceptions.ServiceUnavailable(message, errors=())

Bases: gcloud.exceptions.ServerError

Exception mapping a ‘503 Service Unavailable’ response.

code = 503

exception gcloud.exceptions.TemporaryRedirect(message, errors=())

Bases: gcloud.exceptions.Redirection

Exception mapping a ‘307 Temporary Redirect’ response.

code = 307

exception gcloud.exceptions.TooManyRequests(message, errors=())

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘429 Too Many Requests’ response.

code = 429

exception gcloud.exceptions.Unauthorized(message, errors=())

Bases: gcloud.exceptions.ClientError

Exception mapping a ‘401 Unauthorized’ response.

code = 401

gcloud.exceptions.eklass

alias of ServiceUnavailable

gcloud.exceptions.make_exception(response, content, use_json=True)

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.
• 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.