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