philo/models/base.py

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