App Engine Python SDK  v1.6.9 rev.445
The Python runtime is available as an experimental Preview feature.
Public Member Functions | Static Public Attributes | List of all members
google.appengine.ext.db.Model Class Reference
Inheritance diagram for google.appengine.ext.db.Model:
google.appengine.ext.admin._AhAdminXsrfToken_ google.appengine.ext.blobstore.blobstore.BlobMigrationRecord google.appengine.ext.cloudstorage.cloudstorage_stub._AE_GCSFileInfo_ google.appengine.ext.cloudstorage.cloudstorage_stub._AE_GCSPartialFile_ google.appengine.ext.datastore_admin.backup_handler.BackupInformation google.appengine.ext.datastore_admin.backup_handler.KindBackupFiles google.appengine.ext.datastore_admin.backup_handler.SchemaAggregationResult google.appengine.ext.datastore_admin.utils.DatastoreAdminOperation google.appengine.ext.datastore_admin.utils.DatastoreAdminOperationJob google.appengine.ext.db.Expando google.appengine.ext.db.metadata.BaseMetadata google.appengine.ext.db.polymodel.PolyModel google.appengine.ext.db.stats.BaseStatistic google.appengine.ext.deferred.deferred._DeferredTaskEntity google.appengine.ext.ereporter.ereporter.ExceptionRecord google.appengine.ext.mapreduce.model._HugeTaskPayload google.appengine.ext.mapreduce.model.MapreduceControl google.appengine.ext.mapreduce.model.MapreduceState google.appengine.ext.mapreduce.model.ShardState google.appengine.ext.mapreduce.shuffler._OutputFile google.appengine.ext.search.SearchableModel

Public Member Functions

def __new__
 
def __init__
 
def key
 
def put
 
def delete
 
def is_saved
 
def has_key
 
def dynamic_properties
 
def instance_properties
 
def parent
 
def parent_key
 
def to_xml
 
def get
 
def get_by_key_name
 
def get_by_id
 
def get_or_insert
 
def all
 
def gql
 
def from_entity
 
def kind
 
def entity_type
 
def properties
 
def fields
 

Static Public Attributes

 save = put
 

Detailed Description

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

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)

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.

Constructor & Destructor Documentation

def google.appengine.ext.db.Model.__init__ (   self,
  parent = None,
  key_name = None,
  _app = None,
  _from_entity = False,
  kwds 
)
Creates a new instance of this model.

To create a new entity, you instantiate a model and then call put(),
which saves the entity to the datastore:

   person = Person()
   person.name = 'Bret'
   person.put()

You can initialize properties in the model in the constructor with keyword
arguments:

   person = Person(name='Bret')

We initialize all other properties to the default value (as defined by the
properties in the model definition) if they are not provided in the
constructor.

Args:
  parent: Parent instance for this instance or None, indicating a top-
level instance.
  key_name: Name for new model instance.
  _from_entity: Intentionally undocumented.
  kwds: Keyword arguments mapping to properties of model.  Also:
key: Key instance for this instance, if provided makes parent and
     key_name redundant (they do not need to be set but if they are
     they must match the key).

Member Function Documentation

def google.appengine.ext.db.Model.__new__ (   args,
  unused_kwds 
)
Allow subclasses to call __new__() with arguments.

Do NOT list 'cls' as the first argument, or in the case when
the 'unused_kwds' dictionary contains the key 'cls', the function
will complain about multiple argument values for 'cls'.

Raises:
  TypeError if there are no positional arguments.
def google.appengine.ext.db.Model.all (   cls,
  kwds 
)
Returns a query over all instances of this model from the datastore.

Returns:
  Query that will retrieve all instances from entity collection.
def google.appengine.ext.db.Model.delete (   self,
  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.
def google.appengine.ext.db.Model.dynamic_properties (   self)
Returns a list of all dynamic properties defined for instance.
def google.appengine.ext.db.Model.entity_type (   cls)
Soon to be removed alias for kind.
def google.appengine.ext.db.Model.fields (   cls)
Soon to be removed alias for properties.
def google.appengine.ext.db.Model.from_entity (   cls,
  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.
def google.appengine.ext.db.Model.get (   cls,
  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 retreived.  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 retreived objects are not instances of the
  type associated with call to 'get'.
def google.appengine.ext.db.Model.get_by_id (   cls,
  ids,
  parent = None,
  kwargs 
)
Get 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.
def google.appengine.ext.db.Model.get_by_key_name (   cls,
  key_names,
  parent = None,
  kwargs 
)
Get 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.
def google.appengine.ext.db.Model.get_or_insert (   cls,
  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).
def google.appengine.ext.db.Model.gql (   cls,
  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).
def google.appengine.ext.db.Model.has_key (   self)
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.
def google.appengine.ext.db.Model.instance_properties (   self)
Alias for dyanmic_properties.
def google.appengine.ext.db.Model.is_saved (   self)
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.
def google.appengine.ext.db.Model.key (   self)
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.
def google.appengine.ext.db.Model.kind (   cls)
Returns the datastore kind we use for this model.

We just use the name of the model for now, ignoring potential collisions.
def google.appengine.ext.db.Model.parent (   self)
Get the parent of the model instance.

Returns:
  Parent of contained entity or parent provided in constructor, None if
  instance has no parent.
def google.appengine.ext.db.Model.parent_key (   self)
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.
def google.appengine.ext.db.Model.properties (   cls)
Returns a dictionary of all the properties defined for this model.
def google.appengine.ext.db.Model.put (   self,
  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.
def google.appengine.ext.db.Model.to_xml (   self,
  _entity_class = 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/
  http://code.google.com/apis/gdata/common-elements.html

The documentation for this class was generated from the following file: