google.appengine.ext.blobstore.blobstore module

A Python blobstore API used by app developers.

Contains methods used to interface with Blobstore API. Includes db.Model-like class representing a reference to a very large BLOB. Imports db.Key-like class representing a blob-key.

exception google.appengine.ext.blobstore.blobstore.BlobFetchSizeTooLargeError[source]

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

Raised when attempting to fetch too large a block from a blob.

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 stored by an application. Like db.Model, this class is backed by an 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: Content type of blob. creation: Creation date of blob, when it was uploaded. filename: Filename user selected from their machine. size: Size of uncompressed blob. md5_hash: The md5 hash value of the uploaded blob.

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

classmethod all()[source]

Get query for all Blobs associated with application.

Returns:
A db.Query object querying over BlobInfo’s datastore kind.
content_type
creation
delete(_token=None)[source]

Permanently delete blob from Blobstore.

filename
classmethod from_entity(entity)[source]

Convert entity to BlobInfo.

This method is required for compatibility with the current db.py query mechanism but will be removed in the future. DO NOT USE.

classmethod get(blob_keys)[source]

Retrieve BlobInfo by key or list of keys.

Args:
blob_keys: A key or a list of keys. Keys may be instances of str, unicode and BlobKey.
Returns:
A BlobInfo instance associated with provided key or a list of BlobInfo instances if a list of keys was provided. Keys that are not found in Blobstore return None as their values.
classmethod gql(query_string, *args, **kwds)[source]

Returns a query using GQL query string.

See appengine/ext/gql for more information about GQL.

Args:
query_string: Properly formatted GQL query string with the
‘SELECT * FROM <entity>’ part omitted
*args: rest of the positional arguments used to bind numeric references
in the query.

**kwds: dictionary-based arguments (for named parameters).

Returns:
A gql.GqlQuery object querying over BlobInfo’s datastore kind.
key()[source]

Get key for blob.

Returns:
BlobKey instance that identifies this blob.
classmethod kind()[source]

Get the entity kind for the BlobInfo.

This method is required for compatibility with the current db.py query mechanism but will be removed in the future. DO NOT USE.

md5_hash
open(*args, **kwargs)[source]

Returns a BlobReader for this blob.

Args:
*args, **kwargs: Passed to BlobReader constructor.
Returns:
A BlobReader instance.
classmethod properties()[source]

Set of properties that belong to BlobInfo.

This method is required for compatibility with the current db.py query mechanism but will be removed in the future. DO NOT USE.

size
exception google.appengine.ext.blobstore.blobstore.BlobInfoParseError[source]

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

CGI parameter does not contain 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

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.

Args:
old_blob_key: The blob key 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.

Args:
old_blob_key: The original blob key.
Returns:
The blobstore.BlobKey of the migrated blob.
classmethod kind()[source]
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 with for BlobKeys is efficient, the following 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.BlobNotFoundError[source]

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

Raised when attempting to access blob data for non-existant blob.

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 with for BlobKeys is efficient, the following 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]

Translate model property to datastore value.

make_value_from_datastore(value)[source]

Translate datastore value to BlobInfo.

validate(value)[source]

Validate that assigned value is BlobInfo.

Automatically converts from strings and BlobKey instances.

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.

close()[source]

Close the file.

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

closed

Returns True if this file is closed, False otherwise.

flush()[source]
next()[source]

Returns the next line from the file.

Returns:
A string, terminted by

. The last line may not be terminated by .

If EOF is reached, an empty string will be returned.
read(size=-1)[source]

Read at most size bytes from the file.

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

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

Args:
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]

Read one entire line from the file.

A trailing newline character is kept in the string (but may be absent when a file ends with an incomplete line). If the size argument is present and non-negative, it is a maximum byte count (including the trailing newline) and an incomplete line may be returned. An empty string is returned only when EOF is encountered immediately.

Args:
size: Optional. The maximum number of bytes to read.
Returns:
The read data, as a string.
readlines(sizehint=None)[source]

Read until EOF using readline() and return a list of lines thus read.

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

Args:
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]

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

The whence argument is optional and defaults to os.SEEK_SET or 0 (absolute file positioning); other values are os.SEEK_CUR or 1 (seek relative to the current position) and os.SEEK_END or 2 (seek relative to the file’s end).

Args:

offset: The relative offset to seek to. whence: Defines what the offset is relative to. See description for

details.
tell()[source]

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

truncate(size)[source]
write(str)[source]
writelines(sequence)[source]
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

Information about uploaded files.

This is a class that contains information about blobs stored by an application.

This class is similar to BlobInfo, however this has no key and it is not persisted in the datastore.

Properties:

content_type: Content type of uploaded file. creation: Creation date of uploaded file, when it was uploaded. filename: Filename user selected from their machine. size: Size of uncompressed file. md5_hash: The md5 hash value of the uploaded file. gs_object_name: Name of the file 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 AttributeError.

