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.db package

Summary

Simple, schema-based database abstraction layer for the datastore.

Modeled after Django's abstraction layer on top of SQL databases. Ours is a little simpler and a lot less code because the datastore is so much simpler than SQL databases.

The programming model is to declare Python subclasses of the Model class, declaring datastore properties as class members of that class. So if you want to publish a story with title, body, and created date, you would do it like this:

class Story(db.Model):: title = db.StringProperty() body = db.TextProperty() created = db.DateTimeProperty(auto_now_add=True)

You can create a new Story in the datastore with this usage pattern:

story = Story(title=’My title’) story.body = ‘My body’ story.put()

You query for Story entities using built in query interfaces that map directly to the syntax and semantics of the datastore:

stories = Story.all().filter(‘date >=’, yesterday).order(‘-date’) for story in stories:

print story.title

The Property declarations enforce types by performing validation on assignment. For example, the DateTimeProperty enforces that you assign valid datetime objects, and if you supply the “required” option for a property, you will not be able to assign None to that property.

We also support references between models, so if a story has comments, you would represent it like this:

class Comment(db.Model):: story = db.ReferenceProperty(Story) body = db.TextProperty()

When you get a story out of the datastore, the story reference is resolved automatically the first time it is referenced, which makes it easy to use model instances without performing additional queries by hand:

comment = Comment.get(key) print comment.story.title

Likewise, you can access the set of comments that refer to each story through this property through a reverse reference called comment_set, which is a Query preconfigured to return all matching comments:

story = Story.get(key) for comment in story.comment_set:

print comment.body

Sub Modules
google.appengine.ext.db.metadata	Models and helper functions for access to app’s datastore metadata.
google.appengine.ext.db.polymodel	Support for polymorphic models and queries.
google.appengine.ext.db.stats	Models to be used when accessing app specific datastore usage statistics.

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

Bases: google.appengine.ext.db.UnindexedProperty

A byte string that can be longer than 1500 bytes.

data_type: alias of Blob

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

Bases: google.appengine.ext.db.Property

A boolean property.

data_type: alias of bool

empty(value)source

Is boolean property empty.

False is not an empty value.

Returns

True if value is None, else False.

validate(value)source

Validate boolean.

Returns

A valid value.

Raises

BadValueError if property is not instance of ‘bool’.

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

Bases: google.appengine.ext.db.Property

A short (<=1500 bytes) byte string.

This type should be used for short binary values that need to be indexed. If you do not require indexing (regardless of length), use BlobProperty instead.

MAX_LENGTH = 1500

data_type: alias of ByteString

validate(value)source

Validate ByteString property.

Returns

A valid value.

Raises

BadValueError if property is not instance of ‘ByteString’.

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

Bases: google.appengine.ext.db._CoercingProperty

A property whose values are Category instances.

data_type: alias of Category

class google.appengine.ext.db.ComputedProperty(value_function, indexed=True)source

Bases: google.appengine.ext.db.Property

Property used for creating properties derived from other values.

Certain attributes should never be set by users but automatically calculated at run-time from other values of the same entity. These values are implemented as persistent properties because they provide useful search keys.

A computed property behaves the same as normal properties except that you may not set values on them. Attempting to do so raises db.DerivedPropertyError which db.Model knows to ignore during entity loading time. Whenever getattr is used for the property the value is recalculated. This happens when the model calls get_value_for_datastore on the property.

Example

import string

class Person(Model):

name = StringProperty(required=True)

@db.ComputedProperty def lower_case_name(self):

return self.name.lower()

# Find all people regardless of case used in name. Person.gql(‘WHERE lower_case_name=:1’ % name_to_search_for.lower())

exception google.appengine.ext.db.ConfigurationErrorsource

Bases: google.appengine.api.datastore_errors.Error

Raised when a property or model is improperly configured.

class google.appengine.ext.db.DateProperty(verbose_name=None, auto_now=False, auto_now_add=False, **kwds)source

Bases: google.appengine.ext.db.DateTimeProperty

A date property, which stores a date without a time.

data_type: alias of date

get_updated_value_for_datastore(model_instance)source

Get new value for property to send to datastore.

Returns

now() as appropriate to the date instance in the odd case where auto_now is set to True, else AUTO_UPDATE_UNCHANGED.

get_value_for_datastore(model_instance)source

Get value from property to send to datastore.

We retrieve a datetime.date from the model instance and return a datetime.datetime instance with the time set to zero.

See base class method documentation for details.

make_value_from_datastore(value)source

Native representation of this property.

We receive a datetime.datetime retrieved from the entity and return a datetime.date instance representing its date portion.

See base class method documentation for details.

static now()source

Get now as a date datetime value.

Returns

‘date’ part of ‘now’ only.

validate(value)source

Validate date.

Returns

A valid value.

Raises

