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