Added numbering requirements to README.
[wolnelektury.git] / apps / newtagging / models.py
1 """
2 Models and managers for generic tagging.
3 """
4 # Python 2.3 compatibility
5 if not hasattr(__builtins__, 'set'):
6     from sets import Set as set
7
8 from django.contrib.contenttypes import generic
9 from django.contrib.contenttypes.models import ContentType
10 from django.db import connection, models
11 from django.utils.translation import ugettext_lazy as _
12 from django.db.models.base import ModelBase
13
14 qn = connection.ops.quote_name
15
16 try:
17     from django.db.models.query import parse_lookup
18 except ImportError:
19     parse_lookup = None
20
21
22 def get_queryset_and_model(queryset_or_model):
23     """
24     Given a ``QuerySet`` or a ``Model``, returns a two-tuple of
25     (queryset, model).
26
27     If a ``Model`` is given, the ``QuerySet`` returned will be created
28     using its default manager.
29     """
30     try:
31         return queryset_or_model, queryset_or_model.model
32     except AttributeError:
33         return queryset_or_model._default_manager.all(), queryset_or_model
34
35
36 ############
37 # Managers #
38 ############
39 class TagManager(models.Manager):
40     def __init__(self, intermediary_table_model):
41         super(TagManager, self).__init__()
42         self.intermediary_table_model = intermediary_table_model
43     
44     def update_tags(self, obj, tags):
45         """
46         Update tags associated with an object.
47         """
48         content_type = ContentType.objects.get_for_model(obj)
49         current_tags = list(self.filter(items__content_type__pk=content_type.pk,
50                                         items__object_id=obj.pk))
51         updated_tags = self.model.get_tag_list(tags)
52     
53         # Remove tags which no longer apply
54         tags_for_removal = [tag for tag in current_tags \
55                             if tag not in updated_tags]
56         if len(tags_for_removal):
57             self.intermediary_table_model._default_manager.filter(content_type__pk=content_type.pk,
58                                                object_id=obj.pk,
59                                                tag__in=tags_for_removal).delete()
60         # Add new tags
61         for tag in updated_tags:
62             if tag not in current_tags:
63                 self.intermediary_table_model._default_manager.create(tag=tag, content_object=obj)
64     
65     def get_for_object(self, obj):
66         """
67         Create a queryset matching all tags associated with the given
68         object.
69         """
70         ctype = ContentType.objects.get_for_model(obj)
71         return self.filter(items__content_type__pk=ctype.pk,
72                            items__object_id=obj.pk)
73     
74     def _get_usage(self, model, counts=False, min_count=None, extra_joins=None, extra_criteria=None, params=None, extra=None):
75         """
76         Perform the custom SQL query for ``usage_for_model`` and
77         ``usage_for_queryset``.
78         """
79         if min_count is not None: counts = True
80
81         model_table = qn(model._meta.db_table)
82         model_pk = '%s.%s' % (model_table, qn(model._meta.pk.column))
83         tag_columns = self._get_tag_columns()
84         
85         if extra is None: extra = {}
86         extra_where = ''
87         if 'where' in extra:
88             extra_where = 'AND ' + ' AND '.join(extra['where'])
89         
90         query = """
91         SELECT DISTINCT %(tag_columns)s%(count_sql)s
92         FROM
93             %(tag)s
94             INNER JOIN %(tagged_item)s
95                 ON %(tag)s.id = %(tagged_item)s.tag_id
96             INNER JOIN %(model)s
97                 ON %(tagged_item)s.object_id = %(model_pk)s
98             %%s
99         WHERE %(tagged_item)s.content_type_id = %(content_type_id)s
100             %%s
101             %(extra_where)s
102         GROUP BY %(tag)s.id, %(tag)s.name
103         %%s
104         ORDER BY %(tag)s.%(ordering)s ASC""" % {
105             'tag': qn(self.model._meta.db_table),
106             'ordering': ', '.join(qn(field) for field in self.model._meta.ordering),
107             'tag_columns': tag_columns,
108             'count_sql': counts and (', COUNT(%s)' % model_pk) or '',
109             'tagged_item': qn(self.intermediary_table_model._meta.db_table),
110             'model': model_table,
111             'model_pk': model_pk,
112             'extra_where': extra_where,
113             'content_type_id': ContentType.objects.get_for_model(model).pk,
114         }
115
116         min_count_sql = ''
117         if min_count is not None:
118             min_count_sql = 'HAVING COUNT(%s) >= %%s' % model_pk
119             params.append(min_count)
120
121         cursor = connection.cursor()
122         cursor.execute(query % (extra_joins, extra_criteria, min_count_sql), params)
123         tags = []
124         for row in cursor.fetchall():
125             t = self.model(*row[:len(self.model._meta.fields)])
126             if counts:
127                 t.count = row[len(self.model._meta.fields)]
128             tags.append(t)
129         return tags
130
131     def usage_for_model(self, model, counts=False, min_count=None, filters=None, extra=None):
132         """
133         Obtain a list of tags associated with instances of the given
134         Model class.
135
136         If ``counts`` is True, a ``count`` attribute will be added to
137         each tag, indicating how many times it has been used against
138         the Model class in question.
139
140         If ``min_count`` is given, only tags which have a ``count``
141         greater than or equal to ``min_count`` will be returned.
142         Passing a value for ``min_count`` implies ``counts=True``.
143
144         To limit the tags (and counts, if specified) returned to those
145         used by a subset of the Model's instances, pass a dictionary
146         of field lookups to be applied to the given Model as the
147         ``filters`` argument.
148         """
149         if extra is None: extra = {}
150         if filters is None: filters = {}
151
152         if not parse_lookup:
153             # post-queryset-refactor (hand off to usage_for_queryset)
154             queryset = model._default_manager.filter()
155             for f in filters.items():
156                 queryset.query.add_filter(f)
157             usage = self.usage_for_queryset(queryset, counts, min_count, extra)
158         else:
159             # pre-queryset-refactor
160             extra_joins = ''
161             extra_criteria = ''
162             params = []
163             if len(filters) > 0:
164                 joins, where, params = parse_lookup(filters.items(), model._meta)
165                 extra_joins = ' '.join(['%s %s AS %s ON %s' % (join_type, table, alias, condition)
166                                         for (alias, (table, join_type, condition)) in joins.items()])
167                 extra_criteria = 'AND %s' % (' AND '.join(where))
168             usage = self._get_usage(model, counts, min_count, extra_joins, extra_criteria, params, extra)
169
170         return usage
171
172     def usage_for_queryset(self, queryset, counts=False, min_count=None, extra=None):
173         """
174         Obtain a list of tags associated with instances of a model
175         contained in the given queryset.
176
177         If ``counts`` is True, a ``count`` attribute will be added to
178         each tag, indicating how many times it has been used against
179         the Model class in question.
180
181         If ``min_count`` is given, only tags which have a ``count``
182         greater than or equal to ``min_count`` will be returned.
183         Passing a value for ``min_count`` implies ``counts=True``.
184         """
185         if parse_lookup:
186             raise AttributeError("'TagManager.usage_for_queryset' is not compatible with pre-queryset-refactor versions of Django.")
187
188         extra_joins = ' '.join(queryset.query.get_from_clause()[0][1:])
189         where, params = queryset.query.where.as_sql()
190         if where:
191             extra_criteria = 'AND %s' % where
192         else:
193             extra_criteria = ''
194         return self._get_usage(queryset.model, counts, min_count, extra_joins, extra_criteria, params, extra)
195
196     def related_for_model(self, tags, model, counts=False, min_count=None, extra=None):
197         """
198         Obtain a list of tags related to a given list of tags - that
199         is, other tags used by items which have all the given tags.
200
201         If ``counts`` is True, a ``count`` attribute will be added to
202         each tag, indicating the number of items which have it in
203         addition to the given list of tags.
204
205         If ``min_count`` is given, only tags which have a ``count``
206         greater than or equal to ``min_count`` will be returned.
207         Passing a value for ``min_count`` implies ``counts=True``.
208         """
209         if min_count is not None: counts = True
210         tags = self.model.get_tag_list(tags)
211         tag_count = len(tags)
212         tagged_item_table = qn(self.intermediary_table_model._meta.db_table)
213         tag_columns = self._get_tag_columns()
214         
215         if extra is None: extra = {}
216         extra_where = ''
217         if 'where' in extra:
218             extra_where = 'AND ' + ' AND '.join(extra['where'])
219         
220         # Temporary table in this query is a hack to prevent MySQL from executing
221         # inner query as dependant query (which could result in severe performance loss)
222         query = """
223         SELECT %(tag_columns)s%(count_sql)s
224         FROM %(tagged_item)s INNER JOIN %(tag)s ON %(tagged_item)s.tag_id = %(tag)s.id
225         WHERE %(tagged_item)s.content_type_id = %(content_type_id)s
226         AND %(tagged_item)s.object_id IN
227         (
228             SELECT *
229             FROM (
230                 SELECT %(tagged_item)s.object_id
231                 FROM %(tagged_item)s, %(tag)s
232                 WHERE %(tagged_item)s.content_type_id = %(content_type_id)s
233                   AND %(tag)s.id = %(tagged_item)s.tag_id
234                   AND %(tag)s.id IN (%(tag_id_placeholders)s)
235                 GROUP BY %(tagged_item)s.object_id
236                 HAVING COUNT(%(tagged_item)s.object_id) = %(tag_count)s
237             ) AS temporary
238         )
239         AND %(tag)s.id NOT IN (%(tag_id_placeholders)s)
240         %(extra_where)s
241         GROUP BY %(tag_columns)s
242         %(min_count_sql)s
243         ORDER BY %(tag)s.%(ordering)s ASC""" % {
244             'tag': qn(self.model._meta.db_table),
245             'ordering': ', '.join(qn(field) for field in self.model._meta.ordering),
246             'tag_columns': tag_columns,
247             'count_sql': counts and ', COUNT(%s.object_id)' % tagged_item_table or '',
248             'tagged_item': tagged_item_table,
249             'content_type_id': ContentType.objects.get_for_model(model).pk,
250             'tag_id_placeholders': ','.join(['%s'] * tag_count),
251             'extra_where': extra_where,
252             'tag_count': tag_count,
253             'min_count_sql': min_count is not None and ('HAVING COUNT(%s.object_id) >= %%s' % tagged_item_table) or '',
254         }
255
256         params = [tag.pk for tag in tags] * 2
257         if min_count is not None:
258             params.append(min_count)
259
260         cursor = connection.cursor()
261         cursor.execute(query, params)
262         related = []
263         for row in cursor.fetchall():
264             tag = self.model(*row[:len(self.model._meta.fields)])
265             if counts is True:
266                 tag.count = row[len(self.model._meta.fields)]
267             related.append(tag)
268         return related
269
270     def _get_tag_columns(self):
271         tag_table = qn(self.model._meta.db_table)
272         return ', '.join('%s.%s' % (tag_table, qn(field.column)) for field in self.model._meta.fields)
273
274
275 class TaggedItemManager(models.Manager):
276     """
277     FIXME There's currently no way to get the ``GROUP BY`` and ``HAVING``
278           SQL clauses required by many of this manager's methods into
279           Django's ORM.
280
281           For now, we manually execute a query to retrieve the PKs of
282           objects we're interested in, then use the ORM's ``__in``
283           lookup to return a ``QuerySet``.
284
285           Once the queryset-refactor branch lands in trunk, this can be
286           tidied up significantly.
287     """
288     def __init__(self, tag_model):
289         super(TaggedItemManager, self).__init__()
290         self.tag_model = tag_model
291     
292     def get_by_model(self, queryset_or_model, tags):
293         """
294         Create a ``QuerySet`` containing instances of the specified
295         model associated with a given tag or list of tags.
296         """
297         tags = self.tag_model.get_tag_list(tags)
298         tag_count = len(tags)
299         if tag_count == 0:
300             # No existing tags were given
301             queryset, model = get_queryset_and_model(queryset_or_model)
302             return model._default_manager.none()
303         elif tag_count == 1:
304             # Optimisation for single tag - fall through to the simpler
305             # query below.
306             tag = tags[0]
307         else:
308             return self.get_intersection_by_model(queryset_or_model, tags)
309
310         queryset, model = get_queryset_and_model(queryset_or_model)
311         content_type = ContentType.objects.get_for_model(model)
312         opts = self.model._meta
313         tagged_item_table = qn(opts.db_table)
314         return queryset.extra(
315             tables=[opts.db_table],
316             where=[
317                 '%s.content_type_id = %%s' % tagged_item_table,
318                 '%s.tag_id = %%s' % tagged_item_table,
319                 '%s.%s = %s.object_id' % (qn(model._meta.db_table),
320                                           qn(model._meta.pk.column),
321                                           tagged_item_table)
322             ],
323             params=[content_type.pk, tag.pk],
324         )
325
326     def get_intersection_by_model(self, queryset_or_model, tags):
327         """
328         Create a ``QuerySet`` containing instances of the specified
329         model associated with *all* of the given list of tags.
330         """
331         tags = self.tag_model.get_tag_list(tags)
332         tag_count = len(tags)
333         queryset, model = get_queryset_and_model(queryset_or_model)
334
335         if not tag_count:
336             return model._default_manager.none()
337
338         model_table = qn(model._meta.db_table)
339         # This query selects the ids of all objects which have all the
340         # given tags.
341         query = """
342         SELECT %(model_pk)s
343         FROM %(model)s, %(tagged_item)s
344         WHERE %(tagged_item)s.content_type_id = %(content_type_id)s
345           AND %(tagged_item)s.tag_id IN (%(tag_id_placeholders)s)
346           AND %(model_pk)s = %(tagged_item)s.object_id
347         GROUP BY %(model_pk)s
348         HAVING COUNT(%(model_pk)s) = %(tag_count)s""" % {
349             'model_pk': '%s.%s' % (model_table, qn(model._meta.pk.column)),
350             'model': model_table,
351             'tagged_item': qn(self.model._meta.db_table),
352             'content_type_id': ContentType.objects.get_for_model(model).pk,
353             'tag_id_placeholders': ','.join(['%s'] * tag_count),
354             'tag_count': tag_count,
355         }
356
357         cursor = connection.cursor()
358         cursor.execute(query, [tag.pk for tag in tags])
359         object_ids = [row[0] for row in cursor.fetchall()]
360         if len(object_ids) > 0:
361             return queryset.filter(pk__in=object_ids)
362         else:
363             return model._default_manager.none()
364
365     def get_union_by_model(self, queryset_or_model, tags):
366         """
367         Create a ``QuerySet`` containing instances of the specified
368         model associated with *any* of the given list of tags.
369         """
370         tags = self.tag_model.get_tag_list(tags)
371         tag_count = len(tags)
372         queryset, model = get_queryset_and_model(queryset_or_model)
373
374         if not tag_count:
375             return model._default_manager.none()
376
377         model_table = qn(model._meta.db_table)
378         # This query selects the ids of all objects which have any of
379         # the given tags.
380         query = """
381         SELECT %(model_pk)s
382         FROM %(model)s, %(tagged_item)s
383         WHERE %(tagged_item)s.content_type_id = %(content_type_id)s
384           AND %(tagged_item)s.tag_id IN (%(tag_id_placeholders)s)
385           AND %(model_pk)s = %(tagged_item)s.object_id
386         GROUP BY %(model_pk)s""" % {
387             'model_pk': '%s.%s' % (model_table, qn(model._meta.pk.column)),
388             'model': model_table,
389             'tagged_item': qn(self.model._meta.db_table),
390             'content_type_id': ContentType.objects.get_for_model(model).pk,
391             'tag_id_placeholders': ','.join(['%s'] * tag_count),
392         }
393
394         cursor = connection.cursor()
395         cursor.execute(query, [tag.pk for tag in tags])
396         object_ids = [row[0] for row in cursor.fetchall()]
397         if len(object_ids) > 0:
398             return queryset.filter(pk__in=object_ids)
399         else:
400             return model._default_manager.none()
401
402     def get_related(self, obj, queryset_or_model, num=None):
403         """
404         Retrieve a list of instances of the specified model which share
405         tags with the model instance ``obj``, ordered by the number of
406         shared tags in descending order.
407
408         If ``num`` is given, a maximum of ``num`` instances will be
409         returned.
410         """
411         queryset, model = get_queryset_and_model(queryset_or_model)
412         model_table = qn(model._meta.db_table)
413         content_type = ContentType.objects.get_for_model(obj)
414         related_content_type = ContentType.objects.get_for_model(model)
415         query = """
416         SELECT %(model_pk)s, COUNT(related_tagged_item.object_id) AS %(count)s
417         FROM %(model)s, %(tagged_item)s, %(tag)s, %(tagged_item)s related_tagged_item
418         WHERE %(tagged_item)s.object_id = %%s
419           AND %(tagged_item)s.content_type_id = %(content_type_id)s
420           AND %(tag)s.id = %(tagged_item)s.tag_id
421           AND related_tagged_item.content_type_id = %(related_content_type_id)s
422           AND related_tagged_item.tag_id = %(tagged_item)s.tag_id
423           AND %(model_pk)s = related_tagged_item.object_id"""
424         if content_type.pk == related_content_type.pk:
425             # Exclude the given instance itself if determining related
426             # instances for the same model.
427             query += """
428           AND related_tagged_item.object_id != %(tagged_item)s.object_id"""
429         query += """
430         GROUP BY %(model_pk)s
431         ORDER BY %(count)s DESC
432         %(limit_offset)s"""
433         query = query % {
434             'model_pk': '%s.%s' % (model_table, qn(model._meta.pk.column)),
435             'count': qn('count'),
436             'model': model_table,
437             'tagged_item': qn(self.model._meta.db_table),
438             'tag': qn(self.model._meta.get_field('tag').rel.to._meta.db_table),
439             'content_type_id': content_type.pk,
440             'related_content_type_id': related_content_type.pk,
441             'limit_offset': num is not None and connection.ops.limit_offset_sql(num) or '',
442         }
443
444         cursor = connection.cursor()
445         cursor.execute(query, [obj.pk])
446         object_ids = [row[0] for row in cursor.fetchall()]
447         if len(object_ids) > 0:
448             # Use in_bulk here instead of an id__in lookup, because id__in would
449             # clobber the ordering.
450             object_dict = queryset.in_bulk(object_ids)
451             return [object_dict[object_id] for object_id in object_ids \
452                     if object_id in object_dict]
453         else:
454             return []
455
456
457 ##########
458 # Models #
459 ##########
460 def create_intermediary_table_model(model):
461     """Create an intermediary table model for the specific tag model"""
462     name = model.__name__ + 'Relation'
463      
464     class Meta:
465         db_table = '%s_relation' % model._meta.db_table
466         unique_together = (('tag', 'content_type', 'object_id'),)
467
468     def obj_unicode(self):
469         return u'%s [%s]' % (self.content_type.get_object_for_this_type(pk=self.object_id), self.tag)
470         
471     # Set up a dictionary to simulate declarations within a class    
472     attrs = {
473         '__module__': model.__module__,
474         'Meta': Meta,
475         'tag': models.ForeignKey(model, verbose_name=_('tag'), related_name='items'),
476         'content_type': models.ForeignKey(ContentType, verbose_name=_('content type')),
477         'object_id': models.PositiveIntegerField(_('object id'), db_index=True),
478         'content_object': generic.GenericForeignKey('content_type', 'object_id'),
479         '__unicode__': obj_unicode,
480     }
481
482     return type(name, (models.Model,), attrs)
483
484
485 class TagMeta(ModelBase):
486     "Metaclass for tag models (models inheriting from TagBase)."
487     def __new__(cls, name, bases, attrs):
488         model = super(TagMeta, cls).__new__(cls, name, bases, attrs)
489         if not model._meta.abstract:
490             # Create an intermediary table and register custom managers for concrete models
491             model.intermediary_table_model = create_intermediary_table_model(model)
492             TagManager(model.intermediary_table_model).contribute_to_class(model, 'objects')
493             TaggedItemManager(model).contribute_to_class(model.intermediary_table_model, 'objects')
494         return model
495
496
497 class TagBase(models.Model):
498     """Abstract class to be inherited by model classes."""
499     __metaclass__ = TagMeta
500     
501     class Meta:
502         abstract = True
503     
504     @staticmethod
505     def get_tag_list(tag_list):
506         """
507         Utility function for accepting tag input in a flexible manner.
508         
509         You should probably override this method in your subclass.
510         """
511         if isinstance(tag_list, TagBase):
512             return [tag_list]
513         else:
514             return tag_list
515