philo/models/base.py

   1 from django import forms
   2 from django.db import models
   3 from django.contrib.contenttypes.models import ContentType
   4 from django.contrib.contenttypes import generic
   5 from django.core.exceptions import ObjectDoesNotExist
   6 from django.core.validators import RegexValidator
   7 from django.utils import simplejson as json
   8 from django.utils.encoding import force_unicode
   9 from philo.exceptions import AncestorDoesNotExist
  10 from philo.models.fields import JSONField
  11 from philo.utils import ContentTypeRegistryLimiter, ContentTypeSubclassLimiter
  12 from philo.signals import entity_class_prepared
  13 from philo.validators import json_validator
  14 from UserDict import DictMixin
  15 from mptt.models import MPTTModel, MPTTModelBase, MPTTOptions
  16
  17
  18 class Tag(models.Model):
  19         name = models.CharField(max_length=255)
  20         slug = models.SlugField(max_length=255, unique=True)
  21
  22         def __unicode__(self):
  23                 return self.name
  24
  25         class Meta:
  26                 app_label = 'philo'
  27                 ordering = ('name',)
  28
  29
  30 class Titled(models.Model):
  31         title = models.CharField(max_length=255)
  32         slug = models.SlugField(max_length=255)
  33
  34         def __unicode__(self):
  35                 return self.title
  36
  37         class Meta:
  38                 abstract = True
  39
  40
  41 value_content_type_limiter = ContentTypeRegistryLimiter()
  42 """
  43 An instance of :class:`ContentTypeRegistryLimiter` which is used to track the content types which can be related to by ForeignKeyValues and ManyToManyValues.
  44
  45 """
  46
  47
  48 def register_value_model(model):
  49         """
  50         Registers a model as a valid content type for a :class:`ForeignKeyValue` or :class:`ManyToManyValue` through the :data:`value_content_type_limiter`.
  51
  52         """
  53         value_content_type_limiter.register_class(model)
  54
  55
  56 register_value_model(Tag)
  57
  58
  59 def unregister_value_model(model):
  60         """
  61         Registers a model as a valid content type for a :class:`ForeignKeyValue` or :class:`ManyToManyValue` through the :data:`value_content_type_limiter`.
  62
  63         """
  64         value_content_type_limiter.unregister_class(model)
  65
  66
  67 class AttributeValue(models.Model):
  68         """
  69         This is an abstract base class for models that can be used as values for :class:`Attribute`\ s.
  70
  71         AttributeValue subclasses are expected to supply access to a clean version of their value through an attribute called "value".
  72
  73         """
  74         attribute_set = generic.GenericRelation('Attribute', content_type_field='value_content_type', object_id_field='value_object_id')
  75         """
  76         :class:`GenericRelation` to :class:`Attribute`
  77
  78         """
  79         def set_value(self, value):
  80                 """Given a ``value``, sets the appropriate fields so that it can be correctly stored in the database."""
  81                 raise NotImplementedError
  82
  83         def value_formfields(self, **kwargs):
  84                 """
  85                 Returns any formfields that would be used to construct an instance of this value.
  86
  87                 :returns: A dictionary mapping field names to formfields.
  88
  89                 """
  90                 raise NotImplementedError
  91
  92         def construct_instance(self, **kwargs):
  93                 """Applies cleaned data from the formfields generated by valid_formfields to oneself."""
  94                 raise NotImplementedError
  95
  96         def __unicode__(self):
  97                 return unicode(self.value)
  98
  99         class Meta:
 100                 abstract = True
 101
 102
 103 attribute_value_limiter = ContentTypeSubclassLimiter(AttributeValue)
 104 """
 105 An instance of :class:`ContentTypeSubclassLimiter` which is used to track the content types which are considered valid value models for an :class:`Attribute`.
 106
 107 """
 108
 109
 110 class JSONValue(AttributeValue):
 111         """Stores a python object as a json string."""
 112         value = JSONField(verbose_name='Value (JSON)', help_text='This value must be valid JSON.', default='null', db_index=True)
 113
 114         def __unicode__(self):
 115                 return force_unicode(self.value)
 116
 117         def value_formfields(self):
 118                 kwargs = {'initial': self.value_json}
 119                 field = self._meta.get_field('value')
 120                 return {field.name: field.formfield(**kwargs)}
 121
 122         def construct_instance(self, **kwargs):
 123                 field_name = self._meta.get_field('value').name
 124                 self.set_value(kwargs.pop(field_name, None))
 125
 126         def set_value(self, value):
 127                 self.value = value
 128
 129         class Meta:
 130                 app_label = 'philo'
 131
 132
 133 class ForeignKeyValue(AttributeValue):
 134         """Stores a generic relationship to an instance of any value content type (as defined by the :data:`value_content_type_limiter`)."""
 135         content_type = models.ForeignKey(ContentType, limit_choices_to=value_content_type_limiter, verbose_name='Value type', null=True, blank=True)
 136         object_id = models.PositiveIntegerField(verbose_name='Value ID', null=True, blank=True, db_index=True)
 137         value = generic.GenericForeignKey()
 138
 139         def value_formfields(self):
 140                 field = self._meta.get_field('content_type')
 141                 fields = {field.name: field.formfield(initial=getattr(self.content_type, 'pk', None))}
 142
 143                 if self.content_type:
 144                         kwargs = {
 145                                 'initial': self.object_id,
 146                                 'required': False,
 147                                 'queryset': self.content_type.model_class()._default_manager.all()
 148                         }
 149                         fields['value'] = forms.ModelChoiceField(**kwargs)
 150                 return fields
 151
 152         def construct_instance(self, **kwargs):
 153                 field_name = self._meta.get_field('content_type').name
 154                 ct = kwargs.pop(field_name, None)
 155                 if ct is None or ct != self.content_type:
 156                         self.object_id = None
 157                         self.content_type = ct
 158                 else:
 159                         value = kwargs.pop('value', None)
 160                         self.set_value(value)
 161                         if value is None:
 162                                 self.content_type = ct
 163
 164         def set_value(self, value):
 165                 self.value = value
 166
 167         class Meta:
 168                 app_label = 'philo'
 169
 170
 171 class ManyToManyValue(AttributeValue):
 172         """Stores a generic relationship to many instances of any value content type (as defined by the :data:`value_content_type_limiter`)."""
 173         content_type = models.ForeignKey(ContentType, limit_choices_to=value_content_type_limiter, verbose_name='Value type', null=True, blank=True)
 174         values = models.ManyToManyField(ForeignKeyValue, blank=True, null=True)
 175
 176         def get_object_ids(self):
 177                 return self.values.values_list('object_id', flat=True)
 178         object_ids = property(get_object_ids)
 179
 180         def set_value(self, value):
 181                 # Value must be a queryset. Watch out for ModelMultipleChoiceField;
 182                 # it returns its value as a list if empty.
 183
 184                 self.content_type = ContentType.objects.get_for_model(value.model)
 185
 186                 # Before we can fiddle with the many-to-many to foreignkeyvalues, we need
 187                 # a pk.
 188                 if self.pk is None:
 189                         self.save()
 190
 191                 object_ids = value.values_list('id', flat=True)
 192
 193                 # These lines shouldn't be necessary; however, if object_ids is an EmptyQuerySet,
 194                 # the code (specifically the object_id__in query) won't work without them. Unclear why...
 195                 # TODO: is this still the case?
 196                 if not object_ids:
 197                         self.values.all().delete()
 198                 else:
 199                         self.values.exclude(object_id__in=object_ids, content_type=self.content_type).delete()
 200
 201                         current_ids = self.object_ids
 202
 203                         for object_id in object_ids:
 204                                 if object_id in current_ids:
 205                                         continue
 206                                 self.values.create(content_type=self.content_type, object_id=object_id)
 207
 208         def get_value(self):
 209                 if self.content_type is None:
 210                         return None
 211
 212                 # HACK to be safely explicit until http://code.djangoproject.com/ticket/15145 is resolved
 213                 object_ids = self.object_ids
 214                 manager = self.content_type.model_class()._default_manager
 215                 if not object_ids:
 216                         return manager.none()
 217                 return manager.filter(id__in=self.object_ids)
 218
 219         value = property(get_value, set_value)
 220
 221         def value_formfields(self):
 222                 field = self._meta.get_field('content_type')
 223                 fields = {field.name: field.formfield(initial=getattr(self.content_type, 'pk', None))}
 224
 225                 if self.content_type:
 226                         kwargs = {
 227                                 'initial': self.object_ids,
 228                                 'required': False,
 229                                 'queryset': self.content_type.model_class()._default_manager.all()
 230                         }
 231                         fields['value'] = forms.ModelMultipleChoiceField(**kwargs)
 232                 return fields
 233
 234         def construct_instance(self, **kwargs):
 235                 field_name = self._meta.get_field('content_type').name
 236                 ct = kwargs.pop(field_name, None)
 237                 if ct is None or ct != self.content_type:
 238                         self.values.clear()
 239                         self.content_type = ct
 240                 else:
 241                         value = kwargs.get('value', None)
 242                         if not value:
 243                                 value = self.content_type.model_class()._default_manager.none()
 244                         self.set_value(value)
 245         construct_instance.alters_data = True
 246
 247         class Meta:
 248                 app_label = 'philo'
 249
 250
 251 class Attribute(models.Model):
 252         """
 253         Represents an arbitrary key/value pair on an arbitrary :class:`Model` where the key consists of word characters and the value is a subclass of :class:`AttributeValue`.
 254
 255         """
 256         entity_content_type = models.ForeignKey(ContentType, related_name='attribute_entity_set', verbose_name='Entity type')
 257         entity_object_id = models.PositiveIntegerField(verbose_name='Entity ID', db_index=True)
 258         entity = generic.GenericForeignKey('entity_content_type', 'entity_object_id')
 259         """
 260         :class:`GenericForeignKey` to anything (generally an instance of an Entity subclass).
 261
 262         """
 263
 264         value_content_type = models.ForeignKey(ContentType, related_name='attribute_value_set', limit_choices_to=attribute_value_limiter, verbose_name='Value type', null=True, blank=True)
 265         value_object_id = models.PositiveIntegerField(verbose_name='Value ID', null=True, blank=True, db_index=True)
 266         value = generic.GenericForeignKey('value_content_type', 'value_object_id')
 267         """
 268         :class:`GenericForeignKey` to an instance of a subclass of :class:`AttributeValue` as determined by the :data:`attribute_value_limiter`.
 269
 270         """
 271
 272         key = models.CharField(max_length=255, validators=[RegexValidator("\w+")], help_text="Must contain one or more alphanumeric characters or underscores.", db_index=True)
 273         """
 274         :class:`CharField` containing a key (up to 255 characters) consisting of alphanumeric characters and underscores.
 275
 276         """
 277
 278         def __unicode__(self):
 279                 return u'"%s": %s' % (self.key, self.value)
 280
 281         class Meta:
 282                 app_label = 'philo'
 283                 unique_together = (('key', 'entity_content_type', 'entity_object_id'), ('value_content_type', 'value_object_id'))
 284
 285
 286 class QuerySetMapper(object, DictMixin):
 287         def __init__(self, queryset, passthrough=None):
 288                 self.queryset = queryset
 289                 self.passthrough = passthrough
 290
 291         def __getitem__(self, key):
 292                 try:
 293                         value = self.queryset.get(key__exact=key).value
 294                 except ObjectDoesNotExist:
 295                         if self.passthrough is not None:
 296                                 return self.passthrough.__getitem__(key)
 297                         raise KeyError
 298                 else:
 299                         if value is not None:
 300                                 return value.value
 301                         return value
 302
 303         def keys(self):
 304                 keys = set(self.queryset.values_list('key', flat=True).distinct())
 305                 if self.passthrough is not None:
 306                         keys |= set(self.passthrough.keys())
 307                 return list(keys)
 308
 309
 310 class EntityOptions(object):
 311         def __init__(self, options):
 312                 if options is not None:
 313                         for key, value in options.__dict__.items():
 314                                 setattr(self, key, value)
 315                 if not hasattr(self, 'proxy_fields'):
 316                         self.proxy_fields = []
 317
 318         def add_proxy_field(self, proxy_field):
 319                 self.proxy_fields.append(proxy_field)
 320
 321
 322 class EntityBase(models.base.ModelBase):
 323         def __new__(cls, name, bases, attrs):
 324                 entity_meta = attrs.pop('EntityMeta', None)
 325                 new = super(EntityBase, cls).__new__(cls, name, bases, attrs)
 326                 new.add_to_class('_entity_meta', EntityOptions(entity_meta))
 327                 entity_class_prepared.send(sender=new)
 328                 return new
 329
 330
 331 class Entity(models.Model):
 332         """An abstract class that simplifies access to related attributes. Most models provided by Philo subclass Entity."""
 333         __metaclass__ = EntityBase
 334
 335         attribute_set = generic.GenericRelation(Attribute, content_type_field='entity_content_type', object_id_field='entity_object_id')
 336
 337         @property
 338         def attributes(self):
 339                 """
 340                 Property that returns a dictionary-like object which can be used to retrieve related :class:`Attribute`\ s' values directly.
 341
 342                 Example::
 343
 344                         >>> attr = entity.attribute_set.get(key='spam')
 345                         >>> attr.value.value
 346                         u'eggs'
 347                         >>> entity.attributes['spam']
 348                         u'eggs'
 349                 """
 350                 return QuerySetMapper(self.attribute_set.all())
 351
 352         class Meta:
 353                 abstract = True
 354
 355
 356 class TreeManager(models.Manager):
 357         use_for_related_fields = True
 358
 359         def get_with_path(self, path, root=None, absolute_result=True, pathsep='/', field='slug'):
 360                 """
 361                 If ``absolute_result`` is ``True``, returns the object at ``path`` (starting at ``root``) or raises a :exception:`DoesNotExist` exception. Otherwise, returns a tuple containing the deepest object found along ``path`` (or ``root`` if no deeper object is found) and the remainder of the path after that object as a string (or None if there is no remaining path).
 362
 363                 .. note:: If you are looking for something with an exact path, it is faster to use absolute_result=True, unless the path depth is over ~40, in which case the high cost of the absolute query may make a binary search (i.e. non-absolute) faster.
 364
 365                 .. note:: SQLite allows max of 64 tables in one join. That means the binary search will only work on paths with a max depth of 127 and the absolute fetch will only work to a max depth of (surprise!) 63. Larger depths could be handled, but since the common use case will not have a tree structure that deep, they are not.
 366
 367                 :param path: The path of the object
 368                 :param root: The object which will be considered the root of the search
 369                 :param absolute_result: Whether to return an absolute result or do a binary search
 370                 :param pathsep: The path separator used in ``path``
 371                 :param field: The field on the model which should be queried for ``path`` segment matching.
 372                 :returns: An instance if absolute_result is True or (instance, remaining_path) otherwise.
 373
 374                 """
 375                 segments = path.split(pathsep)
 376
 377                 # Clean out blank segments. Handles multiple consecutive pathseps.
 378                 while True:
 379                         try:
 380                                 segments.remove('')
 381                         except ValueError:
 382                                 break
 383
 384                 # Special-case a lack of segments. No queries necessary.
 385                 if not segments:
 386                         if root is not None:
 387                                 if absolute_result:
 388                                         return root
 389                                 return root, None
 390                         else:
 391                                 raise self.model.DoesNotExist('%s matching query does not exist.' % self.model._meta.object_name)
 392
 393                 def make_query_kwargs(segments, root):
 394                         kwargs = {}
 395                         prefix = ""
 396                         revsegs = list(segments)
 397                         revsegs.reverse()
 398
 399                         for segment in revsegs:
 400                                 kwargs["%s%s__exact" % (prefix, field)] = segment
 401                                 prefix += "parent__"
 402
 403                         if prefix:
 404                                 kwargs[prefix[:-2]] = root
 405
 406                         return kwargs
 407
 408                 def find_obj(segments, depth, deepest_found=None):
 409                         if deepest_found is None:
 410                                 deepest_level = 0
 411                         elif root is None:
 412                                 deepest_level = deepest_found.get_level() + 1
 413                         else:
 414                                 deepest_level = deepest_found.get_level() - root.get_level()
 415                         try:
 416                                 obj = self.get(**make_query_kwargs(segments[deepest_level:depth], deepest_found or root))
 417                         except self.model.DoesNotExist:
 418                                 if not deepest_level and depth > 1:
 419                                         # make sure there's a root node...
 420                                         depth = 1
 421                                 else:
 422                                         # Try finding one with half the path since the deepest find.
 423                                         depth = (deepest_level + depth)/2
 424
 425                                 if deepest_level == depth:
 426                                         # This should happen if nothing is found with any part of the given path.
 427                                         if root is not None and deepest_found is None:
 428                                                 return root, pathsep.join(segments)
 429                                         raise
 430
 431                                 return find_obj(segments, depth, deepest_found)
 432                         else:
 433                                 # Yay! Found one!
 434                                 if root is None:
 435                                         deepest_level = obj.get_level() + 1
 436                                 else:
 437                                         deepest_level = obj.get_level() - root.get_level()
 438
 439                                 # Could there be a deeper one?
 440                                 if obj.is_leaf_node():
 441                                         return obj, pathsep.join(segments[deepest_level:]) or None
 442
 443                                 depth += (len(segments) - depth)/2 or len(segments) - depth
 444
 445                                 if depth > deepest_level + obj.get_descendant_count():
 446                                         depth = deepest_level + obj.get_descendant_count()
 447
 448                                 if deepest_level == depth:
 449                                         return obj, pathsep.join(segments[deepest_level:]) or None
 450
 451                                 try:
 452                                         return find_obj(segments, depth, obj)
 453                                 except self.model.DoesNotExist:
 454                                         # Then this was the deepest.
 455                                         return obj, pathsep.join(segments[deepest_level:])
 456
 457                 if absolute_result:
 458                         return self.get(**make_query_kwargs(segments, root))
 459
 460                 # Try a modified binary search algorithm. Feed the root in so that query complexity
 461                 # can be reduced. It might be possible to weight the search towards the beginning
 462                 # of the path, since short paths are more likely, but how far forward? It would
 463                 # need to shift depending on len(segments) - perhaps logarithmically?
 464                 return find_obj(segments, len(segments)/2 or len(segments))
 465
 466
 467 class TreeModel(MPTTModel):
 468         objects = TreeManager()
 469         parent = models.ForeignKey('self', related_name='children', null=True, blank=True)
 470         slug = models.SlugField(max_length=255)
 471
 472         def get_path(self, root=None, pathsep='/', field='slug'):
 473                 """
 474                 :param root: Only return the path since this object.
 475                 :param pathsep: The path separator to use when constructing an instance's path
 476                 :param field: The field to pull path information from for each ancestor.
 477                 :returns: A string representation of an object's path.
 478
 479                 """
 480                 if root == self:
 481                         return ''
 482
 483                 if root is not None and not self.is_descendant_of(root):
 484                         raise AncestorDoesNotExist(root)
 485
 486                 qs = self.get_ancestors(include_self=True)
 487
 488                 if root is not None:
 489                         qs = qs.filter(**{'%s__gt' % self._mptt_meta.level_attr: root.get_level()})
 490
 491                 return pathsep.join([getattr(parent, field, '?') for parent in qs])
 492         path = property(get_path)
 493
 494         def __unicode__(self):
 495                 return self.path
 496
 497         class Meta:
 498                 unique_together = (('parent', 'slug'),)
 499                 abstract = True
 500
 501
 502 class TreeEntityBase(MPTTModelBase, EntityBase):
 503         def __new__(meta, name, bases, attrs):
 504                 attrs['_mptt_meta'] = MPTTOptions(attrs.pop('MPTTMeta', None))
 505                 cls = EntityBase.__new__(meta, name, bases, attrs)
 506
 507                 return meta.register(cls)
 508
 509
 510 class TreeEntity(Entity, TreeModel):
 511         """
 512         An abstract subclass of Entity which represents a tree relationship.
 513
 514         """
 515         __metaclass__ = TreeEntityBase
 516
 517         @property
 518         def attributes(self):
 519                 """
 520                 Property that returns a dictionary-like object which can be used to retrieve related :class:`Attribute`\ s' values directly. If an attribute with a given key is not related to the :class:`Entity`, then the object will check the parent's attributes.
 521
 522                 Example::
 523
 524                         >>> attr = entity.attribute_set.get(key='spam')
 525                         DoesNotExist: Attribute matching query does not exist.
 526                         >>> attr = entity.parent.attribute_set.get(key='spam')
 527                         >>> attr.value.value
 528                         u'eggs'
 529                         >>> entity.attributes['spam']
 530                         u'eggs'
 531
 532                 """
 533                 if self.parent:
 534                         return QuerySetMapper(self.attribute_set.all(), passthrough=self.parent.attributes)
 535                 return super(TreeEntity, self).attributes
 536
 537         class Meta:
 538                 abstract = True