Note: Python 2.7 has reached end of support on January 31, 2024. Your existing Python 2.7 applications will continue to run and receive traffic. However, App Engine might block re-deployment of applications that use runtimes after their end of support date. We recommend that you migrate to the latest supported version of Python.

google.appengine.ext.ndb.model module

Summary

Model and Property classes and associated stuff.

A model class represents the structure of entities stored in the datastore. Applications define model classes to indicate the structure of their entities, then instantiate those model classes to create entities.

All model classes must inherit (directly or indirectly) from Model. Through the magic of metaclasses, straightforward assignments in the model class definition can be used to declare the model’s structure:

class Person(Model):
  name = StringProperty()
  age = IntegerProperty()

We can now create a Person entity and write it to Cloud Datastore:

p = Person(name='Arthur Dent', age=42)
k = p.put()

The return value from put() is a Key (see the documentation for ndb/key.py), which can be used to retrieve the same entity later:

p2 = k.get()
p2 == p  # Returns True

To update an entity, simple change its attributes and write it back (note that this doesn’t change the key):

p2.name = 'Arthur Philip Dent'
p2.put()

We can also delete an entity (by using the key):

k.delete()

The property definitions in the class body tell the system the names and the types of the fields to be stored in Cloud Datastore, whether they must be indexed, their default value, and more.

Many different Property types exist. Most are indexed by default, the exceptions indicated in the list below:

StringProperty: a short text string, limited to 500 bytes
TextProperty: an unlimited text string; unindexed
BlobProperty: an unlimited byte string; unindexed
IntegerProperty: a 64-bit signed integer
FloatProperty: a double precision floating point number
BooleanProperty: a bool value
DateTimeProperty: a datetime object. Note: App Engine always uses UTC as the timezone
DateProperty: a date object
TimeProperty: a time object
GeoPtProperty: a geographical location, i.e. (latitude, longitude)
KeyProperty: a Cloud Datastore Key value, optionally constrained to referring to a specific kind
UserProperty: a User object (for backwards compatibility only)
StructuredProperty: a field that is itself structured like an entity; see below for more details
LocalStructuredProperty: like StructuredProperty but the on-disk representation is an opaque blob; unindexed
ComputedProperty: a property whose value is computed from other properties by a user-defined function. The property value is written to Cloud Datastore so that it can be used in queries, but the value from Cloud Datastore is not used when the entity is read back
GenericProperty: a property whose type is not constrained; mostly used by the Expando class (see below) but also usable explicitly
JsonProperty: a property whose value is any object that can be serialized using JSON; the value written to Cloud Datastore is a JSON representation of that object
PickleProperty: a property whose value is any object that can be serialized using Python’s pickle protocol; the value written to the Cloud Datastore is the pickled representation of that object, using the highest available pickle protocol

Most Property classes have similar constructor signatures. They accept several optional keyword arguments:

name=<string>: the name used to store the property value in the datastore. Unlike the following options, this may also be given as a positional argument
indexed=<bool>: indicates whether the property should be indexed (allowing queries on this property’s value)
repeated=<bool>: indicates that this property can have multiple values in the same entity.
write_empty_list<bool>: For repeated value properties, controls whether properties with no elements (the empty list) is written to Datastore. If true, written, if false, then nothing is written to Datastore.
required=<bool>: indicates that this property must be given a value
default=<value>: a default value if no explicit value is given
choices=<list of values>: a list or tuple of allowable values
validator=<function>: a general-purpose validation function. It will be called with two arguments (prop, value) and should either return the validated value or raise an exception. It is also allowed for the function to modify the value, but calling it again on the modified value should not modify the value further. (For example: a validator that returns value.strip() or value.lower() is fine, but one that returns value + ‘$’ is not.)
verbose_name=<value>: A human readable name for this property. This human readable name can be used for html form labels.

The repeated and required/default options are mutually exclusive: a repeated property cannot be required nor can it specify a default value (the default is always an empty list and an empty list is always an allowed value), but a required property can have a default.

Some property types have additional arguments. Some property types do not support all options.

Repeated properties are always represented as Python lists; if there is only one value, the list has only one element. When a new list is assigned to a repeated property, all elements of the list are validated. Since it is also possible to mutate lists in place, repeated properties are re-validated before they are written to the datastore.

No validation happens when an entity is read from Cloud Datastore; however property values read that have the wrong type (e.g. a string value for an IntegerProperty) are ignored.

For non-repeated properties, None is always a possible value, and no validation is called when the value is set to None. However for required properties, writing the entity to Cloud Datastore requires the value to be something other than None (and valid).

The StructuredProperty is different from most other properties; it lets you define a sub-structure for your entities. The substructure itself is defined using a model class, and the attribute value is an instance of that model class. However it is not stored in the datastore as a separate entity; instead, its attribute values are included in the parent entity using a naming convention (the name of the structured attribute followed by a dot followed by the name of the subattribute). For example:

class Address(Model):
  street = StringProperty()
  city = StringProperty()

class Person(Model):
  name = StringProperty()
  address = StructuredProperty(Address)

