philo/models/base.py

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