BadValueError if property is not instance of ‘date’,
or if it is an instance of ‘datetime’ (which is a subclass
of ‘date’, but for all practical purposes a different type).

class google.appengine.ext.db.DateTimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, **kwds)source

Bases: google.appengine.ext.db.Property

The base class of all of our date/time properties.

We handle common operations, like converting between time tuples and datetime instances.

data_type: alias of datetime

default_value()source

Default value for datetime.

Returns

value of now() as appropriate to the date-time instance if auto_now or auto_now_add is set, else user configured default value implementation.

get_updated_value_for_datastore(model_instance)source

Get new value for property to send to datastore.

Returns

now() as appropriate to the date-time instance in the odd case where auto_now is set to True, else AUTO_UPDATE_UNCHANGED.

static now()source

Get now as a full datetime value.

Returns

‘now’ as a whole timestamp, including both time and date.

validate(value)source

Validate datetime.

Returns

A valid value.

Raises

BadValueError if property is not instance of ‘datetime’.

exception google.appengine.ext.db.DerivedPropertyErrorsource

Bases: google.appengine.api.datastore_errors.Error

Raised when attempting to assign a value to a derived property.

exception google.appengine.ext.db.DuplicatePropertyErrorsource

Bases: google.appengine.api.datastore_errors.Error

Raised when a property is duplicated in a model definition.

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

Bases: google.appengine.ext.db._CoercingProperty

A property whose values are Email instances.

data_type: alias of Email

class google.appengine.ext.db.Expando(parent=None, key_name=None, _app=None, **kwds)source

Bases: google.appengine.ext.db.Model

Dynamically expandable model.

An Expando does not require (but can still benefit from) the definition of any properties before it can be used to store information in the datastore. Properties can be added to an expando object by simply performing an assignment. The assignment of properties is done on an instance by instance basis, so it is possible for one object of an expando type to have different properties from another or even the same properties with different types. It is still possible to define properties on an expando, allowing those properties to behave the same as on any other model.

Example

import datetime

class Song(db.Expando):: title = db.StringProperty()
crazy = Song(title=’Crazy like a diamond’,: author=’Lucy Sky’, publish_date=’yesterday’, rating=5.0)
hoboken = Song(title=’The man from Hoboken’,: author=[‘Anthony’, ‘Lou’], publish_date=datetime.datetime(1977, 5, 3))

crazy.last_minute_note=db.Text(‘Get a train to the station.’)

Possible Uses:

One use of an expando is to create an object without any specific structure and later, when your application mature and it in the right state, change it to a normal model object and define explicit properties.

Additional exceptions for expando:

Protected attributes (ones whose names begin with ‘_’) cannot be used as dynamic properties. These are names that are reserved for protected transient (non-persisted) attributes.

Order of lookup:

When trying to set or access an attribute value, any other defined properties, such as methods and other values in __dict__ take precedence over values in the datastore.

1 - Because it is not possible for the datastore to know what kind of: property to store on an undefined expando value, setting a property to None is the same as deleting it from the expando.
2 - Persistent variables on Expando must not begin with ‘_’. These: variables considered to be ‘protected’ in Python, and are used internally.
3 - Expando’s dynamic properties are not able to store empty lists.: Attempting to assign an empty list to a dynamic property will raise ValueError. Static properties on Expando can still support empty lists but like normal Model properties is restricted from using None.

dynamic_properties()source

Determine which properties are particular to instance of entity.

Returns

Set of names which correspond only to the dynamic properties.

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

Bases: google.appengine.ext.db.Property

A float property.

data_type: alias of float

empty(value)source

Is float property empty.

0.0 is not an empty value.

Returns

True if value is None, else False.

validate(value)source

Validate float.

Returns

A valid value.

Raises

BadValueError if property is not instance of ‘float’.

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

Bases: google.appengine.ext.db._CoercingProperty

A property whose values are GeoPt instances.

data_type: alias of GeoPt

class google.appengine.ext.db.GqlQuery(query_string, *args, **kwds)source

Bases: google.appengine.ext.db._BaseQuery

A Query class that uses GQL query syntax instead of .filter() etc.

bind(*args, **kwds)source

Bind arguments (positional or keyword) to the query.

Note that you can also pass arguments directly to the query constructor. Each time you call bind() the previous set of arguments is replaced with the new set. This is useful because the hard work in in parsing the query; so if you expect to be using the same query with different sets of arguments, you should hold on to the GqlQuery() object and call bind() on it each time.

Parameters

*args – Positional arguments used to bind numeric references in the query.
**kwds – Dictionary-based arguments for named references.

is_distinct()source

is_keys_only()source

projection()source

run(**kwargs)source

Iterator for this query that handles the LIMIT clause property.

If the GQL query string contains a LIMIT clause, this function fetches all results before returning an iterator. Otherwise results are retrieved in batches by the iterator.

