google.appengine.ext.blobstore.blobstore module

Summary

A Python blobstore API used by app developers.

This module contains methods that are used to interface with Blobstore API. The module includes a db.Model-like class that represents a reference to a very large blob. The module imports a db.Key-like class that represents a blob key.

Contents

exception google.appengine.ext.blobstore.blobstore.BlobFetchSizeTooLargeErrorsource

Bases: google.appengine.api.blobstore.blobstore.Error

The block could not be fetched because it was too large.

class google.appengine.ext.blobstore.blobstore.BlobInfo(entity_or_blob_key, _values=None)source

Bases: object

Information about blobs in Blobstore.

This is a db.Model-like class that contains information about blobs that are stored by an application. Like db.Model, this class is backed by a Datastore entity; however, BlobInfo instances are read-only and have a much more limited interface.

Each BlobInfo has a key of type BlobKey associated with it. This key is specific to the Blobstore API and is not compatible with db.get. The key can be used for quick lookup by passing it to BlobInfo.get. This key converts easily to a string, which is web safe and can be embedded in URLs.

Properties:

  • content_type: The content type of the blob.

  • creation: The creation date of the blob, or when it was uploaded.

  • filename: The file name that the user selected from their machine.

  • size: The size of the uncompressed blob.

  • md5_hash: The MD5 hash value of the uploaded blob.

gs_object_name: The name of the object, if the blob is stored in

Google Cloud Storage, in the form /[bucket-name]/[object-name]

All properties are read-only. Attempting to assign a value to a property will raise a NotImplementedError.

classmethod all()source

Creates a query for all BlobInfo objects associated with the app.

Returns

A db.Query object that queries over BlobInfo’s datastore kind.

content_type

Returns the content type of the blob.

Returns

The content type of the blob.

creation

Returns the creation date or time of upload of the blob.

Returns

The creation date or time of upload of the blob.

delete(_token=None)source

Permanently deletes a blob from Blobstore.

filename

Returns the file name that the user selected from their machine.

Returns

The file name that the user selected.

classmethod from_entity(entity)source

Converts an entity to BlobInfo.

Parameters

entity – The entity that you are trying to convert.

Returns

The BlobInfo that was converted from the entity.

classmethod get(blob_keys)source

Retrieves a BlobInfo by key or by a list of keys.

Parameters

blob_keys – A key or a list of keys. Keys can be in string, Unicode, or BlobKey format.

Returns

A BlobInfo instance that is associated with the provided key or a list of BlobInfo instances if a list of keys was provided. Keys that are not found in Blobstore return None.

classmethod gql(query_string, *args, **kwds)source

Returns a query using a GQL query string.

See the GQL source for more information about GQL.

Parameters

  • query_string – A properly formatted GQL query string that omits SELECT * FROM <entity>

  • *args – The remaining positional arguments that are used to bind numeric references in the query.

  • **kwds – The dictionary-based arguments for named parameters.

Returns

A gql.GqlQuery object that queries over BlobInfo’s datastore kind.

gs_object_name
key()source

Gets the key for a blob.

Returns

The BlobKey instance that identifies this blob.

classmethod kind()source

Gets the entity kind for the BlobInfo.

Returns

The entity kind for BlobInfo.

md5_hash

Returns the MD5 hash value of the uncompressed blob.

Returns

The hash value of the uncompressed blob.

open(*args, **kwargs)source

Returns a BlobReader for this blob.

Parameters

  • *args – Arguments to pass to the BlobReader constructor.

  • **kwargs – Keyword arguments to pass to the BlobReader constructor.

Returns

A BlobReader instance.

classmethod properties()source

Defines the set of properties that belong to BlobInfo.

Returns

A set of all of the properties that belong to BlobInfo.

size

Returns the size of the uncompressed blob.

Returns

The size of the uncompressed blob.

exception google.appengine.ext.blobstore.blobstore.BlobInfoParseErrorsource

Bases: google.appengine.api.blobstore.blobstore.Error

The CGI parameter does not contain a valid BlobInfo record.

class google.appengine.ext.blobstore.blobstore.BlobKey(blob_key)source

Bases: object

Key used to identify a blob in Blobstore.

