google.appengine.ext.ndb package

Summary

NDB – A new datastore API for the Google App Engine Python runtime.

Sub Modules

google.appengine.ext.ndb.blobstore

NDB interface for Blobstore.

google.appengine.ext.ndb.context

Context class.

google.appengine.ext.ndb.django_middleware

Django middleware for NDB.

google.appengine.ext.ndb.eventloop

An event loop.

google.appengine.ext.ndb.google_imports

Dynamically decide from where to import Google App Engine modules.

google.appengine.ext.ndb.key

The Key class, and associated utilities.

google.appengine.ext.ndb.metadata

Models and helper functions for access to app’s datastore metadata.

google.appengine.ext.ndb.model

Model and Property classes and associated stuff.

google.appengine.ext.ndb.msgprop

MessageProperty – a property storing ProtoRPC Message objects.

google.appengine.ext.ndb.polymodel

Polymorphic models and queries.

google.appengine.ext.ndb.query

Higher-level Query wrapper.

google.appengine.ext.ndb.stats

Models to be used when accessing app specific datastore usage statistics.

google.appengine.ext.ndb.tasklets

A tasklet decorator.

google.appengine.ext.ndb.utils

Low-level utilities used internally by NDB.

Contents

google.appengine.ext.ndb.Return

alias of StopIteration

google.appengine.ext.ndb.tasklet(func)source
google.appengine.ext.ndb.synctasklet(func)source

Decorator to run a function as a tasklet when called.

Use this to wrap a request handler function that will be called by some web application framework (e.g. a Django view function or a webapp.RequestHandler.get method).

google.appengine.ext.ndb.toplevel(func)source

A sync tasklet that sets a fresh default Context.

Use this for toplevel view functions such as webapp.RequestHandler.get() or Django view functions.

google.appengine.ext.ndb.sleep(dt)source

Public function to sleep some time.

Example

yield tasklets.sleep(0.5) # Sleep for half a sec.

google.appengine.ext.ndb.add_flow_exception(exc)source

Add an exception that should not be logged.

The argument must be a subclass of Exception.

google.appengine.ext.ndb.get_return_value(err)source
google.appengine.ext.ndb.get_context()source
google.appengine.ext.ndb.set_context(new_context)source
google.appengine.ext.ndb.make_default_context()source
google.appengine.ext.ndb.make_context(*args, **kwds)source
class google.appengine.ext.ndb.Future(info=None)source

Bases: object

A Future has 0 or more callbacks.

The callbacks will be called when the result is ready.

NOTE: This is somewhat inspired but not conformant to the Future interface defined by PEP 3148. It is also inspired (and tries to be somewhat compatible with) the App Engine specific UserRPC and MultiRpc classes.

FINISHING = 2
IDLE = 0
RUNNING = 1
add_callback(callback, *args, **kwds)source
add_immediate_callback(callback, *args, **kwds)source
check_success()source
done()source
dump()source
dump_stack()source
get_exception()source
get_result()source
get_traceback()source
set_exception(exc, tb=None)source
set_result(result)source
state
wait()source
classmethod wait_all(futures)source
classmethod wait_any(futures)source
class google.appengine.ext.ndb.MultiFuture(info=None)source

Bases: google.appengine.ext.ndb.tasklets.Future

A Future that depends on multiple other Futures.

This is used internally by ‘v1, v2, … = yield f1, f2, …’; the semantics (e.g. error handling) are constrained by that use case.

The protocol from the caller’s POV is:

mf = MultiFuture()
mf.add_dependent(<some other Future>)  -OR- mf.putq(<some value>)
mf.add_dependent(<some other Future>)  -OR- mf.putq(<some value>)
  .
  . (More mf.add_dependent() and/or mf.putq() calls)
  .
mf.complete()  # No more dependents will be added.
  .
  . (Time passes)
  .
results = mf.get_result()

Now, results is a list of results from all dependent Futures in the order in which they were added.

It is legal to add the same dependent multiple times.

Callbacks can be added at any point.

From a dependent Future POV, there’s nothing to be done: a callback is automatically added to each dependent Future which will signal its completion to the MultiFuture.

Error handling: if any dependent future raises an error, it is propagated to mf. To force an early error, you can call mf.set_exception() instead of mf.complete(). After this you can’t call mf.add_dependent() or mf.putq() any more.

add_dependent(fut)source
complete()source
putq(value)source
set_exception(exc, tb=None)source
class google.appengine.ext.ndb.QueueFuture(info=None)source

Bases: google.appengine.ext.ndb.tasklets.Future

A Queue following the same protocol as MultiFuture.

However, instead of returning results as a list, it lets you retrieve results as soon as they are ready, one at a time, using getq(). The Future itself finishes with a result of None when the last result is ready (regardless of whether it was retrieved).

The getq() method returns a Future which blocks until the next result is ready, and then returns that result. Each getq() call retrieves one unique result. Extra getq() calls after the last result is already returned return EOFError as their Future’s exception. (I.e., q.getq() returns a Future as always, but yieding that Future raises EOFError.)

NOTE: Values can also be pushed directly via .putq(value). However there is no flow control – if the producer is faster than the consumer, the queue will grow unbounded.

add_dependent(fut)source
complete()source
getq()source
putq(value)source
set_exception(exc, tb=None)source
class google.appengine.ext.ndb.SerialQueueFuture(info=None)source

Bases: google.appengine.ext.ndb.tasklets.Future

Like QueueFuture but maintains the order of insertion.

This class is used by Query operations.

Invariants:

  • At least one of _queue and _waiting is empty.

  • The Futures in _waiting are always pending.

(The Futures in _queue may be pending or completed.)

In the discussion below, add_dependent() is treated the same way as putq().

If putq() is ahead of getq(), the situation is like this:

putq() v

_queue: [f1, f2, …]; _waiting: [] ^ getq()

Here, putq() appends a Future to the right of _queue, and getq() removes one from the left.

If getq() is ahead of putq(), it’s like this:

putq() v

_queue: []; _waiting: [f1, f2, …]

^ getq()

Here, putq() removes a Future from the left of _waiting, and getq() appends one to the right.

When both are empty, putq() appends a Future to the right of _queue, while getq() appends one to the right of _waiting.

The _full flag means that no more calls to putq() will be made; it is set by calling either complete() or set_exception().

Calling complete() signals that no more putq() calls will be made. If getq() is behind, subsequent getq() calls will eat up _queue until it is empty, and after that will return a Future that passes EOFError (note that getq() itself never raises EOFError). If getq() is ahead when complete() is called, the Futures in _waiting are all passed an EOFError exception (thereby eating up _waiting).