Parameters

kwargs – Any keyword arguments accepted by datastore_query.QueryOptions().

Returns

Iterator for this query.

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

Bases: google.appengine.ext.db._CoercingProperty

A property whose values are IM instances.

data_type: alias of IM

class google.appengine.ext.db.Index(index_id, kind, has_ancestor, properties)source

Bases: google.appengine.api.datastore._BaseIndex

A datastore index.

has_ancestor()source: Indicates if this is an ancestor index, a boolean.

id()source: Returns the index id, a long.

kind()source: Returns the index kind, a string. Empty string (‘’) if none.

properties()source: Returns the index properties. a tuple of (index name as a string, [ASCENDING|DESCENDING]) tuples.

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

Bases: google.appengine.ext.db.Property

An integer property.

data_type: alias of int

empty(value)source

Is integer property empty.

0 is not an empty value.

Returns

True if value is None, else False.

validate(value)source

Validate integer property.

Returns

A valid value.

Raises

BadValueError if value is not an integer or long instance.

google.appengine.ext.db.KEY_RANGE_COLLISION = 'Collision'source

Indicates that entities with keys inside the given key range already exist and writing to this range will overwrite those entities. Additionally the implications of KEY_RANGE_COLLISION apply. If overwriting entities that exist in this range is acceptable it is safe to use the given range.

The datastore’s automatic ID allocator will never assign a key to a new entity that will overwrite an existing entity so entities written by the user to this range will never be overwritten by an entity with an automatically assigned key.

google.appengine.ext.db.KEY_RANGE_CONTENTION = 'Contention'source

Indicates the given key range is empty but the datastore’s automatic ID allocator may assign new entities keys in this range. However it is safe to manually assign keys in this range if either of the following is true:

No other request will insert entities with the same kind and parent as the given key range until all entities with manually assigned keys from this range have been written.
Overwriting entities written by other requests with the same kind and parent as the given key range is acceptable.

The datastore’s automatic ID allocator will not assign a key to a new entity that will overwrite an existing entity, so once the range is populated there will no longer be any contention.

google.appengine.ext.db.KEY_RANGE_EMPTY = 'Empty'source: Indicates the given key range is empty and the datastore’s automatic ID allocator will not assign keys in this range to new entities.

exception google.appengine.ext.db.KindErrorsource

Bases: google.appengine.api.datastore_errors.BadValueError

Raised when an entity is used with incorrect Model.

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

Bases: google.appengine.ext.db._CoercingProperty

A property whose values are Link instances.

data_type: alias of Link

validate(value)source

class google.appengine.ext.db.ListProperty(item_type, verbose_name=None, default=None, write_empty_list=None, **kwds)source

Bases: google.appengine.ext.db.Property

A property that stores a list of things.

This is a parameterized property; the parameter must be a valid non-list data type, and all items must conform to this type.

data_type: alias of list

default_value()source

Default value for list.

Because the property supplied to ‘default’ is a static value, that value must be shallow copied to prevent all fields with default values from sharing the same instance.

Returns

Copy of the default value.

empty(value)source

Is list property empty.

[] is not an empty value.

Returns

True if value is None, else false.

get_value_for_datastore(model_instance)source

Get value from property to send to datastore.

Returns

validated list appropriate to save in the datastore.

make_value_from_datastore(value)source

Native representation of this property.

If this list is a list of datetime.date or datetime.time, we convert the list of datetime.datetime retrieved from the entity into datetime.date or datetime.time.

See base class method documentation for details.

make_value_from_datastore_index_value(index_value)source

validate(value)source

Validate list.

Returns

A valid value.

Raises

BadValueError if property is not a list whose items are instances of
the item_type given to the constructor.

validate_list_contents(value)source

Validates that all items in the list are of the correct type.

Returns

The validated list.

Raises

BadValueError if the list has items are not instances of the
item_type given to the constructor.

class google.appengine.ext.db.Model(parent=None, key_name=None, _app=None, _from_entity=False, **kwds)source

Bases: object

Model is the superclass of all object entities in the datastore.

class Story(db.Model):: title = db.StringProperty() body = db.TextProperty() created = db.DateTimeProperty(auto_now_add=True)

A model instance can have a single parent. Model instances without any parent are root entities. It is possible to efficiently query for instances by their shared parent. All descendents of a single root instance also behave as a transaction group. This means that when you work one member of the group within a transaction all descendents of that root join the transaction. All operations within a transaction on this group are ACID.

classmethod all(**kwds)source

Returns a query over all instances of this model from the datastore.

Returns

Query that will retrieve all instances from entity collection.

delete(**kwargs)source

Deletes this entity from the datastore.

Parameters

config – datastore_rpc.Configuration to use for this request.

Raises

TransactionFailedError if the data could not be committed.

dynamic_properties()source: Returns a list of all dynamic properties defined for instance.

classmethod entity_type()source: Soon to be removed alias for kind.

classmethod fields()source: Soon to be removed alias for properties.

classmethod from_entity(entity)source

Converts the entity representation of this model to an instance.

Converts datastore.Entity instance to an instance of cls.

Parameters

entity – Entity loaded directly from datastore.

Raises

KindError when cls is incorrect model for entity.

classmethod get(keys, **kwargs)source

Fetch instance from the datastore of a specific Model type using key.

We support Key objects and string keys (we convert them to Key objects automatically).

Useful for ensuring that specific instance types are retrieved from the datastore. It also helps that the source code clearly indicates what kind of object is being retreived. Example:

story = Story.get(story_key)

Parameters

keys – Key within datastore entity collection to find; or string key; or list of Keys or string keys.
config – datastore_rpc.Configuration to use for this request.

Returns

a Model instance associated with key for the provided class if it exists in the datastore, otherwise None. If a list of keys was given: a list where list[i] is the Model instance for keys[i], or None if no instance exists.

Return type

If a single key was given

Raises

KindError if any of the retreived objects are not instances of the
type associated with call to ‘get’.

classmethod get_by_id(ids, parent=None, **kwargs)source

Get instance of Model class by id.

Parameters

key_names – A single id or a list of ids.
parent – Parent of instances to get. Can be a model or key.
config – datastore_rpc.Configuration to use for this request.

classmethod get_by_key_name(key_names, parent=None, **kwargs)source

Get instance of Model class by its key’s name.

Parameters

key_names – A single key-name or a list of key-names.
parent – Parent of instances to get. Can be a model or key.
config – datastore_rpc.Configuration to use for this request.

classmethod get_or_insert(key_name, **kwds)source

Transactionally retrieve or create an instance of Model class.

This acts much like the Python dictionary setdefault() method, where we first try to retrieve a Model instance with the given key name and parent. If it’s not present, then we create a new instance (using the *kwds supplied) and insert that with the supplied key name.

Subsequent calls to this method with the same key_name and parent will always yield the same entity (though not the same actual object instance), regardless of the *kwds supplied. If the specified entity has somehow been deleted separately, then the next call will create a new entity and return it.

If the ‘parent’ keyword argument is supplied, it must be a Model instance. It will be used as the parent of the new instance of this Model class if one is created.

This method is especially useful for having just one unique entity for a specific identifier. Insertion/retrieval is done transactionally, which guarantees uniqueness.

Example usage:

class WikiTopic(db.Model):: creation_date = db.DatetimeProperty(auto_now_add=True) body = db.TextProperty(required=True)

# The first time through we’ll create the new topic. wiki_word = ‘CommonIdioms’ topic = WikiTopic.get_or_insert(wiki_word,

body=’This topic is totally new!’)

assert topic.key().name() == ‘CommonIdioms’ assert topic.body == ‘This topic is totally new!’

# The second time through will just retrieve the entity. overwrite_topic = WikiTopic.get_or_insert(wiki_word,

body=’A totally different message!’)

assert topic.key().name() == ‘CommonIdioms’ assert topic.body == ‘This topic is totally new!’

Parameters

key_name – Key name to retrieve or create.
**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, the rest of 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.

Raises

TransactionFailedError if the specified Model instance could not be
retrieved or created transactionally (due to high contention, etc).

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

Returns a query using GQL query string.

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

Parameters

query_string – properly formatted GQL query string with the ‘SELECT * FROM <entity>’ part omitted
*args – rest of the positional arguments used to bind numeric references in the query.
**kwds – dictionary-based arguments (for named parameters).

has_key()source

Determine if this model instance has a complete key.

When not using a fully self-assigned Key, ids are not assigned until the data is saved to the Datastore, but instances with a key name always have a full key.

Returns

True if the object has been persisted to the datastore or has a key or has a key_name, otherwise False.

instance_properties()source: Alias for dyanmic_properties.

is_saved()source

Determine if entity is persisted in the datastore.

New instances of Model do not start out saved in the data. Objects which are saved to or loaded from the Datastore will have a True saved state.

Returns

True if object has been persisted to the datastore, otherwise False.

key()source

Unique key for this entity.

This property is only available if this entity is already stored in the datastore or if it has a full key, so it is available if this entity was fetched returned from a query, or after put() is called the first time for new entities, or if a complete key was given when constructed.

Returns

Datastore key of persisted entity.

Raises

NotSavedError when entity is not persistent.

classmethod kind()source

Returns the datastore kind we use for this model.

We just use the name of the model for now, ignoring potential collisions.

parent()source

Get the parent of the model instance.

Returns

Parent of contained entity or parent provided in constructor, None if instance has no parent.

parent_key()source

Get the parent’s key.