This object wraps a string that gets used internally by the Blobstore API to identify application blobs. The BlobKey corresponds to the entity name of the underlying BlobReference entity.

This class is exposed in the API in both google.appengine.ext.db and google.appengine.ext.blobstore.

ToXml()source
class google.appengine.ext.blobstore.blobstore.BlobMigrationRecord(parent=None, key_name=None, _app=None, _from_entity=False, **kwds)source

Bases: google.appengine.ext.db.Model

Defines a model that records the result of a blob migration.

classmethod get_by_blob_key(old_blob_key)source

Fetches the BlobMigrationRecord for the given blob key.

Parameters

old_blob_key – The blob key that was used in the previous app.

Returns

A instance of blobstore.BlobMigrationRecord or None.

classmethod get_new_blob_key(old_blob_key)source

Looks up the new key for a blob.

Parameters

old_blob_key – The original blob key.

Returns

The blobstore.BlobKey of the migrated blob.

classmethod kind()source

Specifies the kind of blob that you are migrating.

Returns

The kind of blob that you are migrating

new_blob_ref

Property compatible with db.Model classes.

Add references to blobs to domain models using BlobReferenceProperty:

class Picture(db.Model):
  title = db.StringProperty()
  image = blobstore.BlobReferenceProperty()
  thumbnail = blobstore.BlobReferenceProperty()

To find the size of a picture using this model:

picture = Picture.get(picture_key)
print picture.image.size

BlobInfo objects are lazily loaded, so iterating over models for BlobKeys is efficient. The following sample code does not need to hit Datastore for each image key:

list_of_untitled_blobs = []
for picture in Picture.gql("WHERE title=''"):
  list_of_untitled_blobs.append(picture.image.key())
exception google.appengine.ext.blobstore.blobstore.BlobNotFoundErrorsource

Bases: google.appengine.api.blobstore.blobstore.Error

The blob does not exist.

class google.appengine.ext.blobstore.blobstore.BlobReferenceProperty(verbose_name=None, name=None, default=None, required=False, validator=None, choices=None, indexed=True)source

Bases: google.appengine.ext.db.Property

Property compatible with db.Model classes.

Add references to blobs to domain models using BlobReferenceProperty:

class Picture(db.Model):
  title = db.StringProperty()
  image = blobstore.BlobReferenceProperty()
  thumbnail = blobstore.BlobReferenceProperty()

To find the size of a picture using this model:

picture = Picture.get(picture_key)
print picture.image.size

BlobInfo objects are lazily loaded, so iterating over models for BlobKeys is efficient. The following sample code does not need to hit Datastore for each image key:

list_of_untitled_blobs = []
for picture in Picture.gql("WHERE title=''"):
  list_of_untitled_blobs.append(picture.image.key())
data_type

alias of BlobInfo

get_value_for_datastore(model_instance)source

Returns a model property translated to a datastore value.

Parameters

model_instance – The model property that you want to translate.

Returns

The model property that was translated from datastore.

make_value_from_datastore(value)source

Returns a datastore value to BlobInfo.

Parameters

value – The datastore value that you want to translate.

Returns

A BlobInfo that was translated from datastore.

validate(value)source

Validates that an assigned value is BlobInfo.

This method automatically converts from strings and BlobKey instances.

Parameters

value – The value that you want to validate.

Returns

Information about whether an assigned value is BlobInfo.

class google.appengine.ext.blobstore.blobstore.BlobReader(blob, buffer_size=131072, position=0)source

Bases: object

Provides a read-only file-like interface to a blobstore blob.

SEEK_CUR = 1
SEEK_END = 2
SEEK_SET = 0
blob_info

Returns the BlobInfo for this file.

Returns

A string that contains the BlobInfo.

close()source

Closes the file.

A closed file cannot be read or written to anymore. An operation that requires that the file to be open will raise a ValueError after the file has been closed. Calling close() more than once is allowed.

closed

Determines whether a file is closed.

Returns

True if this file is closed; opened files return False.

flush()source
next()source

Returns the next line from the file.

Returns

A string, terminated by \n. The last line cannot end with \n. If the end of the file is reached, an empty string will be returned.

Raises

StopIteration – If there are no further lines to read.

read(size=-1)source

Reads at most size bytes from the file.

