App Engine Python SDK  v1.6.9 rev.445
The Python runtime is available as an experimental Preview feature.
Public Member Functions | List of all members
google.appengine.ext.db.polymodel.PolyModel Class Reference
Inheritance diagram for google.appengine.ext.db.polymodel.PolyModel:
google.appengine.ext.db.Model

Public Member Functions

def __new__
 
def kind
 
def class_key
 
def class_name
 
def from_entity
 
def all
 
def gql
 
- Public Member Functions inherited from google.appengine.ext.db.Model
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
 

Additional Inherited Members

- Static Public Attributes inherited from google.appengine.ext.db.Model
 save = put
 

Detailed Description

Base-class for models that supports polymorphic queries.

Use this class to build hierarchies that can be queried based
on their types.

Example:

  consider the following model hierarchy:

    +------+
    |Animal|
    +------+
      |
      +-----------------+
      |                 |
    +------+          +------+
    |Canine|          |Feline|
    +------+          +------+
      |                 |
      +-------+         +-------+
      |       |         |       |
    +---+   +----+    +---+   +-------+
    |Dog|   |Wolf|    |Cat|   |Panther|
    +---+   +----+    +---+   +-------+

  This class hierarchy has three levels.  The first is the "root class".
  All models in a single class hierarchy must inherit from this root.  All
  models in the hierarchy are stored as the same kind as the root class.
  For example, Panther entities when stored to the datastore are of the kind
  'Animal'.  Querying against the Animal kind will retrieve Cats, Dogs and
  Canines, for example, that match your query.  Different classes stored
  in the root class' kind are identified by their class-key.  When loaded
  from the datastore, it is mapped to the appropriate implementation class.

Polymorphic properties:

  Properties that are defined in a given base-class within a hierarchy are
  stored in the datastore for all sub-casses only.  So, if the Feline class
  had a property called 'whiskers', the Cat and Panther enties would also
  have whiskers, but not Animal, Canine, Dog or Wolf.

Polymorphic queries:

  When written to the datastore, all polymorphic objects automatically have
  a property called 'class' that you can query against.  Using this property
  it is possible to easily write a GQL query against any sub-hierarchy.  For
  example, to fetch only Canine objects, including all Dogs and Wolves:

    db.GqlQuery("SELECT * FROM Animal WHERE class='Canine'")

  And alternate method is to use the 'all' or 'gql' methods of the Canine
  class:

    Canine.all()
    Canine.gql('')

  The 'class' property is not meant to be used by your code other than
  for queries.  Since it is supposed to represents the real Python class
  it is intended to be hidden from view.

Root class:

  The root class is the class from which all other classes of the hierarchy
  inherits from.  Each hierarchy has a single root class.  A class is a
  root class if it is an immediate child of PolyModel.  The subclasses of
  the root class are all the same kind as the root class. In other words:

    Animal.kind() == Feline.kind() == Panther.kind() == 'Animal'

Member Function Documentation

def google.appengine.ext.db.polymodel.PolyModel.__new__ (   args,
  kwds 
)
Prevents direct instantiation of PolyModel.

Allow subclasses to call __new__() with arguments.

Do NOT list 'cls' as the first argument, or in the case when
the '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.polymodel.PolyModel.all (   cls,
  kwds 
)
Get all instance of a class hierarchy.

Args:
  kwds: Keyword parameters passed on to Model.all.

Returns:
  Query with filter set to match this class' discriminator.
def google.appengine.ext.db.polymodel.PolyModel.class_key (   cls)
Caclulate the class-key for this class.

Returns:
  Class key for class.  By default this is a the list of classes
  of the hierarchy, starting with the root class and walking its way
  down to cls.
def google.appengine.ext.db.polymodel.PolyModel.class_name (   cls)
Calculate class name for this class.

Returns name to use for each classes element within its class-key.  Used
to discriminate between different classes within a class hierarchy's
Datastore kind.

The presence of this method allows developers to use a different class
name in the datastore from what is used in Python code.  This is useful,
for example, for renaming classes without having to migrate instances
already written to the datastore.  For example, to rename a polymorphic
class Contact to SimpleContact, you could convert:

  # Class key is ['Information']
  class Information(PolyModel): ...

  # Class key is ['Information', 'Contact']
  class Contact(Information): ...

to:

  # Class key is still ['Information', 'Contact']
  class SimpleContact(Information):
...
@classmethod
def class_name(cls):
  return 'Contact'

  # Class key is ['Information', 'Contact', 'ExtendedContact']
  class ExtendedContact(SimpleContact): ...

This would ensure that all objects written previously using the old class
name would still be loaded.

Returns:
  Name of this class.
def google.appengine.ext.db.polymodel.PolyModel.from_entity (   cls,
  entity 
)
Load from entity to class based on discriminator.

Rather than instantiating a new Model instance based on the kind
mapping, this creates an instance of the correct model class based
on the entities class-key.

Args:
  entity: Entity loaded directly from datastore.

Raises:
  KindError when there is no class mapping based on discriminator.
def google.appengine.ext.db.polymodel.PolyModel.gql (   cls,
  query_string,
  args,
  kwds 
)
Returns a polymorphic query using GQL query string.

This query is polymorphic in that it has its filters configured in a way
to retrieve instances of the model or an instance of a subclass of the
model.

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.polymodel.PolyModel.kind (   cls)
Get kind of polymorphic model.

Overridden so that all subclasses of root classes are the same kind
as the root.

Returns:
  Kind of entity to write to datastore.

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