This method is useful for avoiding a potential fetch from the datastore but still get information about the instances parent.

Returns

Parent key of entity, None if there is no parent.

classmethod properties()source: Returns a dictionary of all the properties defined for this model.

put(**kwargs)source

Writes this model instance to the datastore.

If this instance is new, we add an entity to the datastore. Otherwise, we update this instance, and the key will remain the same.

Parameters

config – datastore_rpc.Configuration to use for this request.

Returns

The key of the instance (either the existing key or a new key).

Raises

TransactionFailedError if the data could not be committed.

save(**kwargs)source

Writes this model instance to the datastore.

If this instance is new, we add an entity to the datastore. Otherwise, we update this instance, and the key will remain the same.

Parameters

config – datastore_rpc.Configuration to use for this request.

Returns

The key of the instance (either the existing key or a new key).

Raises

TransactionFailedError if the data could not be committed.

to_xml(_entity_class=google.appengine.api.datastore.Entity)source

Generate an XML representation of this model instance.

atom and gd:namespace properties are converted to XML according to their respective schemas. For more information, see:

http://www.atomenabled.org/developers/syndication/ https://developers.google.com/gdata/docs/1.0/elements

exception google.appengine.ext.db.NotSavedErrorsource

Bases: google.appengine.api.datastore_errors.Error

Raised when a saved-object action is performed on a non-saved object.

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

Bases: google.appengine.ext.db._CoercingProperty

A property whose values are PhoneNumber instances.

data_type: alias of PhoneNumber

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

Bases: google.appengine.ext.db._CoercingProperty

A property whose values are PostalAddress instances.

data_type: alias of PostalAddress

class google.appengine.ext.db.PropertiedClass(name, bases, dct, map_kind=True)source

Bases: type

Meta-class for initializing Model classes properties.

Used for initializing Properties defined in the context of a model. By using a meta-class much of the configuration of a Property descriptor becomes implicit. By using this meta-class, descriptors that are of class Model are notified about which class they belong to and what attribute they are associated with and can do appropriate initialization via __property_config__.

Duplicate properties are not permitted.

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

Bases: object

A Property is an attribute of a Model.

It defines the type of the attribute, which determines how it is stored in the datastore and how the property values are validated. Different property types support different options, which change validation rules, default values, etc. The simplest example of a property is a StringProperty:

class Story(db.Model):: title = db.StringProperty()

creation_counter = 41

data_type: alias of str

datastore_type()source: Deprecated backwards-compatible accessor method for self.data_type.

default_value()source

Default value for unassigned values.

Returns

Default value as provided by __init__(default).

empty(value)source

Determine if value is empty in the context of this property.

For most kinds, this is equivalent to “not value”, but for kinds like bool, the test is more subtle, so subclasses can override this method if necessary.

Parameters

value – Value to validate against this Property.

Returns

True if this value is considered empty in the context of this Property type, otherwise False.

get_updated_value_for_datastore(model_instance)source

Determine new value for auto-updated property.

Some properies (e.g. DateTimeProperty, UserProperty) optionally update their value on every put(). This call must return the new desired value for such properties. For all other properties, this call must return AUTO_UPDATE_UNCHANGED.

Parameters

model_instance – Instance to get new value for.

Returns

Datastore representation of the new model value in a form that is appropriate for storing in the datastore, or AUTO_UPDATE_UNCHANGED.

get_value_for_datastore(model_instance)source

Datastore representation of this property.

Looks for this property in the given model instance, and returns the proper datastore representation of the value that can be stored in a datastore entity. Most critically, it will fetch the datastore key value for reference properties.

Some properies (e.g. DateTimeProperty, UserProperty) optionally update their value on every put(). This call must return the current value for such properties (get_updated_value_for_datastore returns the new value).

Parameters

model_instance – Instance to fetch datastore value from.

Returns

Datastore representation of the model value in a form that is appropriate for storing in the datastore.

make_value_from_datastore(value)source

Native representation of this property.

Given a value retrieved from a datastore entity, return a value, possibly converted, to be stored on the model instance. Usually this returns the value unchanged, but a property class may override this when it uses a different datatype on the model instance than on the entity.

This API is not quite symmetric with get_value_for_datastore(), because the model instance on which to store the converted value may not exist yet – we may be collecting values to be passed to a model constructor.

Parameters

value – value retrieved from the datastore entity.

Returns

The value converted for use as a model instance attribute.

make_value_from_datastore_index_value(index_value)source

validate(value)source

Assert that provided value is compatible with this property.

Parameters

value – Value to validate against this Property.

Returns

A valid value, either the input unchanged or adapted to the required type.

Raises

BadValueError if the value is not appropriate for this
property in any way.

exception google.appengine.ext.db.PropertyErrorsource

Bases: google.appengine.api.datastore_errors.Error

Raised when non-existent property is referenced.