Fewer bytes are read if the read hits the end of the file before obtaining size bytes. If the size argument is negative or omitted, all data is read until the end of the file is reached. The bytes are returned as a string object. An empty string is returned immediately when the end of the file is reached.

Calling read() without specifying a size is likely to be dangerous, as it might read excessive amounts of data.

Parameters

size – Optional. The maximum number of bytes to read. When omitted, read() returns all remaining data in the file.

Returns

The read data, as a string.

readline(size=-1)source

Reads one entire line from the file.

A trailing newline character is kept in the string but can be absent when a file ends with an incomplete line. If the size argument is present and non-negative, it represents a maximum byte count, including the trailing newline and an incomplete line might be returned. An empty string is returned immediately only when the end of the file is reached.

Parameters

size – Optional. The maximum number of bytes to read.

Returns

The read data, as a string.

readlines(sizehint=None)source

Reads until the end of the file using readline().

A list of lines read is returned.

If the optional sizehint argument is present, instead of reading up to the end of the file, whole lines totalling approximately sizehint bytes are read, possibly after rounding up to an internal buffer size.

Parameters

sizehint – A hint as to the maximum number of bytes to read.

Returns

A list of strings, each being a single line from the file.

seek(offset, whence=0)source

Sets the file’s current position, like stdio’s fseek().

Parameters

  • offset – The relative offset to seek to.

  • whence – Optional; defines to what value the offset is relative. This argument defaults to os.SEEK_SET or 0 to use absolute file positioning; other valid values are os.SEEK_CUR or 1 to seek relative to the current position and os.SEEK_END or 2 to seek relative to the end of the file.

tell()source

Retrieves the file’s current position, like stdio’s ftell().

Returns

The file’s current position.

truncate(size)source

Raises an error if you attempt to truncate the file.

Parameters

size – The size that you are attempting to truncate to.

Raises

IOError – If you attempt to truncate a file in BlobReader.

write(str)source

Raises an error if you attempt to write to the file.

Parameters

str – The string that you are attempting to write.

Raises

IOError – If you attempt to write to a file in BlobReader.

writelines(sequence)source

Raises an error if you attempt to write to the file.

Parameters

sequence – The sequence of strings that you are attempting to write.

Raises

IOError – If you attempt to write lines to a file in BlobReader.

class google.appengine.ext.blobstore.blobstore.FileInfo(filename=None, content_type=None, creation=None, size=None, md5_hash=None, gs_object_name=None)source

Bases: object

Details information about uploaded files.

This class contains information about blobs stored by an application.

This class is similar to BlobInfo; however, this method does not make use of a key, and the information is not persisted in the datastore.

Properties:

  • content_type: The content type of the uploaded file.

  • creation: The creation date of the uploaded file, or when it was

    uploaded.

  • filename: The file name that the user selected from their machine.

  • size: The size of the uncompressed file.

  • md5_hash: The MD5 hash value of the uploaded file.

  • gs_object_name: The name of the file that was written to Google Cloud Storage, or None if the file was not uploaded to Google Cloud Storage.

All properties are read-only. Attempting to assign a value to a property will raise an AttributeError.

content_type

Returns the content type of the uploaded file.

Returns

The content type of the file.

creation

Returns the creation date or upload time of the file.

Returns

The creation date or upload time of the file.

filename

Returns the file name that the user selected.

Returns

The file name that the user selected.

gs_object_name

Returns the name of the file that was written to Cloud Storage.

Returns

The name of the file that was written to Cloud Storage.

md5_hash

Returns the MD5 hash of the uploaded file.

Returns

The hash value for the uploaded file.

size

Returns the size of the uncompressed file.

Returns

The size of the uncompressed file.

exception google.appengine.ext.blobstore.blobstore.FileInfoParseErrorsource

Bases: google.appengine.api.blobstore.blobstore.Error

The CGI parameter does not contain a valid FileInfo record.

exception google.appengine.ext.blobstore.blobstore.DataIndexOutOfRangeErrorsource

Bases: google.appengine.api.blobstore.blobstore.Error

The indexes could not be accessed.

The specified indexes were out of range or in the wrong order.

exception google.appengine.ext.blobstore.blobstore.PermissionDeniedErrorsource

Bases: google.appengine.api.blobstore.blobstore.Error

