google.appengine.ext.db.Expando

Dynamically expandable model.

Inherits From: Model, expected_type

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

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.

Args
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

@classmethod
all(
    **kwds
)

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

delete(
    **kwargs
)

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

dynamic_properties()

Determine which properties are particular to instance of entity.

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

entity_type

View source

@classmethod
entity_type()

Soon to be removed alias for kind.

fields

View source

@classmethod
fields()

Soon to be removed alias for properties.

from_entity

View source

@classmethod
from_entity(
    entity
)

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

@classmethod
get(
    keys, **kwargs
)

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

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

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

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

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

@classmethod
get_or_insert(
    key_name, **kwds
)

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

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

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

has_key()

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

instance_properties()

Alias for dyanmic_properties.

is_saved

View source

is_saved()

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

key()

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

@classmethod
kind()

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

parent()

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

parent_key()

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

@classmethod
properties()

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

put

View source

put(
    **kwargs
)

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

save(
    **kwargs
)

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

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

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