#!/usr/bin/env python

#

# Copyright 2007 Google Inc.

#

# Licensed under the Apache License, Version 2.0 (the "License");

# you may not use this file except in compliance with the License.

# You may obtain a copy of the License at

#

#     http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an "AS IS" BASIS,

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and

# limitations under the License.

#

"""Support for polymorphic models and queries.

The Model class on its own is only able to support functional polymorphism.

It is possible to create a subclass of Model and then subclass that one as

many generations as necessary and those classes will share all the same

properties and behaviors.  The problem is that subclassing Model in this way

places each subclass in their own Kind.  This means that it is not possible

to do polymorphic queries.  Building a query on a base class will only return

instances of that class from the Datastore, while queries on a subclass will

only return those instances.

This module allows applications to specify class hierarchies that support

polymorphic queries.

"""

from google.appengine.ext import db

_class_map = {}

_CLASS_KEY_PROPERTY = 'class'

class _ClassKeyProperty(db.ListProperty):

  """Property representing class-key property of a polymorphic class.

  The class key is a list of strings describing an polymorphic instances

  place within its class hierarchy.  This property is automatically calculated.

  For example:

    class Foo(PolyModel): ...

    class Bar(Foo): ...

    class Baz(Bar): ...

    Foo.class_key() == ['Foo']

    Bar.class_key() == ['Foo', 'Bar']

    Baz.class_key() == ['Foo', 'Bar', 'Baz']

  """

  def __init__(self, name):

    super(_ClassKeyProperty, self).__init__(name=name,

                                            item_type=str,

                                            default=None)

  def __set__(self, *args):

    raise db.DerivedPropertyError(

        'Class-key is a derived property and cannot be set.')

  def __get__(self, model_instance, model_class):

    if model_instance is None:

      return self

    return [cls.__name__ for cls in model_class.__class_hierarchy__]

class PolymorphicClass(db.PropertiedClass):

  """Meta-class for initializing PolymorphicClasses.

  This class extends PropertiedClass to add a few static attributes to

  new polymorphic classes necessary for their correct functioning.

  """

  def __init__(cls, name, bases, dct):

    """Initializes a class that belongs to a polymorphic hierarchy.

    This method configures a few built-in attributes of polymorphic

    models:

      __root_class__: If the new class is a root class, __root_class__ is set to

        itself so that it subclasses can quickly know what the root of

        their hierarchy is and what kind they are stored in.

      __class_hierarchy__: List of classes describing the new model's place

        in the class hierarchy in reverse MRO order.  The first element is

        always the root class while the last element is always the new class.

        MRO documentation: http://www.python.org/download/releases/2.3/mro/

        For example:

          class Foo(PolymorphicClass): ...

          class Bar(Foo): ...

          class Baz(Bar): ...

          Foo.__class_hierarchy__ == [Foo]

          Bar.__class_hierarchy__ == [Foo, Bar]

          Baz.__class_hierarchy__ == [Foo, Bar, Baz]

    Unless the class is a root class or PolyModel itself, it is not

    inserted in to the kind-map like other models.  However, all polymorphic

    classes, are inserted in to the class-map which maps the class-key to

    implementation.  This class key is consulted using the polymorphic instances

    discriminator (the 'class' property of the entity) when loading from the

    datastore.

    """

    if name == 'PolyModel':

      super(PolymorphicClass, cls).__init__(name, bases, dct, map_kind=False)

      return

    elif PolyModel in bases:

      if getattr(cls, '__class_hierarchy__', None):

        raise db.ConfigurationError(('%s cannot derive from PolyModel as '

            '__class_hierarchy__ is already defined.') % cls.__name__)

      cls.__class_hierarchy__ = [cls]

      cls.__root_class__ = cls

      super(PolymorphicClass, cls).__init__(name, bases, dct)

    else:

      super(PolymorphicClass, cls).__init__(name, bases, dct, map_kind=False)

      cls.__class_hierarchy__ = [c for c in reversed(cls.mro())

          if issubclass(c, PolyModel) and c != PolyModel]

      if cls.__class_hierarchy__[0] != cls.__root_class__:

        raise db.ConfigurationError(

            '%s cannot be derived from both root classes %s and %s' %

            (cls.__name__,

            cls.__class_hierarchy__[0].__name__,

            cls.__root_class__.__name__))

    _class_map[cls.class_key()] = cls

class PolyModel(db.Model):

  """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'

  """

  __metaclass__ = PolymorphicClass

  _class = _ClassKeyProperty(name=_CLASS_KEY_PROPERTY)

  def __new__(cls, *args, **kwds):

    """Prevents direct instantiation of PolyModel."""

    if cls is PolyModel:

      raise NotImplementedError()

    return super(PolyModel, cls).__new__(cls, *args, **kwds)

  @classmethod

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

    """

    if cls is cls.__root_class__:

      return super(PolyModel, cls).kind()

    else:

      return cls.__root_class__.kind()

  @classmethod

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

    """

    if not hasattr(cls, '__class_hierarchy__'):

      raise NotImplementedError(

          'Cannot determine class key without class hierarchy')

    return tuple(cls.class_name() for cls in cls.__class_hierarchy__)

  @classmethod

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

    """

    return cls.__name__

  @classmethod

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

    """

    if (_CLASS_KEY_PROPERTY in entity and

        tuple(entity[_CLASS_KEY_PROPERTY]) != cls.class_key()):

      key = tuple(entity[_CLASS_KEY_PROPERTY])

      try:

        poly_class = _class_map[key]

      except KeyError:

        raise db.KindError('No implementation for class \'%s\'' % key)

      return poly_class.from_entity(entity)

    return super(PolyModel, cls).from_entity(entity)

  @classmethod

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

    """

    query = super(PolyModel, cls).all(**kwds)

    if cls != cls.__root_class__:

      query.filter(_CLASS_KEY_PROPERTY + ' =', cls.class_name())

    return query

  @classmethod

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

    """

    if cls == cls.__root_class__:

      return super(PolyModel, cls).gql(query_string, *args, **kwds)

    else:

      from google.appengine.ext import gql

      query = db.GqlQuery('SELECT * FROM %s %s' % (cls.kind(), query_string))

      query_filter = [('nop',

                       [gql.Literal(cls.class_name())])]

      query._proto_query.filters()[('class', '=')] = query_filter

      query.bind(*args, **kwds)

      return query