The operation did not complete; review the permissions required.

exception google.appengine.ext.blobstore.blobstore.Errorsource

Bases: exceptions.Exception

Base blobstore error type.

exception google.appengine.ext.blobstore.blobstore.InternalErrorsource

Bases: google.appengine.api.blobstore.blobstore.Error

An internal error occured.

google.appengine.ext.blobstore.blobstore.create_rpc(deadline=None, callback=None)source

Creates an RPC object to use with the Blobstore API.

Parameters

  • deadline – Optional deadline in seconds for the operation; the default value is a system-specific deadline, typically 5 seconds.

  • callback – Optional callable to invoke on completion.

Returns

An apiproxy_stub_map.UserRPC object that is specialized for this service.

google.appengine.ext.blobstore.blobstore.create_upload_url(success_path, max_bytes_per_blob=None, max_bytes_total=None, rpc=None, gs_bucket_name=None)source

Creates the upload URL for a POST form.

Parameters

  • success_path – Path within application to call when a POST call is successful and the upload is complete.

  • max_bytes_per_blob – The maximum size in bytes that any one blob in the upload can be, or None for no maximum size.

  • max_bytes_total – The maximum size in bytes that the aggregate sizes of all of the blobs in the upload can be, or None for no maximum size.

  • rpc – Optional UserRPC object.

  • gs_bucket_name – The Google Cloud Storage bucket name to which the blobs should be uploaded. The application’s service account must have the correct permissions to write to this bucket. The bucket name can be of the format bucket/path/, in which case the included path will be prepended to the uploaded object name.

Returns

The upload URL.

Raises

  • TypeError – If max_bytes_per_blob or max_bytes_total are not integral types.

  • ValueError – If max_bytes_per_blob or max_bytes_total are not positive values.

google.appengine.ext.blobstore.blobstore.create_upload_url_async(success_path, max_bytes_per_blob=None, max_bytes_total=None, rpc=None, gs_bucket_name=None)source

Asynchronously creates the upload URL for a POST form.

Parameters

  • success_path – The path within the application to call when a POST call is successful and the upload is complete.

  • max_bytes_per_blob – The maximum size in bytes that any one blob in the upload can be, or None for no maximum size.

  • max_bytes_total – The maximum size in bytes that the aggregate sizes of all of the blobs in the upload can be, or None for no maximum size.

  • rpc – Optional UserRPC object.

  • gs_bucket_name – The Google Cloud Storage bucket name to which the blobs should be uploaded. The application’s service account must have the correct permissions to write to this bucket. The bucket name can be of the format bucket/path/, in which case the included path will be prepended to the uploaded object name.

Returns

A UserRPC whose result will be the upload URL.

Raises

  • TypeError – If max_bytes_per_blob or max_bytes_total are not integral types.

  • ValueError – If max_bytes_per_blob or max_bytes_total are not positive values.

google.appengine.ext.blobstore.blobstore.delete(blob_keys, rpc=None, _token=None)source

Deletes a blob from Blobstore.

Parameters

  • blob_keys – A single BlobKey instance or a list of blob keys. A blob key can be either a string or an instance of BlobKey.

  • rpc – Optional UserRPC object.

Returns

None.

google.appengine.ext.blobstore.blobstore.delete_async(blob_keys, rpc=None, _token=None)source

Asynchronously deletes a blob from Blobstore.

Parameters

  • blob_keys – A single BlobKey instance or a list of blob keys. A blob key can be either a string or an instance of BlobKey.

  • rpc – Optional UserRPC object.

Returns

A UserRPC, whose result will be None.

google.appengine.ext.blobstore.blobstore.fetch_data(blob, start_index, end_index, rpc=None)source

Fetches data for a blob.

Fetches a fragment of a blob up to MAX_BLOB_FETCH_SIZE in length. Attempting to fetch a fragment that extends beyond the boundaries of the blob will return the amount of data from start_index until the end of the blob, which will be a smaller size than requested. Requesting a fragment that is entirely outside the boundaries of the blob will return an empty string. Attempting to fetch a negative index will raise an exception.

Parameters

  • blob – A BlobInfo, BlobKey, string, or Unicode representation of the BlobKey of the blob from which you want to fetch data.

  • start_index – The start index of blob data to fetch. This value must not be negative.

  • end_index – The end index (inclusive) of the blob data to fetch. This value must be greater than or equal to start_index.

  • rpc – Optional UserRPC object.

