![]() |
App Engine Python SDK
v1.6.9 rev.445
The Python runtime is available as an experimental Preview feature.
|
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 | |
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.
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).
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