Python 3.9 is now generally available.

google.appengine.ext.db.Expando

Dynamically expandable model.

Inherits From: Model, expected_type

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.

parent Parent instance for this instance or None, indicating a top- level instance.
key_name Name for new model instance.
_app Intentionally undocumented.
args Keyword arguments mapping to properties of model.

Methods

all

View source

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

Returns
Query that will retrieve all instances from entity collection.

delete

View source

Deletes this entity from the datastore.

Args
config datastore_rpc.Configuration to use for this request.

Raises
TransactionFailedError if the data could not be committed.

dynamic_properties

View source

Determine which properties are particular to instance of entity.

Returns
Set of names which correspond only to the dynamic properties.

entity_type

View source

Soon to be removed alias for kind.

fields

View source

Soon to be removed alias for properties.

from_entity

View source

Converts the entity representation of this model to an instance.

Converts datastore.Entity instance to an instance of cls.

Args
entity Entity loaded directly from datastore.

Raises
KindError when cls is incorrect model for entity.

get

View 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 retrieved. Example:

story = Story.get(story_key)

Args
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
If a single key was given: 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.

Raises
KindError if any of the retrieved objects are not instances of the type associated with call to get.

get_by_id

View source

Returns instance of Model class by id.

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

get_by_key_name

View source

Returns instance of Model class by its key's name.

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

get_or_insert

View 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!'

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

gql

View source

Returns a query using GQL query string.

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

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

has_key

View 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

View source

Alias for dyanmic_properties.

is_saved

View 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

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

kind

View source

Returns the datastore kind we use for this model.

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

parent

View 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

View source

Get the parent's key.

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

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

properties

View source

Returns a dictionary of all the properties defined for this model.

put

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

Args
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

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

Args
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

View 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