Returns

A string that contains partial data of a blob. If the indexes are legal but outside of the boundaries of the blob, an empty string is returned.

Raises

  • TypeError – If start_index or end_index are not indexes, or if blob is not a string, BlobKey or BlobInfo.

  • DataIndexOutOfRangeError – If start_index is set to a value that is less than 0 or end_index is less than start_index.

  • BlobFetchSizeTooLargeError – If the requested blob fragment is larger than MAX_BLOB_FETCH_SIZE.

  • BlobNotFoundError – If the blob does not exist.

google.appengine.ext.blobstore.blobstore.fetch_data_async(blob, start_index, end_index, rpc=None)source

Asynchronously fetches data for a blob.

Fetches a fragment of a blob up to MAX_BLOB_FETCH_SIZE in length. Attempting to fetch a fragment that extends beyond the boundaries of the blob will return the amount of data from start_index until the end of the blob, which will be a smaller size than requested. Requesting a fragment that is entirely outside the boundaries of the blob will return an empty string. Attempting to fetch a negative index will raise an exception.

Parameters

  • blob – A BlobInfo, BlobKey, string, or Unicode representation of the BlobKey of the blob from which you want to fetch data.

  • start_index – The start index of blob data to fetch. This value must not be negative.

  • end_index – The end index (inclusive) of the blob data to fetch. This value must be greater than or equal to start_index.

  • rpc – Optional UserRPC object.

Returns

A UserRPC whose result will be a string as returned by fetch_data().

Raises

  • TypeError – If start_index or end_index are not indexes, or if blob is not a string, BlobKey or BlobInfo.

  • DataIndexOutOfRangeError – If start_index is set to a value that is less than 0 or end_index is less than start_index when calling rpc.get_result().

  • BlobFetchSizeTooLargeError – If the requested blob fragment is larger than MAX_BLOB_FETCH_SIZE when calling rpc.get_result().

  • BlobNotFoundError – If the blob does not exist when calling rpc.get_result().

google.appengine.ext.blobstore.blobstore.create_gs_key(filename, rpc=None)source

Creates an encoded key for a Google Cloud Storage file.

It is safe to persist this key for future use.

Parameters

  • filename – The file name of the Google Cloud Storage object for which you want to create the key.

  • rpc – Optional UserRPC object.

Returns

An encrypted BlobKey string.

google.appengine.ext.blobstore.blobstore.create_gs_key_async(filename, rpc=None)source

Asynchronously creates an encoded key for a Google Cloud Storage file.

It is safe to persist this key for future use.

Parameters

  • filename – The file name of the Google Cloud Storage object for which you want to create the key.

  • rpc – Optional UserRPC object.

Returns

A UserRPC whose result will be a string as returned by create_gs_key().

Raises

  • TypeError – If filename is not a string.

  • ValueError – If filename is not in the format /gs/bucket_name/object_name.

google.appengine.ext.blobstore.blobstore.get(blob_key)source

Gets a BlobInfo record from blobstore.

Does the same as BlobInfo.get.

Parameters

blob_key – The BlobKey of the record you want to retrieve.

Returns

A BlobInfo instance that is associated with the provided key or a list of BlobInfo instances if a list of keys was provided. Keys that are not found in Blobstore return None.

google.appengine.ext.blobstore.blobstore.parse_blob_info(field_storage)source

Parses a BlobInfo record from file upload field_storage.

Parameters

field_storage – cgi.FieldStorage that represents an uploaded blob.

Returns

A BlobInfo record as parsed from the field_storage instance. This method will return None if field_storage was not defined.

Raises

BlobInfoParseError – If the provided field_storage does not contain enough information to construct a BlobInfo object.

google.appengine.ext.blobstore.blobstore.parse_file_info(field_storage)source

Parses a FileInfo record from file upload field_storage.

Parameters

field_storage – cgi.FieldStorage that represents the uploaded file.

Returns

FileInfo record as parsed from the field_storage instance. This method will return None if field_storage was not specified.

Raises

FileInfoParseError – If field_storage does not contain enough information to construct a FileInfo object.