Functions

The google.appengine.ext.blobstore package provides several functions. These functions allow applications to generate upload URLs, delete blobs, and fetch blob data.

Note: You can use objects stored in Google Cloud Storage with the Blobstore API functions. To do this, you need to generate a Blob Key using the create_gs_key() function.

create_rpc(deadline=None, callback=None)

Creates and returns an RPC object.

Arguments

deadline

The most amount of time to wait for a response from the remote host, as a number of seconds. If the remote host does not respond in this amount of time, an exception is raised when the check_success() method or the get_result() method of the RPC object is called.

If the application attempts to access results before the remote host has responded and before the deadline has elapsed, the call will wait until either of these have occurred, and either return results or raise the exception. If the application request timer expires while the application is waiting, the call is canceled.

callback

A Python function to be called when the service returns results successfully. The function is called without arguments.

The callback function is called when the wait() method of the RPC object is called, either directly by the application or implicitly with a call to check_success() or get_result(). The function does not get called in a background process or thread; it only gets called when one of these methods is called by the application.

The callback function is called even if the request fails or if the RPC deadline elapses.

create_upload_url(success_path, max_bytes_per_blob=None, max_bytes_total=None, rpc=None, gs_bucket_name=None)

Generate an action URL for a Blobstore upload web form.

When the user submits an upload web form, the uploaded data goes directly to the Blobstore or to Google Cloud Storage if you use that instead of Blobstore. (Google Cloud Storage requires the gs_bucket_name parameter.) The Blobstore rewrites the incoming request to remove the uploaded data (the MIME part body) and add the Blobstore key (as a header in the MIME part), then passes the rewritten request to the application handler associated with the URL path given to create_upload_url() as success_path. The handler at that path can process the rest of the form.

The generated URL will accept a Blobstore upload for up to 10 minutes after it is created. After 10 minutes Blobstore uploads to this URL will be rejected.

Arguments

success_path: The URL path of the request handler that will process the upload request, after the file submitted with the form has been uploaded to the Blobstore.
max_bytes_per_blob: The maximum size in bytes that any one blob in the upload can be, or None if there is no maximum blob size. Must be a positive value or None.
max_bytes_total: The maximum aggregate size of all of the blobs in the upload, or None if there is no total maximum. Must be a positive value or None.
rpc: An RPC object that controls some settings of this request from the application to the Blobstore service (deadline and optional callback function). If this argument is None (the default), this request uses normal settings.
gs_bucket_name: The Google Storage bucket name that the blob will be stored to. (Required if you use Google Cloud Storage instead of Blobstore.) Your application must have permissions to write to this bucket. Instead of the simple bucket name, you can optionally supply a bucket name and path in the format bucket_name/path, in which case the included path will be prepended to the uploaded object name.

Returns the URL to use as the action of an upload form.

create_upload_url_async(success_path, max_bytes_per_blob=None, max_bytes_total=None, rpc=None, gs_bucket_name=None)

Asynchronously generate an action URL for a Blobstore upload web form. This function is the asynchronous version of create_upload_url().

Arguments

success_path: The URL path of the request handler that will process the upload request, after the file submitted with the form has been uploaded to the Blobstore.
max_bytes_per_blob: The maximum size in bytes that any one blob in the upload can be, or None if there is no maximum blob size. Must be a positive value or None.
max_bytes_total: The maximum aggregate size of all of the blobs in the upload, or None if there is no total maximum. Must be a positive value or None.
rpc: An RPC object that controls some settings of this request from the application to the Blobstore service (deadline and optional callback function). If this argument is None (the default), this request uses normal settings.
gs_bucket_name: The Google Storage bucket name that the blob will be stored to. (Required if you use Google Cloud Storage instead of Blobstore.) Your application must have permissions to write to this bucket. Instead of the simple bucket name, you can optionally supply a bucket name and path in the format bucket_name/path, in which case the included path will be prepended to the uploaded object name.

Returns an RPC object. If the rpc argument is specified, this return value is that RPC object. This RPC object's result will be the URL to use as the action of an upload form.

delete(blob_keys, rpc=None)

Deletes a value or values from the Blobstore, and the corresponding BlobInfo entities from the datastore.

Arguments

blob_keys: A BlobKey object or blob key string, or a list of BlobKey objects or blob key strings to delete.
rpc: An RPC objectNone (the default), this request uses normal settings.

This function does not return a value. An application can confirm that a value has been deleted by attempting to get its correpsonding BlobInfo entity using the get() function.

delete_async(blob_keys, rpc=None)

Asynchronously deletes a value or values from the Blobstore and the corresponding BlobInfo entities from the datastore. This function is the asynchronous version of delete().

Arguments

blob_keys: A BlobKey object or blob key string, or a list of BlobKey objects or blob key strings to delete.
rpc: An RPC object that controls some settings of this request from the application to the Blobstore service (deadline and optional callback function). If this argument is None (the default), this request uses normal settings.

This function returns an RPC with result None. If the rpc argument is specified, this return value is that RPC object.

get(blob_key)

A synonym for BlobInfo.get().

parse_blob_info(field_storage)

Parses a cgi.FieldStorage object into a BlobInfo object.

When a Blobstore value is uploaded, the Blobstore creates a BlobInfo entity in the datastore. It also retains this data in the headers of the request passed to the upload handler. The upload handler can use parse_blob_info() to access this data from the header instead of making a call to the datastore.