class google.appengine.ext.db.Query(model_class=None, keys_only=False, cursor=None, namespace=None, _app=None, distinct=False, projection=None)source

Bases: google.appengine.ext.db._BaseQuery

A Query instance queries over instances of Models.

You construct a query with a model class, like this:

class Story(db.Model):: title = db.StringProperty() date = db.DateTimeProperty()

query = Query(Story)

You modify a query with filters and orders like this:

query.filter(‘title =’, ‘Foo’) query.order(‘-date’) query.ancestor(key_or_model_instance)

Every query can return an iterator, so you access the results of a query by iterating over it:

for story in query:: print story.title

For convenience, all of the filtering and ordering methods return “self”, so the easiest way to use the query interface is to cascade all filters and orders in the iterator line like this:

for story in Query(story).filter(‘title =’, ‘Foo’).order(‘-date’):: print story.title

ancestor(ancestor)source

Sets an ancestor for this query.

This restricts the query to only return results that descend from a given model instance. In other words, all of the results will have the ancestor as their parent, or parent’s parent, etc. The ancestor itself is also a possible result!

Parameters

ancestor – Model or Key (that has already been saved)

Returns

Self to support method chaining.

Raises

TypeError if the argument isn’t a Key or Model; NotSavedError
if it is, but isn’t saved yet.

filter(property_operator, value)source

Add filter to query.

Parameters

property_operator – string with the property and operator to filter by.
value – the filter value.

Returns

Self to support method chaining.

Raises

PropertyError if invalid property is provided.

is_distinct()source

is_keys_only()source

order(property)source

Set order of query result.

To use descending order, prepend ‘-‘ (minus) to the property name, e.g., ‘-date’ rather than ‘date’.

Parameters

property – Property to sort on.

Returns

Self to support method chaining.

Raises

PropertyError if invalid property is provided.

projection()source

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

Bases: google.appengine.ext.db._CoercingProperty, google.appengine.ext.db.IntegerProperty

A property whose values are Rating instances.

data_type: alias of Rating

google.appengine.ext.db.Reference: alias of ReferenceProperty

class google.appengine.ext.db.ReferenceProperty(reference_class=None, verbose_name=None, collection_name=None, **attrs)source

Bases: google.appengine.ext.db.Property

A property that represents a many-to-one reference to another model.

For example, a reference property in model A that refers to model B forms a many-to-one relationship from A to B: every instance of A refers to a single B instance, and every B instance can have many A instances refer to it.

get_value_for_datastore(model_instance)source: Get key of reference rather than reference itself.

make_value_from_datastore_index_value(index_value)source

validate(value)source

Validate reference.

Returns

A valid value.

Raises

BadValueError for the following reasons – - Value is not saved. - Object not of correct model type for reference.

exception google.appengine.ext.db.ReservedWordErrorsource

Bases: google.appengine.api.datastore_errors.Error

Raised when a property is defined for a reserved word.

google.appengine.ext.db.SelfReference(verbose_name=None, collection_name=None, **attrs)source

Create a self reference.

Function for declaring a self referencing property on a model.

Example

class HtmlNode(db.Model):: parent = db.SelfReferenceProperty(‘Parent’, ‘children’)

Parameters

verbose_name – User friendly name of property.
collection_name – Name of collection on model.

Raises

ConfigurationError if reference_class provided as parameter.

google.appengine.ext.db.SelfReferenceProperty(verbose_name=None, collection_name=None, **attrs)source

Create a self reference.

Function for declaring a self referencing property on a model.

Example

class HtmlNode(db.Model):: parent = db.SelfReferenceProperty(‘Parent’, ‘children’)

Parameters

verbose_name – User friendly name of property.
collection_name – Name of collection on model.

Raises

ConfigurationError if reference_class provided as parameter.

class google.appengine.ext.db.StringListProperty(verbose_name=None, default=None, write_empty_list=None, **kwds)source

Bases: google.appengine.ext.db.ListProperty

A property that stores a list of strings.

A shorthand for the most common type of ListProperty.

class google.appengine.ext.db.StringProperty(verbose_name=None, multiline=False, **kwds)source

Bases: google.appengine.ext.db.Property

A textual property, which can be multi- or single-line.

MAX_LENGTH = 1500

data_type: alias of basestring

validate(value)source

Validate string property.

Returns

A valid value.

Raises

BadValueError if property is not multi-line but value is.

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

Bases: google.appengine.ext.db.UnindexedProperty

A string that can be longer than 1500 bytes.

data_type: alias of Text

class google.appengine.ext.db.TimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, **kwds)source

Bases: google.appengine.ext.db.DateTimeProperty

A time property, which stores a time without a date.

data_type: alias of time

empty(value)source

Is time property empty.

“0:0” (midnight) is not an empty value.

Returns

True if value is None, else False.