p = Person(name='Harry Potter',
           address=Address(street='4 Privet Drive',
                           city='Little Whinging'))
k.put()

This would write a single ‘Person’ entity with three attributes (as you could verify using the Datastore Viewer in the Admin Console):

name = 'Harry Potter'
address.street = '4 Privet Drive'
address.city = 'Little Whinging'

Structured property types can be nested arbitrarily deep, but in a hierarchy of nested structured property types, only one level can have the repeated flag set. It is fine to have multiple structured properties referencing the same model class.

It is also fine to use the same model class both as a top-level entity class and as for a structured property; however queries for the model class will only return the top-level entities.

The LocalStructuredProperty works similar to StructuredProperty on the Python side. For example:

class Address(Model):
  street = StringProperty()
  city = StringProperty()

class Person(Model):
  name = StringProperty()
  address = LocalStructuredProperty(Address)

p = Person(name='Harry Potter',
           address=Address(street='4 Privet Drive',
                           city='Little Whinging'))
k.put()

However the data written to Cloud Datastore is different; it writes a ‘Person’ entity with a ‘name’ attribute as before and a single ‘address’ attribute whose value is a blob which encodes the Address value (using the standard”protocol buffer” encoding).

Sometimes the set of properties is not known ahead of time. In such cases you can use the Expando class. This is a Model subclass that creates properties on the fly, both upon assignment and when loading an entity from Cloud Datastore. For example:

class SuperPerson(Expando):
  name = StringProperty()
  superpower = StringProperty()

razorgirl = SuperPerson(name='Molly Millions',
                        superpower='bionic eyes, razorblade hands',
                        rasta_name='Steppin' Razor',
                        alt_name='Sally Shears')
elastigirl = SuperPerson(name='Helen Parr',
                         superpower='stretchable body')
elastigirl.max_stretch = 30  # Meters

You can inspect the properties of an expando instance using the _properties attribute:

>>> print razorgirl._properties.keys() ['rasta_name', 'name', 'superpower', 'alt_name'] >>> print elastigirl._properties {'max_stretch': GenericProperty('max_stretch'), 'name': StringProperty('name'), 'superpower': StringProperty('superpower')}

Note: this property exists for plain Model instances too; it is just not as interesting for those.

The Model class offers basic query support. You can create a Query object by calling the query() class method. Iterating over a Query object returns the entities matching the query one at a time.

Query objects are fully described in the docstring for query.py, but there is one handy shortcut that is only available through Model.query(): positional arguments are interpreted as filter expressions which are combined through an AND operator. For example:

Person.query(Person.name == 'Harry Potter', Person.age >= 11)

is equivalent to:

Person.query().filter(Person.name == 'Harry Potter', Person.age >= 11)

Keyword arguments passed to .query() are passed along to the Query() constructor.

It is possible to query for field values of structured properties. For example:

qry = Person.query(Person.address.city == 'London')

A number of top-level functions also live in this module:

transaction() runs a function inside a transaction
get_multi() reads multiple entities at once
put_multi() writes multiple entities at once
delete_multi() deletes multiple entities at once

All these have a corresponding *_async() variant as well. The *_multi_async() functions return a list of Futures.

And finally these (without async variants):

in_transaction() tests whether you are currently running in a transaction
@transactional decorates functions that should be run in a transaction

There are many other interesting features. For example, Model subclasses may define pre-call and post-call hooks for most operations (get, put, delete, allocate_ids), and Property classes may be subclassed to suit various needs. Documentation for writing a Property subclass is in the docstring for the Property class.

class google.appengine.ext.ndb.model.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.model.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.model.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.model.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.model.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.model.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.model.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.model.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.model.ModelAttributesource

Bases: object

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

class google.appengine.ext.ndb.model.ModelKeysource

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

Special property to store the Model key.

class google.appengine.ext.ndb.model.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.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.model.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.model.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.model.transaction_async(*args, **kwds)source

Run a callback in a transaction.

This is the asynchronous version of transaction().

google.appengine.ext.ndb.model.in_transaction()source: Return whether a transaction is currently active.

google.appengine.ext.ndb.model.transactional(_func=None, **options)source

google.appengine.ext.ndb.model.transactional_async(_func=None, **options)source

google.appengine.ext.ndb.model.transactional_tasklet(_func=None, **options)source

google.appengine.ext.ndb.model.non_transactional(_func=None, **options)source

google.appengine.ext.ndb.model.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.model.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.model.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.model.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.model.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.model.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.model.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.model.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.model.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.model.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.model.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.model.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.model.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.model.BadProjectionError: alias of InvalidPropertyError

class google.appengine.ext.ndb.model.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.model.TimeProperty(*args, **kwds)source

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

A Property whose value is a time object.

class google.appengine.ext.ndb.model.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.model.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.model.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.model.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.model.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.model.BooleanProperty(*args, **kwds)source

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

A Property whose value is a Python bool.

class google.appengine.ext.ndb.model.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.model.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.model.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.model.DateProperty(*args, **kwds)source

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

A Property whose value is a date object.

class google.appengine.ext.ndb.model.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.model.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.model.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.model.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.model.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.