content_type
creation
filename
gs_object_name
md5_hash
size
exception google.appengine.ext.blobstore.blobstore.FileInfoParseError[source]

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

CGI parameter does not contain valid FileInfo record.

exception google.appengine.ext.blobstore.blobstore.DataIndexOutOfRangeError[source]

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

Raised when attempting to access indexes out of range in wrong order.

exception google.appengine.ext.blobstore.blobstore.PermissionDeniedError[source]

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

Raised when permissions are lacking for a requested operation.

exception google.appengine.ext.blobstore.blobstore.Error[source]

Bases: exceptions.Exception

Base blobstore error type.

exception google.appengine.ext.blobstore.blobstore.InternalError[source]

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

Raised when an internal error occurs within API.

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

Creates an RPC object for use with the blobstore API.

Args:
deadline: Optional deadline in seconds for the operation; the default
is a system-specific deadline (typically 5 seconds).

callback: Optional callable to invoke on completion.

Returns:
An apiproxy_stub_map.UserRPC object 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]

Create upload URL for POST form.

Args:
success_path: Path within application to call when POST is successful
and 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 Storage bucket name that the blobs should be

uploaded to. The application’s service account must have the correct permissions to write to this bucket. The bucket name may be of the foramt ‘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]

Create upload URL for POST form – async version.

Args:
success_path: Path within application to call when POST is successful
and 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 Storage bucket name that the blobs should be

uploaded to. The application’s service account must have the correct permissions to write to this bucket. The bucket name may be of the foramt ‘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]

Delete a blob from Blobstore.

Args:
blob_keys: Single instance or 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]

Delete a blob from Blobstore – async version.

Args:
blob_keys: Single instance or 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]

Fetch data for 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 which is entirely outside the boundaries of the blob will return empty string. Attempting to fetch a negative index will raise an exception.

Args:
blob: BlobInfo, BlobKey, str or unicode representation of BlobKey of
blob to fetch data from.

start_index: Start index of blob data to fetch. May not be negative. end_index: End index (inclusive) of blob data to fetch. Must be

>= start_index.

rpc: Optional UserRPC object.

Returns:
str containing partial data of blob. If the indexes are legal but outside the boundaries of the blob, will return empty string.
Raises:
TypeError if start_index or end_index are not indexes. Also when blob
is not a string, BlobKey or BlobInfo.

DataIndexOutOfRangeError when start_index < 0 or end_index < start_index. BlobFetchSizeTooLargeError when request blob fragment is larger than

MAX_BLOB_FETCH_SIZE.

BlobNotFoundError when blob does not exist.

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

Fetch data for blob – async version.

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 which is entirely outside the boundaries of the blob will return empty string. Attempting to fetch a negative index will raise an exception.

Args:
blob: BlobInfo, BlobKey, str or unicode representation of BlobKey of
blob to fetch data from.

start_index: Start index of blob data to fetch. May not be negative. end_index: End index (inclusive) of blob data to fetch. Must be

>= start_index.

rpc: Optional UserRPC object.

Returns:
A UserRPC whose result will be a str as returned by fetch_data().
Raises:
TypeError if start_index or end_index are not indexes. Also when blob
is not a string, BlobKey or BlobInfo.

The following exceptions may be raised when rpc.get_result() is called: DataIndexOutOfRangeError when start_index < 0 or end_index < start_index. BlobFetchSizeTooLargeError when request blob fragment is larger than

MAX_BLOB_FETCH_SIZE.

BlobNotFoundError when blob does not exist.

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

Create an encoded key for a Google Storage file.

It is safe to persist this key for future use.

Args:
filename: The filename of the google storage object to create the key for. rpc: Optional UserRPC object.
Returns:
An encrypted blob key string.
google.appengine.ext.blobstore.blobstore.create_gs_key_async(filename, rpc=None)[source]

Create an encoded key for a google storage file - async version.

It is safe to persist this key for future use.

Args:
filename: The filename of the google storage object to create the
key for.

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]

Get a BlobInfo record from blobstore.

Does the same as BlobInfo.get.

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

Parse a BlobInfo record from file upload field_storage.

Args:
field_storage: cgi.FieldStorage that represents uploaded blob.
Returns:
BlobInfo record as parsed from the field-storage instance. None if there was no field_storage.
Raises:
BlobInfoParseError when provided field_storage does not contain enough information to construct a BlobInfo object.
google.appengine.ext.blobstore.blobstore.parse_file_info(field_storage)[source]

Parse an FileInfo record from file upload field_storage.

Args:
field_storage: cgi.FieldStorage that represents uploaded file.
Returns:
FileInfo record as parsed from the field-storage instance. None if there was no field_storage.
Raises:
FileInfoParseError when provided a field_storage that does not contain enough information to construct a FileInfo object.