get_updated_value_for_datastore(model_instance)source

Get new value for property to send to datastore.

Returns

now() as appropriate to the time instance in the odd case where auto_now is set to True, else AUTO_UPDATE_UNCHANGED.

get_value_for_datastore(model_instance)source

Get value from property to send to datastore.

We retrieve a datetime.time from the model instance and return a datetime.datetime instance with the date set to 1/1/1970.

See base class method documentation for details.

make_value_from_datastore(value)source

Native representation of this property.

We receive a datetime.datetime retrieved from the entity and return a datetime.date instance representing its time portion.

See base class method documentation for details.

static now()source

Get now as a time datetime value.

Returns

‘time’ part of ‘now’ only.

google.appengine.ext.db.URLProperty: alias of LinkProperty

class google.appengine.ext.db.UnindexedProperty(*args, **kwds)source

Bases: google.appengine.ext.db.Property

A property that isn’t indexed by either built-in or composite indices.

TextProperty and BlobProperty derive from this class.

validate(value)source

Validate property.

Returns

A valid value.

Raises

BadValueError if property is not an instance of data_type.

class google.appengine.ext.db.UserProperty(verbose_name=None, name=None, required=False, validator=None, choices=None, auto_current_user=False, auto_current_user_add=False, indexed=True)source

Bases: google.appengine.ext.db.Property

A user property.

data_type: alias of User

default_value()source

Default value for user.

Returns

Value of users.get_current_user() if auto_current_user or auto_current_user_add is set; else None. (But not the default implementation, since we don’t support the ‘default’ keyword argument.)

get_updated_value_for_datastore(model_instance)source

Get new value for property to send to datastore.

Returns

Value of users.get_current_user() if auto_current_user is set; else AUTO_UPDATE_UNCHANGED.

validate(value)source

Validate user.

Returns

A valid value.

Raises

BadValueError if property is not instance of ‘User’.

google.appengine.ext.db.allocate_id_range(model, start, end, **kwargs)source

Allocates a range of IDs with specific endpoints.

Once these IDs have been allocated they may be provided manually to newly created entities.

Since the datastore’s automatic ID allocator will never assign a key to a new entity that will cause an existing entity to be overwritten, entities written to the given key range will never be overwritten. However, writing entities with manually assigned keys in this range may overwrite existing entities (or new entities written by a separate request) depending on the key range state returned.

This method should only be used if you have an existing numeric id range that you want to reserve, e.g. bulk loading entities that already have IDs. If you don’t care about which IDs you receive, use allocate_ids instead.

Parameters

model – Model instance, Key or string to serve as a template specifying the ID sequence in which to allocate IDs. Allocated ids should only be used in entities with the same parent (if any) and kind as this key.
start – first id of the range to allocate, inclusive.
end – last id of the range to allocate, inclusive.
config – datastore_rpc.Configuration to use for this request.

Returns

One of (KEY_RANGE_EMPTY, KEY_RANGE_CONTENTION, KEY_RANGE_COLLISION). If not KEY_RANGE_EMPTY, this represents a potential issue with using the allocated key range.

google.appengine.ext.db.allocate_ids(model, size, **kwargs)source

Allocates a range of IDs of size for the model_key defined by model.

Allocates a range of IDs in the datastore such that those IDs will not be automatically assigned to new entities. You can only allocate IDs for model keys from your app. If there is an error, raises a subclass of datastore_errors.Error.

Parameters

model – Model instance, Key or string to serve as a template specifying the ID sequence in which to allocate IDs. Returned ids should only be used in entities with the same parent (if any) and kind as this key.
size – Number of IDs to allocate.
config – datastore_rpc.Configuration to use for this request.

Returns

(start, end) of the allocated range, inclusive.

google.appengine.ext.db.allocate_ids_async(model, size, **kwargs)source

Asynchronously allocates a range of IDs.

Identical to allocate_ids() except returns an asynchronous object. Call get_result() on the return value to block on the call and return the result.

google.appengine.ext.db.check_reserved_word(attr_name)source

Raise an exception if attribute name is a reserved word.

Parameters

attr_name – Name to check to see if it is a reserved word.

Raises

ReservedWordError when attr_name is determined to be a reserved word.

google.appengine.ext.db.class_for_kind(kind)source

Return base-class responsible for implementing kind.

Necessary to recover the class responsible for implementing provided kind.

Parameters

kind – Entity kind string.

Returns

Class implementation for kind.

Raises

KindError when there is no implementation for kind.

google.appengine.ext.db.create_rpc(deadline=None, callback=None, read_policy=0)source

Create an rpc for use in configuring datastore calls.

NOTE: This functions exists for backwards compatibility. Please use create_config() instead. NOTE: the latter uses ‘on_completion’, which is a function taking an argument, wherease create_rpc uses ‘callback’ which is a function without arguments.