If, instead of complete(), set_exception() is called, the exception and traceback set there will be used instead of EOFError.

add_dependent(fut)source
complete()source
getq()source
putq(value)source
set_exception(exc, tb=None)source
class google.appengine.ext.ndb.ReducingFuture(reducer, info=None, batch_size=20)source

Bases: google.appengine.ext.ndb.tasklets.Future

A Queue following the same protocol as MultiFuture.

However the result, instead of being a list of results of dependent Futures, is computed by calling a ‘reducer’ tasklet. The reducer tasklet takes a list of values and returns a single value. It may be called multiple times on sublists of values and should behave like e.g. sum().

NOTE: The reducer input values may be reordered compared to the order in which they were added to the queue.

add_dependent(fut)source
complete()source
putq(value)source
set_exception(exc, tb=None)source
class google.appengine.ext.ndb.Keysource

Bases: object

An immutable datastore key.

For flexibility and convenience, multiple constructor signatures are supported.

The primary way to construct a key is using positional arguments: - Key(kind1, id1, kind2, id2, …).

This is shorthand for either of the following two longer forms: - Key(pairs=[(kind1, id1), (kind2, id2), …]) - Key(flat=[kind1, id1, kind2, id2, …])

Either of the above constructor forms can additionally pass in another key using parent=<key>. The (kind, id) pairs of the parent key are inserted before the (kind, id) pairs passed explicitly.

You can also construct a Key from a ‘url-safe’ encoded string: - Key(urlsafe=<string>)

For esoteric purposes the following constructors exist: - Key(reference=<reference>) – passing in a low-level Reference object - Key(serialized=<string>) – passing in a serialized low-level Reference - Key(<dict>) – for unpickling, the same as Key(**<dict>)

The ‘url-safe’ string is really a websafe-base64-encoded serialized Reference, but it’s best to think of it as just an opaque unique string.

Additional constructor keyword arguments: - app=<string> – specify the application id - namespace=<string> – specify the namespace

If a Reference is passed (using one of reference, serialized or urlsafe), the args and namespace keywords must match what is already present in the Reference (after decoding if necessary). The parent keyword cannot be combined with a Reference in any form.

Keys are immutable, which means that a Key object cannot be modified once it has been created. This is enforced by the implementation as well as Python allows.

For access to the contents of a key, the following methods and operations are supported:

  • repr(key), str(key) – return a string representation resembling the shortest constructor form, omitting the app and namespace unless they differ from the default value.

  • key1 == key2, key1 != key2 – comparison for equality between Keys.

  • hash(key) – a hash value sufficient for storing Keys in a dict.

  • key.pairs() – a tuple of (kind, id) pairs.

  • key.flat() – a tuple of flattened kind and id values, i.e. (kind1, id1, kind2, id2, …).

  • key.app() – the application id.

  • key.id() – the string or integer id in the last (kind, id) pair, or None if the key is incomplete.

  • key.string_id() – the string id in the last (kind, id) pair, or None if the key has an integer id or is incomplete.

  • key.integer_id() – the integer id in the last (kind, id) pair, or None if the key has a string id or is incomplete.

  • key.namespace() – the namespace.

  • key.kind() – a shortcut for key.pairs()[-1][0].

  • key.parent() – a Key constructed from all but the last (kind, id) pairs.

  • key.urlsafe() – a websafe-base64-encoded serialized Reference.

  • key.serialized() – a serialized Reference.

  • key.reference() – a Reference object. The caller promises not to mutate it.

Keys also support interaction with the datastore; these methods are the only ones that engage in any kind of I/O activity. For Future objects, see the document for ndb/tasklets.py.

  • key.get() – return the entity for the Key.

  • key.get_async() – return a Future whose eventual result is the entity for the Key.

  • key.delete() – delete the entity for the Key.

  • key.delete_async() – asynchronously delete the entity for the Key.

Keys may be pickled.

Subclassing Key is best avoided; it would be hard to get right.

app()source

Return the application id.

delete(**ctx_options)source

Synchronously delete the entity for this Key.

This is a no-op if no such entity exists.

delete_async(**ctx_options)source

Schedule deletion of the entity for this Key.

This returns a Future, whose result becomes available once the deletion is complete. If no such entity exists, a Future is still returned. In all cases the Future’s result is None (i.e. there is no way to tell whether the entity existed or not).

flat()source

Return a tuple of alternating kind and id values.

classmethod from_old_key(old_key)source
get(**ctx_options)source

Synchronously get the entity for this Key.

Return None if there is no such entity.

get_async(**ctx_options)source

Return a Future whose result is the entity for this Key.

If no such entity exists, a Future is still returned, and the Future’s eventual return result be None.

id()source

Return the string or integer id in the last (kind, id) pair, if any.

Returns

A string or integer id, or None if the key is incomplete.

integer_id()source

Return the integer id in the last (kind, id) pair, if any.

Returns

An integer id, or None if the key has a string id or is incomplete.

kind()source

Return the kind of the entity referenced.

This is the kind from the last (kind, id) pair.

namespace()source

Return the namespace.

pairs()source

Return a tuple of (kind, id) pairs.

parent()source

Return a Key constructed from all but the last (kind, id) pairs.

If there is only one (kind, id) pair, return None.

reference()source

Return the Reference object for this Key.

This is a entity_pb.Reference instance – a protocol buffer class used by the lower-level API to the datastore.

NOTE: The caller should not mutate the return value.

root()source

Return the root key. This is either self or the highest parent.

serialized()source

Return a serialized Reference object for this Key.

string_id()source

Return the string id in the last (kind, id) pair, if any.

Returns

A string id, or None if the key has an integer id or is incomplete.

to_old_key()source
urlsafe()source

Return a url-safe string encoding this Key’s Reference.

This string is compatible with other APIs and languages and with the strings used to represent Keys in GQL and in the App Engine Admin Console.

class google.appengine.ext.ndb.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.ndb.GeoPt(lat, lon=None)source

Bases: object

A geographical point, specified by floating-point latitude and longitude coordinates. Often used to integrate with mapping sites like Google Maps. May also be used as ICBM coordinates.

This is the georss:point element. In XML output, the coordinates are provided as the lat and lon attributes. See: http://georss.org/

Serializes to ‘<lat>,<lon>’. Raises BadValueError if it’s passed an invalid serialized string, or if lat and lon are not valid floating points in the ranges [-90, 90] and [-180, 180], respectively.

