+
−#!/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]