Arguments

field_storage

A FieldStorage object, from the cgi module in the Python standard library.

import cgi
from google.appengine.ext import blobstore

blob_info = blobstore.parse_blob_info(cgi.FieldStorage()['file'])
# blob_info.filename...

The argument must be a FieldStorage object that represents a single file upload. If the user request contains more than one file upload (as multipart MIME data), you can iterate over the FieldStorage to get an inner FieldStorage object for each upload, and pass the inner object to the parse_blob_info() function. Here's an example that accommodates multiple files in a single form:

fields = cgi.FieldStorage()
# all fields named "file" assumed to contain file uploads
file_fields = fields['file']
if not isinstance(file_fields, list):
    file_fields = [file_fields]

for field in file_fields:
    blob_info = blobstore.parse_blob_info(field)
    # ...

parse_file_info(field_storage)

Parses a cgi.FieldStorage object into a FileInfo object.

When a file is uploaded to Google Cloud Storage (GCS) using the Blobstore library, the BlobstoreUploadHandler receives blob metadata in the POST handler's headers, such as the file name required to retrieve the file from GCS. (The blobkey alone won't suffice.) The upload handler uses parse_file_info() to access this data.

An alternative method for extracting GCS file metadata during a file upload is to use the Webapp BlobstoreUploadHandler get_file_infos() function, which is provided by google.appengine.ext.webapp.

Arguments

field_storage

A FieldStorage object, from the cgi module in the Python standard library.

import cgi
from google.appengine.ext import blobstore

file_info = blobstore.parse_file_info(cgi.FieldStorage()['file'])
# file_info.filename...

The argument must be a FieldStorage object that represents a single file upload. If the user request contains more than one file upload (as multipart MIME data), you can iterate over the FieldStorage to get an inner FieldStorage object for each upload, and pass the inner object to the parse_file_info() function. Here's an example that accommodates multiple files in a single form:

fields = cgi.FieldStorage()
file_fields = fields['file']  # all fields named "file" assumed to contain file
uploads
if not isinstance(file_fields, list):
    file_fields = [file_fields]

for field in file_fields:
    file_info = blobstore.parse_file_info(field)
    # ...

fetch_data(blob, start_index, end_index, rpc=None)

Retrieves the portion of a given Blobstore value described by the given byte indices.

The size of the portion (end_index-start_index + 1) must not exceed MAX_BLOB_FETCH_SIZE (about 1 megabyte). fetch_data() allows your application to access data in Blobstore values without exceeding the size limit on API return values.

Returns a str containing the requested portion of the Blobstore value. The return value may contain fewer than end_index-start_index + 1 bytes if either index is larger than the last index of the value.

Byte indices are inclusive, with the first byte having an index of 0. For example, a start_index of 9 and an end_index of 19 will return up to 11 bytes, starting from the 10th byte (index 9) in the value.

If blob does not refer to an actual Blobstore value, fetch_data raises a BlobNotFoundError.

Arguments

blob: A BlobInfo object, a BlobKey object, or a str or unicode representation of the blob key for the Blobstore value.
start_index: The index of the first byte of the portion of the value to fetch. An index of 0 represents the first byte of the value. If start_index is larger than the last index of the value, fetch_data() returns an empty byte string.
end_index: The index of the last byte of the portion of the value to fetch. If end_index is larger than the last index of the value, all bytes from start_index to the end of the value are returned.
rpc: An RPC object that controls some settings of this request from the application to the Blobstore service (deadline and optional callback function). If this argument is None (the default), this request uses normal settings.

fetch_data_async(blob, start_index, end_index, rpc=None)

Asynchronously retrieves the portion of a given Blobstore value described by the given byte indices. This function is the asynchronous version of fetch_data().

Arguments

blob: A BlobInfo object, a BlobKey object, or a str or unicode representation of the blob key for the Blobstore value.
start_index: The index of the first byte of the portion of the value to fetch. An index of 0 represents the first byte of the value. If start_index is larger than the last index of the value, fetch_data() returns an empty byte string.
end_index: The index of the last byte of the portion of the value to fetch. If end_index is larger than the last index of the value, all bytes from start_index to the end of the value are returned.
rpc: An RPC object that controls some settings of this request from the application to the Blobstore service (deadline and optional callback function). If this argument is None (the default), this request uses normal settings.

Returns an RPC object. If the rpc argument is specified, this return value is that RPC object. The RPC object's result will be a string containing the requested portion of the Blobstore value. The return value may contain fewer than end_index - start_index + 1 bytes if either index is larger than the last index of the value.

create_gs_key(filename, rpc=None)

Create an encoded key for a file representing a Google Storage object. You can safely persist the blob key generated by this function just as you can persist ordinary blob keys in the Blobstore API.

Arguments

filename: The filename of the Google Storage object for which you want to create a key.
rpc: An optional UserRPC object.

Returns an encrypted blob key as a string.

create_gs_key_async(filename, rpc=None)

Asynchronously create an encoded key for a file representing a Google Storage object. You can safely persist the blob key generated by this function.

Arguments

filename: The filename of the Google Storage object for which you want to create a key.
rpc: An optional UserRPC object.

Returns a UserRPC object whose result is a string as returned by create_gs_key.

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.

Last updated September 22, 2014.

Functions

Products

Learn

Deploy

Resources

Pricing