ToXml()source
lat = None
lon = None
exception google.appengine.ext.ndb.Rollbacksource

Bases: google.appengine.api.datastore_errors.Error

May be raised by transaction functions when they want to roll back instead of committing. Note that any exception raised by a transaction function will cause a rollback. This is purely for convenience. See datastore.RunInTransaction for details.

class google.appengine.ext.ndb.Indexsource

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

Immutable object representing an index.

ancestor

Whether this is an ancestor index, a bool.

kind

The kind being indexed, a string.

properties

A list of PropertyIndex objects giving the properties being indexed.

class google.appengine.ext.ndb.IndexStatesource

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

Immutable object representing and index and its state.

definition

An Index object describing the index.

id

The index ID, an integer.

state

The index state, a string.

Possible values are ‘error’, ‘deleting’, ‘serving’ or ‘building’.

class google.appengine.ext.ndb.IndexPropertysource

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

Immutable object representing a single property in an index.

direction

The direction in the index for this property, ‘asc’ or ‘desc’.

name

The property name being indexed, a string.

class google.appengine.ext.ndb.ModelAdapter(default_model=None, id_resolver=None)source

Bases: google.appengine.datastore.datastore_rpc.AbstractAdapter

Conversions between ‘our’ Key and Model classes and protobufs.

This is needed to construct a Connection object, which in turn is needed to construct a Context object.

See the base class docstring for more info about the signatures.

entity_to_pb(ent)source
key_to_pb(key)source
pb_to_entity(pb)source
pb_to_index(pb)source
pb_to_key(pb)source
class google.appengine.ext.ndb.ModelAttributesource

Bases: object

A Base class signifying the presence of a _fix_up() method.

class google.appengine.ext.ndb.ModelKeysource

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

Special property to store the Model key.

class google.appengine.ext.ndb.MetaModel(name, bases, classdict)source

Bases: type

Metaclass for Model.

This exists to fix up the properties – they need to know their name. This is accomplished by calling the class’s _fix_properties() method.

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

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

A class describing Cloud Datastore entities.

Model instances are usually called entities. All model classes inheriting from Model automatically have MetaModel as their metaclass, so that the properties are fixed up properly after the class once the class is defined.

Because of this, you cannot use the same Property object to describe multiple properties – you must create separate Property objects for each property. E.g. this does not work:

wrong_prop = StringProperty()
class Wrong(Model):
  wrong1 = wrong_prop
  wrong2 = wrong_prop

The kind is normally equal to the class name (exclusive of the module name or any other parent scope). To override the kind, define a class method named _get_kind(), as follows:

class MyModel(Model):
  @classmethod
  def _get_kind(cls):
    return 'AnotherKind'
classmethod allocate_ids(size=None, max=None, parent=None, **ctx_options)source

Allocates a range of key IDs for this model class.

Parameters
  • size – Number of IDs to allocate. Either size or max can be specified, not both.

  • max – Maximum ID to allocate. Either size or max can be specified, not both.

  • parent – Parent key for which the IDs will be allocated.

  • **ctx_options – Context options.

Returns

A tuple with (start, end) for the allocated range, inclusive.

classmethod allocate_ids_async(size=None, max=None, parent=None, **ctx_options)source

Allocates a range of key IDs for this model class.

This is the asynchronous version of Model._allocate_ids().

classmethod get_by_id(*args, **kwds)source

Returns an instance of Model class by ID.

This is really just a shorthand for Key(cls, id, …).get().

Parameters
  • id – A string or integer key ID.

  • parent – Optional parent key of the model to get.

  • namespace – Optional namespace.

  • app – Optional app ID.

  • **ctx_options – Context options.

Returns

A model instance or None if not found.

classmethod get_by_id_async(*args, **kwds)source

Returns an instance of Model class by ID (and app, namespace).

This is the asynchronous version of Model._get_by_id().

classmethod get_or_insert(*args, **kwds)source

Transactionally retrieves an existing entity or creates a new one.

Positional Args:

name: Key name to retrieve or create.

Keyword Arguments
  • namespace – Optional namespace.

  • app – Optional app ID.

  • parent – Parent entity key, if any.

  • context_options – ContextOptions object (not keyword args!) or None.

  • **kwds – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied key_name and parent already exists, these arguments will be discarded.

Returns

Existing instance of Model class with the specified key name and parent or a new one that has just been created.

classmethod get_or_insert_async(*args, **kwds)source

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of Model._get_or_insert().

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

Run a GQL query.

has_complete_key()source

Return whether this entity has a complete key.

key

Special property to store the Model key.

populate(**kwds)source

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Keywords must refer to valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provisions for key, id or parent are made.

put(**ctx_options)source

Write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Returns

The key for the entity. This is always a complete key.

put_async(**ctx_options)source

Write this entity to Cloud Datastore.

This is the asynchronous version of Model._put().

classmethod query(*args, **kwds)source

Create a Query object for this class.

Parameters
  • distinct – Optional bool, short hand for group_by = projection.

  • *args – Used to apply an initial filter

  • **kwds – are passed to the Query() constructor.

Returns

A Query object.

to_dict(*args, **kwds)source

Return a dict containing the entity’s property values.

Parameters
  • include – Optional set of property names to include, default all.

  • exclude – Optional set of property names to skip, default none. A name contained in both include and exclude is excluded.

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

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

Model subclass to support dynamic Property names and types.

See the module docstring for details.

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

Run a callback in a transaction.

Parameters
  • callback – A function or tasklet to be called.

  • **ctx_options – Transaction options.

Useful options include:

retries=N: Retry up to N times (i.e. try up to N+1 times) propagation=<flag>: Determines how an existing transaction should be

propagated, where <flag> can be one of the following: TransactionOptions.NESTED: Start a nested transaction (this is the

default; but actual nested transactions are not yet implemented, so effectively you can only use this outside an existing transaction).

TransactionOptions.MANDATORY: A transaction must already be in progress. TransactionOptions.ALLOWED: If a transaction is in progress, join it. TransactionOptions.INDEPENDENT: Always start a new parallel transaction.

xg=True: On the High Replication Datastore, enable cross-group

transactions, i.e. allow writing to up to 5 entity groups.

read_only=True: Indicates a transaction will not do any writes, which

potentially allows for more throughput.

