The GCS client library provides the following functions:

Functions

• cloudstorage.delete() deletes the specified object from the GCS bucket.
• cloudstorage.listbucket() lists the objects in the GCS bucket.
• cloudstorage.open() opens an existing object in the GCS bucket for reading or overwriting, or creates a new object, depending on the specified mode
• cloudstorage.stat() provides metadata information about the file, such as content type, size, timestamp, MD5 digest, and GCS headers.

Once cloudstorage.open() is invoked to return the file-like object representing the GCS object specified, you can use the standard Python file functions, such as write() and close(), to write an object to the GCS bucket, or read() to read an object from the GCS bucket.

Classes

• GCSFileStat()
• RetryParams()

Functions

cloudstorage.delete (filename, retry_params=None)

Deletes the specified file from the GCS bucket.

Raises errors.NotFoundError if the specified GCS object doesn't exist.

Arguments

filename (Required)

The full GCS file name for the object, in the format /bucket/object_name. Must be a full filename and can include the delimiter `/`.

retry_params= None (Optional.)

A RetryParams object in which you supply any changes you want to make to the default timeout and retry settings for this call.

Back to top

cloudstorage.listbucket (bucket, marker=None, prefix=None, max_keys=None, retry_params=None)

Returns a sorted list of the objects in the specified bucket path. This function is asynchronous. It does not block unless the iterator is called before the iterator gets results.

Arguments

bucket (Required)

The GCS bucket, in the format /bucketname. Supply only the bucket name in the path. You can use the prefix parameter to supply initial portions of the filename.

marker= None (Optional)

String. A named parameter specifying the file from which listbucket is to return results. The file used as `marker` is not returned. For example, if you want all fileslisted starting at superduperfoo3.txt to be listed, you specify the file immediately preceding superduperfoo3.txt, for example:

stat = gcs.listbucket(my_bucket, marker='superduperfoo2.txt')

One way to use this parameter is to use it with max_keys to "page through" the bucket file names.

prefix= None (Optional)

String. Specifies a file prefix that must start with the initial portion of the filename. For example, specify prefix='music/southamerica' to return only files prefixed by music/southamerica.

The following snippet shows prefix and marker used together to return filenames after a specific file, f005.mp3:

stats = gcs.listbucket(bucket, prefix='music/sou', marker='music/southamerica/f005.mp3')

where an initial portion of the filename is used for the prefix, and the full filename is used for marker. The marker param could be the initial portion of the file name, similar to prefix.

Note: Regular expressions are not supported.

max_keys= None (Optional)

Integer. A named parameter specifying the maximum number of file names to be returned. Can be used with marker to page through filenames in a bucket. Note that GCS itself will not return a list longer than 1000 names:

stats = gcs.listbucket(bucket, prefix='music/sou', marker='music/southamerica/f005.mp3', max_keys=15)

retry_params= None (Optional.)

A RetryParams object in which you supply any changes you want to make to the default timeout and retry settings for this call.

Result Value

Returns a GCSFileStat iterator over the matched files, sorted by filename. Only filename, etag (MD5 digest), and st_size (content length of headers) are set in the GCSFileStat objects.

Back to top

cloudstorage.open(filename, mode='r', content_type=None, options=None, read_buffer_size=storage_api.ReadBuffer.DEFAULT_BUFFER_SIZE, retry_params=None)

In read mode (r) opens the specified GCS object for read. In write mode w, if the specified file exists, it opens it for an overwrite (append is not supported). If the file doesn't exist, it is created in the specified bucket.

When you finish writing, if you want to read the file and/or store it at GCS, close the file using the close function. It is not an error if you don't call close, but the file will not be readable or persisted at GCS.

Raises:

• errors.NotFoundError if in read mode and the specified object doesn't exist.

Arguments

filename (Required)

The file to open, in the format /bucket/object. For example,/my_bucket/lyrics/southamerica/list5.txt.

mode (Optional)

String. Specify 'r' to open a file for read (default). Specify 'r' to open an existing file for overwriting or to create a new file.

content_type: (Optional)

String. Used only in write mode. You should specify the MIME type of the file (You can specify any valid MIME type.) If you don't supply this value, GCS defaults to the type binary/octet-stream when it serves the object.

options: (Optional)

Dict. Used only in write mode. GCS controls access to objects in buckets by means of an access control list (ACL). If you don't specify an ACL, GCS uses the bucket's default ACL. If you want to supply a specific ACL, you can do so by specifying the appropriate ACL in options. The valid values you can supply are listed in the GCS documentation for x-goog-acl-

In options, you can also specify custom metadata, using x-goog-meta- headers.

gcs_file = cloudstorage.open(filename, 'w', content_type='text/plain', options={'x-goog-acl': 'private','x-goog-meta-foo': 'foo', 'x-goog-meta-bar': 'bar'})

read_buffer_size: (Optional)

Integer. Used only in read mode. If you don't set this value, the default buffer size is used (recommended). When you read, you should read by read_buffer_size for optimum prefetch performance.

retry_params= None (Optional.)

A RetryParams object in which you supply any changes you want to make to the default timeout and retry settings for this call.

Result Value

Returns a reading or writing buffer, supporting a file-like interface on which you can invoke standard Python read, write, and close functions. This buffer must be closed after you finish reading or writing.

Back to top

cloudstorage.stat(filename, retry_params=None)

Returns a GCSFileStat object containing file metadata.

Raises:

• errors.NotFoundError if in read mode and the specified bucket or object doesn't exist.

Arguments

filename (Required)

The file to open, in the format /bucket/object. For example,/my_bucket/lyrics/southamerica/list5.txt

retry_params= None (Optional.)

A RetryParams object in which you supply any changes you want to make to the default timeout and retry settings for this call.

Result Value

Returns a GCSFileStat object containing file metadata.

Back to top

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.