google.appengine.ext.ndb.blobstore module

Summary

NDB interface for Blobstore.

This currently builds on google.appengine.ext.blobstore and provides a similar API. The main API differences:

  • BlobInfo is an actual Model subclass rather than a pseudo-model class. To query, use BlobInfo.query() and its documented properties. Other changes: - The kind is ‘__BlobInfo__’ (BLOB_INFO_KIND). - key() is a method returning a BlobKey instance. - put() and friends are disabled. - Added class methods get() and friends. - Added instance methods delete() and friends, and open().

  • Instead of BlobReferenceProperty, there’s BlobKeyProperty.

  • There is no create_rpc() function. Instead, functions and methods take keyword arguments to specify deadline, callback, and (in some case) datastore options.

  • APIs (get() and delete()) that in ext.blobstore take either a blob key or a list of blob keys are split into two: one that takes a blob key and one that takes a list of blob keys, the latter having a name ending in _multi.

  • The following APIs have a synchronous and an async version: - BlobInfo.get() - BlobInfo.delete() - create_upload_url() - get() - get_multi() - delete() - delete_multi() - fetch_data()

Contents

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

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

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

class google.appengine.ext.ndb.blobstore.BlobInfo(*args, **kwds)source

Bases: google.appengine.ext.ndb.model.Model

Information about blobs in Blobstore.

This is a Model subclass that has been doctored to be unwritable.

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 (in hex).

Additional API:

Class methods: - get(): retrieve a BlobInfo by key - get_multi(): retrieve a list of BlobInfos by keys - get_async(), get_multi_async(): async version of get() and get_multi()

Instance methods: - delete(): delete this blob - delete_async(): async version of delete() - key(): return the BlobKey for this blob - open(): return a BlobReader instance for this blob

Because BlobInfo instances are synchronized with Blobstore, the class cache policies are off.

Do not subclass this class.

content_type

An indexed Property whose value is a text string of limited length.

creation

A Property whose value is a datetime object.

Note: Unlike Django, auto_now_add can be overridden by setting the value before writing the entity. And unlike classic db, auto_now does not supply a default value. Also unlike classic db, when the entity is written, the property values are updated to match what was written. Finally, beware that this also updates the value in the in-process cache, and that auto_now_add may interact weirdly with transaction retries (a retry of a property with auto_now_add set will reuse the value that was set on the first try).

delete(**options)source

Permanently delete this blob from Blobstore.

Parameters

**options – Options for create_rpc().

delete_async(**options)source

Async version of delete().

filename

An indexed Property whose value is a text string of limited length.

classmethod get(blob_key, **ctx_options)source

Retrieve a BlobInfo by key.

Parameters

  • blob_key – A blob key. This may be a str, unicode or BlobKey instance.

  • **ctx_options – Context options for Model().get_by_id().

Returns

A BlobInfo entity associated with the provided key, If there was no such entity, returns None.

classmethod get_async(blob_key, **ctx_options)source

Async version of get().

classmethod get_multi(blob_keys, **ctx_options)source

Multi-key version of get().

Parameters

  • blob_keys – A list of blob keys.

  • **ctx_options – Context options for Model().get_by_id().

Returns

A list whose items are each either a BlobInfo entity or None.

classmethod get_multi_async(blob_keys, **ctx_options)source

Async version of get_multi().

key()source

Get key for blob.

Returns

BlobKey instance that identifies this blob.

md5_hash

An indexed Property whose value is a text string of limited length.

open(*args, **kwds)source

Returns a BlobReader for this blob.

Parameters

**kwargs (*args,) –

Passed to BlobReader constructor.

Returns

A BlobReader instance.

put_async(**ctx_options)source

Cheap way to make BlobInfo entities read-only.

size

A Property whose value is a Python int or long (or bool).

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

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

The CGI parameter does not contain a valid BlobInfo record.

class google.appengine.ext.ndb.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
exception google.appengine.ext.ndb.blobstore.BlobNotFoundErrorsource

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

The blob does not exist.

class google.appengine.ext.ndb.blobstore.BlobKeyProperty(*args, **kwds)source

Bases: google.appengine.ext.ndb.model.Property

A Property whose value is a BlobKey object.

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

Bases: google.appengine.ext.blobstore.blobstore.BlobReader

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

blob_info

Returns the BlobInfo for this file.

exception google.appengine.ext.ndb.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.ndb.blobstore.PermissionDeniedErrorsource

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

The operation did not complete; review the permissions required.

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

Bases: exceptions.Exception

Base blobstore error type.

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

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

An internal error occured.

google.appengine.ext.ndb.blobstore.create_upload_url(success_path, max_bytes_per_blob=None, max_bytes_total=None, **options)source

Create upload URL for POST form.

Parameters

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

  • **options – Options for create_rpc().

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.ndb.blobstore.create_upload_url_async(*args, **kwds)source

Async version of create_upload_url().

google.appengine.ext.ndb.blobstore.delete(blob_key, **options)source

Delete a blob from Blobstore.

Parameters

  • blob_key – A blob key. This may be a str, unicode or BlobKey instance.

  • **options – Options for create_rpc().

google.appengine.ext.ndb.blobstore.delete_async(*args, **kwds)source

Async version of delete().

google.appengine.ext.ndb.blobstore.delete_multi(blob_keys, **options)source

Delete blobs from Blobstore.

Parameters

  • blob_keys – A list of blob keys.

  • **options – Options for create_rpc().

google.appengine.ext.ndb.blobstore.delete_multi_async(*args, **kwds)source

Async version of delete_multi().

google.appengine.ext.ndb.blobstore.fetch_data(blob, start_index, end_index, **options)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.

Parameters

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

  • **options – Options for create_rpc().

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.ndb.blobstore.fetch_data_async(*args, **kwds)source

Async version of fetch_data().

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

Parse a BlobInfo record from file upload field_storage.

Parameters

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.