WARNING: Using anything other than NESTED for the propagation flag can have strange consequences. When using ALLOWED or MANDATORY, if an exception is raised, the transaction is likely not safe to commit. When using INDEPENDENT it is not generally safe to return values read to the caller (as they were not read in the caller’s transaction).

Returns

Whatever callback() returns.

Raises
  • Whatever callback() raises; datastore_errors.TransactionFailedError

  • if the transaction failed.

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

Run a callback in a transaction.

This is the asynchronous version of transaction().

google.appengine.ext.ndb.in_transaction()source

Return whether a transaction is currently active.

google.appengine.ext.ndb.transactional(_func=None, **options)source
google.appengine.ext.ndb.transactional_async(_func=None, **options)source
google.appengine.ext.ndb.transactional_tasklet(_func=None, **options)source
google.appengine.ext.ndb.non_transactional(_func=None, **options)source
google.appengine.ext.ndb.get_multi(keys, **ctx_options)source

Fetches a sequence of keys.

Parameters
  • keys – A sequence of keys.

  • **ctx_options – Context options.

Returns

A list whose items are either a Model instance or None if the key wasn’t found.

google.appengine.ext.ndb.get_multi_async(keys, **ctx_options)source

Fetches a sequence of keys.

Parameters
  • keys – A sequence of keys.

  • **ctx_options – Context options.

Returns

A list of futures.

google.appengine.ext.ndb.put_multi(entities, **ctx_options)source

Stores a sequence of Model instances.

Parameters
  • entities – A sequence of Model instances.

  • **ctx_options – Context options.

Returns

A list with the stored keys.

google.appengine.ext.ndb.put_multi_async(entities, **ctx_options)source

Stores a sequence of Model instances.

Parameters
  • entities – A sequence of Model instances.

  • **ctx_options – Context options.

Returns

A list of futures.

google.appengine.ext.ndb.delete_multi(keys, **ctx_options)source

Deletes a sequence of keys.

Parameters
  • keys – A sequence of keys.

  • **ctx_options – Context options.

Returns

A list whose items are all None, one per deleted key.

google.appengine.ext.ndb.delete_multi_async(keys, **ctx_options)source

Deletes a sequence of keys.

Parameters
  • keys – A sequence of keys.

  • **ctx_options – Context options.

Returns

A list of futures.

google.appengine.ext.ndb.get_indexes(**ctx_options)source

Get a data structure representing the configured indexes.

Parameters

**ctx_options – Context options.

Returns

A list of Index objects.

google.appengine.ext.ndb.get_indexes_async(**ctx_options)source

Get a data structure representing the configured indexes.

Parameters

**ctx_options – Context options.

Returns

A future.

google.appengine.ext.ndb.make_connection(config=None, default_model=None, _api_version=u'datastore_v3', _id_resolver=None)source

Create a new Connection object with the right adapter.

Optionally you can pass in a datastore_rpc.Configuration object.

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

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

A Property whose value is a byte string. It may be compressed.

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

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

A property whose value is any Json-encodable Python object.

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

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

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

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

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

A Property whose value is a Python float.

Note: int, long and bool are also allowed.

google.appengine.ext.ndb.BadProjectionError

alias of InvalidPropertyError

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

Bases: google.appengine.ext.ndb.model._StructuredGetForDictMixin, google.appengine.ext.ndb.model.BlobProperty

Substructure that is serialized to an opaque blob.

This looks like StructuredProperty on the Python side, but is written like a BlobProperty in Cloud Datastore. It is not indexed and you cannot query for subproperties. On the other hand, the on-disk representation is more efficient and can be made even more efficient by passing compressed=True, which compresses the blob data using gzip.

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

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

A Property whose value is a time object.

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

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

A Property whose value is a User object.

Note: this exists for backwards compatibility with existing Cloud Datastore schemas only; we do not recommend storing User objects directly in Cloud Datastore, but instead recommend storing the user.user_id() value.

exception google.appengine.ext.ndb.InvalidPropertyErrorsource

Bases: google.appengine.api.datastore_errors.Error

Raised when a property is not applicable to a given use.

For example, a property must exist and be indexed to be used in a query’s projection or group by clause.

exception google.appengine.ext.ndb.KindErrorsource

Bases: google.appengine.api.datastore_errors.BadValueError

Raised when an implementation for a kind can’t be found.

Also raised when the Kind is not an 8-bit string.

class google.appengine.ext.ndb.ComputedProperty(func, name=None, indexed=None, repeated=None, verbose_name=None)source

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

A Property whose value is determined by a user-supplied function.

Computed properties cannot be set directly, but are instead generated by a function when required. They are useful to provide fields in Cloud Datastore that can be used for filtering or sorting without having to manually set the value in code - for example, sorting on the length of a BlobProperty, or using an equality filter to check if another field is not empty.

ComputedProperty can be declared as a regular property, passing a function as the first argument, or it can be used as a decorator for the function that does the calculation.

Example:

>>> class DatastoreFile(Model): ... name = StringProperty() ... name_lower = ComputedProperty(lambda self: self.name.lower()) ... ... data = BlobProperty() ... ... @ComputedProperty ... def size(self): ... return len(self.data) ... ... def _compute_hash(self): ... return hashlib.sha1(self.data).hexdigest() ... hash = ComputedProperty(_compute_hash, name='sha1')
class google.appengine.ext.ndb.KeyProperty(*args, **kwds)source

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

A Property whose value is a Key object.

Optional keyword argument: kind=<kind>, to require that keys assigned to this property always have the indicated kind. May be a string or a Model subclass.

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

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

A Property whose value is a Python bool.

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

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

A Property whose value is any picklable Python object.

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

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

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

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

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

A class describing a typed, persisted attribute of a Cloud Datastore entity.

Not to be confused with Python’s ‘property’ built-in.

This is just a base class; there are specific subclasses that describe Properties of various types (and GenericProperty which describes a dynamically typed Property).

All special Property attributes, even those considered ‘public’, have names starting with an underscore, because StructuredProperty uses the non-underscore attribute namespace to refer to nested Property names; this is essential for specifying queries on subproperties (see the module docstring).

The Property class and its predefined subclasses allow easy subclassing using composable (or stackable) validation and conversion APIs. These require some terminology definitions:

  • A ‘user value’ is a value such as would be set and accessed by the application code using standard attributes on the entity.

  • A ‘base value’ is a value such as would be serialized to and deserialized from Cloud Datastore.

The values stored in ent._values[name] and accessed by _store_value() and _retrieve_value() can be either user values or base values. To retrieve user values, use _get_user_value(). To retrieve base values, use _get_base_value(). In particular, _get_value() calls _get_user_value(), and _serialize() effectively calls _get_base_value().

To store a user value, just call _store_value(). To store a base value, wrap the value in a _BaseValue() and then call _store_value().

A Property subclass that wants to implement a specific transformation between user values and serialiazble values should implement two methods, _to_base_type() and _from_base_type(). These should NOT call their super() method; super calls are taken care of by _call_to_base_type() and _call_from_base_type(). This is what is meant by composable (or stackable) APIs.

The API supports ‘stacking’ classes with ever more sophisticated user<–>base conversions: the user–>base conversion goes from more sophisticated to less sophisticated, while the base–>user conversion goes from less sophisticated to more sophisticated. For example, see the relationship between BlobProperty, TextProperty and StringProperty.

In addition to _to_base_type() and _from_base_type(), the _validate() method is also a composable API.

The validation API distinguishes between ‘lax’ and ‘strict’ user values. The set of lax values is a superset of the set of strict values. The _validate() method takes a lax value and if necessary converts it to a strict value. This means that when setting the property value, lax values are accepted, while when getting the property value, only strict values will be returned. If no conversion is needed, _validate() may return None. If the argument is outside the set of accepted lax values, _validate() should raise an exception, preferably TypeError or datastore_errors.BadValueError.

Example/boilerplate:

def _validate(self, value):

‘Lax user value to strict user value.’ if not isinstance(value, <top type>):

raise TypeError(…) # Or datastore_errors.BadValueError(…).

def _to_base_type(self, value):

‘(Strict) user value to base value.’ if isinstance(value, <user type>):

return <base type>(value)

def _from_base_type(self, value):

‘base value to (strict) user value.’ if not isinstance(value, <base type>):

return <user type>(value)

Things that _validate(), _to_base_type() and _from_base_type() do not need to handle:

  • None: They will not be called with None (and if they return None, this means that the value does not need conversion).

  • Repeated values: The infrastructure (_get_user_value() and _get_base_value()) takes care of calling _from_base_type() or _to_base_type() for each list item in a repeated value.

  • Wrapping values in _BaseValue(): The wrapping and unwrapping is taken care of by the infrastructure that calls the composable APIs.

  • Comparisons: The comparison operations call _to_base_type() on their operand.

  • Distinguishing between user and base values: the infrastructure guarantees that _from_base_type() will be called with an (unwrapped) base value, and that _to_base_type() will be called with a user value.

  • Returning the original value: if any of these return None, the original value is kept. (Returning a differen value not equal to None will substitute the different value.)

IN(value)source

Comparison operator for the ‘in’ comparison operator.

The Python ‘in’ operator cannot be overloaded in the way we want to, so we define a method. For example:

Employee.query(Employee.rank.IN([4, 5, 6]))

Note that the method is called ._IN() but may normally be invoked as .IN(); ._IN() is provided for the case you have a StructuredProperty with a model that has a Property named IN.

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

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

A Property whose value is a date object.

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

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

An unindexed Property whose value is a text string of unlimited length.

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

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

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

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

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

A Property whose value can be (almost) any basic type.

This is mainly used for Expando and for orphans (values present in Cloud Datastore but not represented in the Model subclass) but can also be used explicitly for properties with dynamically-typed values.

This supports compressed=True, which is only effective for str values (not for unicode), and implies indexed=False.

exception google.appengine.ext.ndb.UnprojectedPropertyErrorsource

Bases: google.appengine.api.datastore_errors.Error

Raised when getting a property value that’s not in the projection.

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

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

A Property whose value is itself an entity.

The values of the sub-entity are indexed and can be queried.

See the module docstring for details.

IN(value)source
class google.appengine.ext.ndb.GeoPtProperty(*args, **kwds)source

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

A Property whose value is a GeoPt.

exception google.appengine.ext.ndb.ComputedPropertyErrorsource

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

Raised when attempting to set a value to or delete a computed property.

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

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

A Property whose value is a BlobKey object.

exception google.appengine.ext.ndb.ReadonlyPropertyErrorsource

Bases: google.appengine.api.datastore_errors.Error

Raised when attempting to set a property value that is read-only.

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

Bases: object

Query object.

Usually constructed by calling Model.query().

See module docstring for examples.

Note that not all operations on Queries are supported by _MultiQuery instances; the latter are generated as necessary when any of the operators !=, IN or OR is used.

analyze()source

Return a list giving the parameters required by a query.

ancestor

Accessor for the ancestor (a Key or None).

app

Accessor for the app (a string or None).

bind(*args, **kwds)source

Bind parameter values. Returns a new Query object.

count(*args, **kwds)source

Count the number of query results, up to a limit.

This returns the same result as len(q.fetch(limit)) but more efficiently.

Note that you must pass a maximum value to limit the amount of work done by the query.

Parameters
  • limit – How many results to count at most.

  • **q_options – All query options keyword arguments are supported.

Returns:

count_async(*args, **kwds)source

Count the number of query results, up to a limit.

This is the asynchronous version of Query.count().

default_options

Accessor for the default_options (a QueryOptions instance or None).

fetch(*args, **kwds)source

Fetch a list of query results, up to a limit.

Parameters
  • limit – How many results to retrieve at most.

  • **q_options – All query options keyword arguments are supported.

Returns

A list of results.

fetch_async(*args, **kwds)source

Fetch a list of query results, up to a limit.

This is the asynchronous version of Query.fetch().

fetch_page(*args, **kwds)source

Fetch a page of results.

This is a specialized method for use by paging user interfaces.

Parameters

page_size – The requested page size. At most this many results will be returned.

In addition, any keyword argument supported by the QueryOptions class is supported. In particular, to fetch the next page, you pass the cursor returned by one call to the next call using start_cursor=<cursor>. A common idiom is to pass the cursor to the client using <cursor>.to_websafe_string() and to reconstruct that cursor on a subsequent request using Cursor.from_websafe_string(<string>).

Returns

A tuple (results, cursor, more) where results is a list of query results, cursor is a cursor pointing just after the last result returned, and more is a bool indicating whether there are (likely) more results after that.

fetch_page_async(*args, **kwds)source

Fetch a page of results.

This is the asynchronous version of Query.fetch_page().

filter(*args)source

Return a new Query with additional filter(s) applied.

filters

Accessor for the filters (a Node or None).

get(**q_options)source

Get the first query result, if any.

This is similar to calling q.fetch(1) and returning the first item of the list of results, if any, otherwise None.