Parameters

deadline – float, deadline for calls in seconds.
callback – callable, a callback triggered when this rpc completes, accepts one argument: the returned rpc.
read_policy – flag, set to EVENTUAL_CONSISTENCY to enable eventually consistent reads

Returns

A datastore.DatastoreRPC instance.

google.appengine.ext.db.delete(models, **kwargs)source

Delete one or more Model instances.

Parameters

models – Model instance, key, key string or iterable thereof.
config – datastore_rpc.Configuration to use for this request, must be specified as a keyword argument.

Raises

TransactionFailedError if the data could not be committed.

google.appengine.ext.db.delete_async(models, **kwargs)source

Asynchronous version of delete one or more Model instances.

Identical to db.delete() except returns an asynchronous object. Call get_result() on the return value to block on the call.

google.appengine.ext.db.get(keys, **kwargs)source

Fetch the specific Model instance with the given key from the datastore.

We support Key objects and string keys (we convert them to Key objects automatically).

Parameters

keys – Key within datastore entity collection to find; or string key; or list of Keys or string keys.
config – datastore_rpc.Configuration to use for this request, must be specified as a keyword argument.
Returns – If a single key was given: a Model instance associated with key if it exists in the datastore, otherwise None. If a list of keys was given: a list where list[i] is the Model instance for keys[i], or None if no instance exists.

google.appengine.ext.db.get_async(keys, **kwargs)source

Asynchronously fetch the specified Model instance(s) from the datastore.

Identical to db.get() except returns an asynchronous object. Call get_result() on the return value to block on the call and get the results.

google.appengine.ext.db.get_indexes(**kwargs)source

Retrieves the application indexes and their states.

Parameters

config – datastore_rpc.Configuration to use for this request, must be specified as a keyword argument.

Returns

A list of (Index, Index.[BUILDING|SERVING|DELETING|ERROR]) tuples. An index can be in the following states:

Index.BUILDING: Index is being built and therefore can not serve queries Index.SERVING: Index is ready to service queries Index.DELETING: Index is being deleted Index.ERROR: Index encounted an error in the BUILDING state

google.appengine.ext.db.get_indexes_async(**kwargs)source

Asynchronously retrieves the application indexes and their states.

Identical to get_indexes() except returns an asynchronous object. Call get_result() on the return value to block on the call and get the results.

google.appengine.ext.db.model_from_protobuf(pb, _entity_class=google.appengine.api.datastore.Entity)source

Decodes a model instance from a protocol buffer.

Parameters

pb – The protocol buffer representation of the model instance. Can be an entity_pb.EntityProto or str encoding of an entity_bp.EntityProto

Returns

Model instance resulting from decoding the protocol buffer

google.appengine.ext.db.model_is_projection(model_instance)source: Returns true if the given db.Model instance only contains a projection of the full entity.

google.appengine.ext.db.model_to_protobuf(model_instance, _entity_class=google.appengine.api.datastore.Entity)source

Encodes a model instance as a protocol buffer.

Parameters

model_instance – Model instance to encode.

Returns

entity_pb.EntityProto representation of the model instance

google.appengine.ext.db.put(models, **kwargs)source

Store one or more Model instances.

Parameters

models – Model instance or list of Model instances.
config – datastore_rpc.Configuration to use for this request, must be specified as a keyword argument.

Returns

A Key if models is an instance, a list of Keys in the same order as models if models is a list.

Raises

TransactionFailedError if the data could not be committed.

google.appengine.ext.db.put_async(models, **kwargs)source

Asynchronously store one or more Model instances.

Identical to db.put() except returns an asynchronous object. Call get_result() on the return value to block on the call and get the results.

google.appengine.ext.db.query_descendants(model_instance)source

Returns a query for all the descendants of a model instance.

Parameters

model_instance – Model instance to find the descendants of.

Returns

Query that will retrieve all entities that have the given model instance

as an ancestor. Unlike normal ancestor queries, this does not include the ancestor itself.

google.appengine.ext.db.save(models, **kwargs)source

Store one or more Model instances.

Parameters

models – Model instance or list of Model instances.
config – datastore_rpc.Configuration to use for this request, must be specified as a keyword argument.

Returns

A Key if models is an instance, a list of Keys in the same order as models if models is a list.

Raises

TransactionFailedError if the data could not be committed.

google.appengine.ext.db.to_dict(model_instance, dictionary=None)source

Convert model to dictionary.

Parameters

model_instance – Model instance for which to make dictionary.
dictionary – dict instance or compatible to receive model values. The dictionary is not cleared of original values. Similar to using dictionary.update. If dictionary is None, a new dictionary instance is created and returned.

Returns

New dictionary appropriate populated with model instances values if entity is None, else entity.

google.appengine.ext.db package

Summary

Sub Modules

Contents