#!/usr/bin/python2.5
#
# Copyright 2007 Ken Tidwell
#
# 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.
# 
"""Simple property for storing ordered lists of Model objects.

It should be noted that larger lists are going to be VERY inefficient
to load (one get per object).

Currently I have no idea where that upper bound might lie, though.
 
A quick usage example:
        class Bit(db.Model):
                name = db.StringProperty(required=True)
        class Holder(db.Model):
                bits = reflistprop.ReferenceListProperty(Bit, default=None)
        b1 = Bit(name="first")
        b1.put() # need to put it so that it is a valid reference object
        h1 = holder()
        h1.bits.append(b1)
        h1.put()
         
These also work:
        h1.bits = [b1]
         
This throws a db.BadValueError because a string is not an instance of
Bit: 
        h1.bits = ["nasty evil string"]
         
This is not good but gets no complaint at assignment time (same behaviour
as ListProperty) but we will throw a db.BadValueError if you try to put it
into the datastore. (Maybe ListProperty wants to do the same? Or should I be
waiting for the datastore internal entity construction to notice the problem
and throw?):
        h1.bits.append("nasty evil string")

Yes, of course you can query them. The important bit to understand is
that the list is stored as a list of keys in the datastore. So you use
the key of the entity in question in your query. (Seems like it would be
nice if the property could get involved and do that coercion for you but
I don't think it can right now...).
 
Here's a little example:
        class Thang(db.Model):
            name = db.StringProperty(required=True)
        class Holder(db.Model):
            thangs = langutils.ReferenceListProperty(Thang, default=None)
        holder1 = Holder()
        holder1.put()
        foo = Thang(name="foo")
        foo.put()
        holder1.thangs.append(foo)
        holder1.put()
        hq = db.GqlQuery("SELECT * FROM Holder where thangs = :1", foo.key())
        holders = hq.fetch(10)
        print "Holders =", holders
        
Obtained from:
  http://groups.google.com/group/google-appengine/msg/d203cc1b93ee22d7
"""


from google.appengine.ext import db

 
class ReferenceListProperty(db.Property):
  """A property that stores a list of models.
  
  This is a parameterized property; the parameter must be a valid
  Model type, and all items must conform to this type.
  """
  def __init__(self, item_type, verbose_name=None, default=None, **kwds):
    """Construct ReferenceListProperty.

    Args:
      item_type: Type for the list items; must be a subclass of Model.
      verbose_name: Optional verbose name.
      default: Optional default value; if omitted, an empty list is used.
      **kwds: Optional additional keyword arguments, passed to base class.
    """
    if not issubclass(item_type, db.Model):
      raise TypeError('Item type should be a subclass of Model')
    if default is None:
      default = []
    self.item_type = item_type
    super(ReferenceListProperty, self).__init__(verbose_name,
                                                default=default,
                                                **kwds)
  
  def validate(self, value):
    """Validate list.

    Note that validation here is just as broken as for ListProperty.
    The values in the list are only validated if the entire list is
    swapped out. If the list is directly modified, there is no attempt
    to validate the new items.

    Returns:
      A valid value.

    Raises:
      BadValueError if property is not a list whose items are
      instances of the item_type given to the constructor.
    """
    value = super(ReferenceListProperty, self).validate(value)
    if value is not None:
      if not isinstance(value, list):
        raise db.BadValueError('Property %s must be a list' %
                               self.name)
      for item in value:
        if not isinstance(item, self.item_type):
          raise db.BadValueError(
            'Items in the %s list must all be %s instances' %
            (self.name, self.item_type.__name__))
    return value

  def empty(self, value):
    """Is list property empty.

    [] is not an empty value.
 
    Returns:
      True if value is None, else False.
    """ 
    return value is None

  data_type = list
 
  def default_value(self):
    """Default value for list.
 
    Because the property supplied to 'default' is a static value,
    that value must be shallow copied to prevent all fields with
    default values from sharing the same instance.
 
    Returns:
      Copy of the default value.
    """ 
    return list(super(ReferenceListProperty, self).default_value())
 
  def get_value_for_datastore(self, model_instance):
    """A list of key values is stored.

    Prior to storage, we validate the items in the list.
    This check seems to be missing from ListProperty.

    Args:
      model_instance: Instance to fetch datastore value from.
 
    Returns:
      A list of the keys for all Models in the value list.
    """
    value = self.__get__(model_instance, model_instance.__class__)
    self.validate(value)
    if value is None:
      return None
    else:
      return [v.key() for v in value]
 
  def make_value_from_datastore(self, value):
    """Recreates the list of Models from the list of keys.
 
    Args:
      value: value retrieved from the datastore entity.

    Returns:
      None or a list of Models.
    """ 
    if value is None:
      return None
    else:
      return [db.get(v) for v in value]