Parameters

**q_options – All query options keyword arguments are supported.

Returns

A single result, or None if there are no results.

get_async(**q_options)source

Get the first query result, if any.

This is the asynchronous version of Query.get().

group_by

Accessor for the group by properties (a tuple instance or None).

is_distinct

True if results are guaranteed to contain a unique set of property values.

This happens when every property in the group_by is also in the projection.

iter(**q_options)source

Construct an iterator over the query.

Parameters

**q_options – All query options keyword arguments are supported.

Returns

A QueryIterator object.

kind

Accessor for the kind (a string or None).

map(*args, **kwds)source

Map a callback function or tasklet over the query results.

Parameters
  • callback – A function or tasklet to be applied to each result; see below.

  • merge_future – Optional Future subclass; see below.

  • **q_options – All query options keyword arguments are supported.

Callback signature: The callback is normally called with an entity as argument. However if keys_only=True is given, it is called with a Key. Also, when pass_batch_into_callback is True, it is called with three arguments: the current batch, the index within the batch, and the entity or Key at that index. The callback can return whatever it wants. If the callback is None, a trivial callback is assumed that just returns the entity or key passed in (ignoring produce_cursors).

Optional merge future: The merge_future is an advanced argument that can be used to override how the callback results are combined into the overall map() return value. By default a list of callback return values is produced. By substituting one of a small number of specialized alternatives you can arrange otherwise. See tasklets.MultiFuture for the default implementation and a description of the protocol the merge_future object must implement the default. Alternatives from the same module include QueueFuture, SerialQueueFuture and ReducingFuture.

Returns

When the query has run to completion and all callbacks have returned, map() returns a list of the results of all callbacks. (But see ‘optional merge future’ above.)

map_async(*args, **kwds)source

Map a callback function or tasklet over the query results.

This is the asynchronous version of Query.map().

namespace

Accessor for the namespace (a string or None).

order(*args)source

Return a new Query with additional sort order(s) applied.

orders

Accessor for the filters (a datastore_query.Order or None).

projection

Accessor for the projected properties (a tuple instance or None).

run_to_queue(*args, **kwds)source

Run this query, putting entities into the given queue.

class google.appengine.ext.ndb.QueryOptionssource

Bases: google.appengine.ext.ndb.context.ContextOptions, google.appengine.datastore.datastore_query.QueryOptions

Support both context options and query options (esp. use_cache).

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

Bases: google.appengine.datastore.datastore_query._BaseComponent

An immutable class that represents a relative position in a query.

The position denoted by a Cursor is relative to a result in a query even if the result has been removed from the given query. Usually to position immediately after the last result returned by a batch.

A cursor should only be used on a query with an identical signature to the one that produced it or on a query with its sort order reversed.

advance(offset, query, conn)source

Advances a Cursor by the given offset.

Parameters
  • offset – The amount to advance the current query.

  • query – A Query identical to the one this cursor was created from.

  • conn – The datastore_rpc.Connection to use.

Returns

A new cursor that is advanced by offset using the given query.

static from_bytes(cursor)source

Gets a Cursor given its byte string serialized form.

The serialized form of a cursor may change in a non-backwards compatible way. In this case cursors must be regenerated from a new Query request.

Parameters

cursor – A serialized cursor as returned by .to_bytes.

Returns

A Cursor.

Raises
  • datastore_errors.BadValueError if the cursor argument does not represent a

  • serialized cursor.

static from_websafe_string(cursor)source

Gets a Cursor given its websafe serialized form.

The serialized form of a cursor may change in a non-backwards compatible way. In this case cursors must be regenerated from a new Query request.

Parameters

cursor – A serialized cursor as returned by .to_websafe_string.

Returns

A Cursor.

Raises
  • datastore_errors.BadValueError if the cursor argument is not a string

  • type of does not represent a serialized cursor.

reversed()source

DEPRECATED. It is no longer necessary to call reversed() on cursors.

A cursor returned by a query may also be used in a query whose sort order has been reversed. This method returns a copy of the original cursor.

to_bytes()source

Serialize cursor as a byte string.

to_websafe_string()source

Serialize cursor as a websafe string.

Returns

A base64-encoded serialized cursor.

urlsafe()source

Serialize cursor as a websafe string.

Returns

A base64-encoded serialized cursor.

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

Bases: object

This iterator works both for synchronous and async callers!

For synchronous callers, just use:

for entity in Account.query():

<use entity>

Async callers use this idiom:

it = iter(Account.query()) while (yield it.has_next_async()):

entity = it.next() <use entity>

You can also use q.iter([options]) instead of iter(q); this allows passing query options such as keys_only or produce_cursors.

When keys_only is set, it.next() returns a key instead of an entity.

When produce_cursors is set, the methods it.cursor_before() and it.cursor_after() return Cursor objects corresponding to the query position just before and after the item returned by it.next(). Before it.next() is called for the first time, both raise an exception. Once the loop is exhausted, both return the cursor after the last item returned. Calling it.has_next() does not affect the cursors; you must call it.next() before the cursors move. Note that sometimes requesting a cursor requires a Cloud Datastore roundtrip (but not if you happen to request a cursor corresponding to a batch boundary). If produce_cursors is not set, both methods always raise an exception.

Note that queries requiring in-memory merging of multiple queries (i.e. queries using the IN, != or OR operators) do not support query options.

cursor_after()source

Return the cursor after the current item.

You must pass a QueryOptions object with produce_cursors=True for this to work.

If there is no cursor or no current item, raise BadArgumentError. Before next() has returned there is no cursor. Once the loop is exhausted, this returns the cursor after the last item.

cursor_before()source

Return the cursor before the current item.

You must pass a QueryOptions object with produce_cursors=True for this to work.

If there is no cursor or no current item, raise BadArgumentError. Before next() has returned there is no cursor. Once the loop is exhausted, this returns the cursor after the last item.

has_next()source

Return whether a next item is available.

See the module docstring for the usage pattern.

has_next_async(*args, **kwds)source

Return a Future whose result will say whether a next item is available.

See the module docstring for the usage pattern.

index_list()source

Return the list of indexes used for this query.

This returns a list of index representations, where an index representation is the same as what is returned by get_indexes().

Before the first result, the information is unavailable, and then None is returned. This is not the same as an empty list – the empty list means that no index was used to execute the query. (In the dev_appserver, an empty list may also mean that only built-in indexes were used; metadata queries also return an empty list here.)

Proper use is as follows:

q = <modelclass>.query(<filters>) i = q.iter() try:

i.next()

except Stopiteration:

pass

indexes = i.index_list() assert isinstance(indexes, list)

Notes: - Forcing produce_cursors=False makes this always return None. - This always returns None for a multi-query.

next()source

Iterator protocol: get next item or raise StopIteration.

probably_has_next()source

Return whether a next item is (probably) available.

This is not quite the same as has_next(), because when

produce_cursors is set, some shortcuts are possible. However, in some cases (e.g. when the query has a post_filter) we can get a false positive (returns True but next() will raise StopIteration). There are no false negatives.

class google.appengine.ext.ndb.RepeatedStructuredPropertyPredicate(match_keys, pb, key_prefix)source

Bases: google.appengine.datastore.datastore_query.FilterPredicate

google.appengine.ext.ndb.AND

alias of ConjunctionNode

google.appengine.ext.ndb.OR

alias of DisjunctionNode

class google.appengine.ext.ndb.ConjunctionNodesource

Bases: google.appengine.ext.ndb.query.Node

Tree node representing a Boolean AND operator on two or more nodes.

resolve(bindings, used)source
class google.appengine.ext.ndb.DisjunctionNodesource

Bases: google.appengine.ext.ndb.query.Node

Tree node representing a Boolean OR operator on two or more nodes.

resolve(bindings, used)source
class google.appengine.ext.ndb.FilterNodesource

Bases: google.appengine.ext.ndb.query.Node

Tree node for a single filter expression.

class google.appengine.ext.ndb.PostFilterNodesource

Bases: google.appengine.ext.ndb.query.Node

Tree node representing an in-memory filtering operation.

This is used to represent filters that cannot be executed by the datastore, for example a query for a structured value.

class google.appengine.ext.ndb.FalseNodesource

Bases: google.appengine.ext.ndb.query.Node

Tree node for an always-failing filter.

class google.appengine.ext.ndb.Nodesource

Bases: object

Base class for filter expression tree nodes.

Tree nodes are considered immutable, even though they can contain Parameter instances, which are not. In particular, two identical trees may be represented by the same Node object in different contexts.

resolve(bindings, used)source

Return a Node with Parameters replaced by the selected values.

Parameters
  • bindings – A dict mapping integers and strings to values.

  • used – A dict into which use of use of a binding is recorded.

Returns

A Node instance.

class google.appengine.ext.ndb.ParameterNodesource

Bases: google.appengine.ext.ndb.query.Node

Tree node for a parameterized filter.

resolve(bindings, used)source
class google.appengine.ext.ndb.ParameterizedThingsource

Bases: object

Base class for Parameter and ParameterizedFunction.

This exists purely for isinstance() checks.

class google.appengine.ext.ndb.Parameter(key)source

Bases: google.appengine.ext.ndb.query.ParameterizedThing

Represents a bound variable in a GQL query.

Parameter(1) corresponds to a slot labeled “:1” in a GQL query. Parameter(‘xyz’) corresponds to a slot labeled “:xyz”.

The value must be set (bound) separately by calling .set(value).

key

Retrieve the key.

resolve(bindings, used)source
class google.appengine.ext.ndb.ParameterizedFunction(func, values)source

Bases: google.appengine.ext.ndb.query.ParameterizedThing

Represents a GQL function with parameterized arguments.

For example, ParameterizedFunction(‘key’, [Parameter(1)]) stands for the GQL syntax KEY(:1).

func
is_parameterized()source
resolve(bindings, used)source
values
google.appengine.ext.ndb.gql(query_string, *args, **kwds)source

Parse a GQL query string.

Parameters
  • query_string – Full GQL query, e.g. ‘SELECT * FROM Kind WHERE prop = 1’.

  • **kwds (*args,) –

    If present, used to call bind().

Returns

An instance of query_class.

class google.appengine.ext.ndb.Context(conn=None, auto_batcher_class=google.appengine.ext.ndb.context.AutoBatcher, config=None, parent_context=None)source

Bases: object

allocate_ids(*args, **kwds)source
call_on_commit(callback)source

Call a callback upon successful commit of a transaction.

If not in a transaction, the callback is called immediately.

In a transaction, multiple callbacks may be registered and will be called once the transaction commits, in the order in which they were registered. If the transaction fails, the callbacks will not be called.

If the callback raises an exception, it bubbles up normally. This means: If the callback is called immediately, any exception it raises will bubble up immediately. If the call is postponed until commit, remaining callbacks will be skipped and the exception will bubble up through the transaction() call. (However, the transaction is already committed at that point.)

clear_cache()source

Clears the in-memory cache.

NOTE: This does not affect memcache.

static default_cache_policy(key)source

Default cache policy.

This defers to _use_cache on the Model class.

Parameters

key – Key instance.

Returns

A bool or None.

static default_datastore_policy(key)source

Default datastore policy.

This defers to _use_datastore on the Model class.

Parameters

key – Key instance.

Returns

A bool or None.

static default_memcache_policy(key)source

Default memcache policy.

This defers to _use_memcache on the Model class.

Parameters

key – Key instance.

Returns

A bool or None.

static default_memcache_timeout_policy(key)source

Default memcache timeout policy.

This defers to _memcache_timeout on the Model class.

Parameters

key – Key instance.

Returns

Memcache timeout to use (integer), or None.

delete(*args, **kwds)source
flush(*args, **kwds)source
get(*args, **kwds)source

Return a Model instance given the entity key.

It will use the context cache if the cache policy for the given key is enabled.

Parameters
  • key – Key instance.

  • **ctx_options – Context options.

Returns

A Model instance if the key exists in the datastore; None otherwise.

get_cache_policy()source

Return the current context cache policy function.

Returns

A function that accepts a Key instance as argument and returns a bool indicating if it should be cached. May be None.

get_datastore_policy()source

Return the current context datastore policy function.

Returns

A function that accepts a Key instance as argument and returns a bool indicating if it should use the datastore. May be None.

get_indexes(*args, **kwds)source
get_memcache_policy()source

Return the current memcache policy function.

Returns

A function that accepts a Key instance as argument and returns a bool indicating if it should be cached. May be None.

get_memcache_timeout_policy()source

Return the current policy function for memcache timeout (expiration).

in_transaction()source

Return whether a transaction is currently active.

iter_query(*args, **kwds)source
map_query(*args, **kwds)source
memcache_add(key, value, time=0, namespace=None, deadline=None)source
memcache_cas(key, value, time=0, namespace=None, deadline=None)source
memcache_decr(key, delta=1, initial_value=None, namespace=None, deadline=None)source
memcache_delete(key, seconds=0, namespace=None, deadline=None)source
memcache_get(key, for_cas=False, namespace=None, use_cache=False, deadline=None)source

An auto-batching wrapper for memcache.get() or .get_multi().

Parameters
  • key – Key to set. This must be a string; no prefix is applied.

  • for_cas – If True, request and store CAS ids on the Context.

  • namespace – Optional namespace.

  • deadline – Optional deadline for the RPC.

Returns

A Future (!) whose return value is the value retrieved from memcache, or None.

memcache_gets(key, namespace=None, use_cache=False, deadline=None)source
memcache_incr(key, delta=1, initial_value=None, namespace=None, deadline=None)source
memcache_replace(key, value, time=0, namespace=None, deadline=None)source
memcache_set(key, value, time=0, namespace=None, use_cache=False, deadline=None)source
put(*args, **kwds)source
set_cache_policy(func)source

Set the context cache policy function.

Parameters

func – A function that accepts a Key instance as argument and returns a bool indicating if it should be cached. May be None.

set_datastore_policy(func)source

Set the context datastore policy function.

Parameters

func – A function that accepts a Key instance as argument and returns a bool indicating if it should use the datastore. May be None.

set_memcache_policy(func)source

Set the memcache policy function.

Parameters

func – A function that accepts a Key instance as argument and returns a bool indicating if it should be cached. May be None.

set_memcache_timeout_policy(func)source

Set the policy function for memcache timeout (expiration).

Parameters

func – A function that accepts a key instance as argument and returns an integer indicating the desired memcache timeout. May be None.

If the function returns 0 it implies the default timeout.

transaction(*args, **kwds)source
urlfetch(*args, **kwds)source
class google.appengine.ext.ndb.ContextOptionssource

Bases: google.appengine.datastore.datastore_rpc.Configuration

Configuration options that may be passed along with get/put/delete.

max_memcache_items

A descriptor for a Configuration option.

This class is used to create a configuration option on a class that inherits from BaseConfiguration. A validator function decorated with this class will be converted to a read-only descriptor and BaseConfiguration will implement constructor and merging logic for that configuration option. A validator function takes a single non-None value to validate and either throws an exception or returns that value (or an equivalent value). A validator is called once at construction time, but only if a non-None value for the configuration option is specified the constructor’s keyword arguments.

memcache_deadline

A descriptor for a Configuration option.

This class is used to create a configuration option on a class that inherits from BaseConfiguration. A validator function decorated with this class will be converted to a read-only descriptor and BaseConfiguration will implement constructor and merging logic for that configuration option. A validator function takes a single non-None value to validate and either throws an exception or returns that value (or an equivalent value). A validator is called once at construction time, but only if a non-None value for the configuration option is specified the constructor’s keyword arguments.

memcache_timeout

A descriptor for a Configuration option.

This class is used to create a configuration option on a class that inherits from BaseConfiguration. A validator function decorated with this class will be converted to a read-only descriptor and BaseConfiguration will implement constructor and merging logic for that configuration option. A validator function takes a single non-None value to validate and either throws an exception or returns that value (or an equivalent value). A validator is called once at construction time, but only if a non-None value for the configuration option is specified the constructor’s keyword arguments.

use_cache

A descriptor for a Configuration option.

This class is used to create a configuration option on a class that inherits from BaseConfiguration. A validator function decorated with this class will be converted to a read-only descriptor and BaseConfiguration will implement constructor and merging logic for that configuration option. A validator function takes a single non-None value to validate and either throws an exception or returns that value (or an equivalent value). A validator is called once at construction time, but only if a non-None value for the configuration option is specified the constructor’s keyword arguments.

use_datastore

A descriptor for a Configuration option.

This class is used to create a configuration option on a class that inherits from BaseConfiguration. A validator function decorated with this class will be converted to a read-only descriptor and BaseConfiguration will implement constructor and merging logic for that configuration option. A validator function takes a single non-None value to validate and either throws an exception or returns that value (or an equivalent value). A validator is called once at construction time, but only if a non-None value for the configuration option is specified the constructor’s keyword arguments.

use_memcache

A descriptor for a Configuration option.

This class is used to create a configuration option on a class that inherits from BaseConfiguration. A validator function decorated with this class will be converted to a read-only descriptor and BaseConfiguration will implement constructor and merging logic for that configuration option. A validator function takes a single non-None value to validate and either throws an exception or returns that value (or an equivalent value). A validator is called once at construction time, but only if a non-None value for the configuration option is specified the constructor’s keyword arguments.

class google.appengine.ext.ndb.TransactionOptionssource

Bases: google.appengine.ext.ndb.context.ContextOptions, google.appengine.datastore.datastore_rpc.TransactionOptions

Support both context options and transaction options.

class google.appengine.ext.ndb.AutoBatcher(todo_tasklet, limit)source

Bases: object

Batches multiple async calls if they share the same rpc options.

Here is an example to explain what this class does.

Life of a key.get_async(options) API call: *) Key gets the singleton Context instance and invokes Context.get. *) Context.get calls Context._get_batcher.add(key, options). This

returns a future “fut” as the return value of key.get_async. At this moment, key.get_async returns.

*) When more than “limit” number of _get_batcher.add() was called,

_get_batcher invokes its self._todo_tasklet, Context._get_tasklet, with the list of keys seen so far.

*) Context._get_tasklet fires a MultiRPC and waits on it. *) Upon MultiRPC completion, Context._get_tasklet passes on the results

to the respective “fut” from key.get_async.

*) If user calls “fut”.get_result() before “limit” number of add() was called,

“fut”.get_result() will repeatedly call eventloop.run1().

*) After processing immediate callbacks, eventloop will run idlers.

AutoBatcher._on_idle is an idler.

*) _on_idle will run the “todo_tasklet” before the batch is full.

So the engine is todo_tasklet, which is a proxy tasklet that can combine arguments into batches and passes along results back to respective futures. This class is mainly a helper that invokes todo_tasklet with the right arguments at the right time.

action()source
add(arg, options=None)source

Adds an arg and gets back a future.

Parameters
  • arg – one argument for _todo_tasklet.

  • options – rpc options.

Returns

An instance of future, representing the result of running

_todo_tasklet without batching.

add_once(arg, options=None)source
flush(*args, **kwds)source
run_queue(options, todo)source

Actually run the _todo_tasklet.