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