librarian update
[wolnelektury.git] / src / newtagging / models.py
1 # -*- coding: utf-8 -*-
2 """
3 Models and managers for generic tagging.
4 """
5
6 from django.contrib.contenttypes.fields import GenericForeignKey
7 from django.contrib.contenttypes.models import ContentType
8 from django.db import connection, models
9 from django.utils.translation import ugettext_lazy as _
10 from django.db.models.base import ModelBase
11 from django.core.exceptions import ObjectDoesNotExist
12 from django.dispatch import Signal
13
14 qn = connection.ops.quote_name
15
16 tags_updated = Signal(providing_args=["affected_tags"])
17
18
19 def get_queryset_and_model(queryset_or_model):
20     """
21     Given a ``QuerySet`` or a ``Model``, returns a two-tuple of
22     (queryset, model).
23
24     If a ``Model`` is given, the ``QuerySet`` returned will be created
25     using its default manager.
26     """
27     try:
28         return queryset_or_model, queryset_or_model.model
29     except AttributeError:
30         return queryset_or_model.objects.all(), queryset_or_model
31
32
33 ############
34 # Managers #
35 ############
36 class TagManager(models.Manager):
37     def __init__(self, intermediary_table_model):
38         super(TagManager, self).__init__()
39         self.intermediary_table_model = intermediary_table_model
40         models.signals.pre_delete.connect(self.target_deleted)
41
42     def target_deleted(self, instance, **kwargs):
43         """ clear tag relations before deleting an object """
44         try:
45             int(instance.pk)
46         except ValueError:
47             return
48
49         self.update_tags(instance, [])
50
51     def update_tags(self, obj, tags):
52         """
53         Update tags associated with an object.
54         """
55         content_type = ContentType.objects.get_for_model(obj)
56         current_tags = list(self.filter(items__content_type__pk=content_type.pk,
57                                         items__object_id=obj.pk))
58         updated_tags = self.model.get_tag_list(tags)
59
60         # Remove tags which no longer apply
61         tags_for_removal = [tag for tag in current_tags if tag not in updated_tags]
62         if len(tags_for_removal):
63             self.intermediary_table_model.objects.filter(
64                 content_type__pk=content_type.pk,
65                 object_id=obj.pk,
66                 tag__in=tags_for_removal).delete()
67         # Add new tags
68         tags_to_add = [tag for tag in updated_tags
69                        if tag not in current_tags]
70         for tag in tags_to_add:
71             if tag not in current_tags:
72                 self.intermediary_table_model.objects.create(tag=tag, content_object=obj)
73
74         tags_updated.send(sender=type(obj), instance=obj, affected_tags=tags_to_add + tags_for_removal)
75
76     def remove_tag(self, obj, tag):
77         """
78         Remove tag from an object.
79         """
80         content_type = ContentType.objects.get_for_model(obj)
81         self.intermediary_table_model.objects.filter(
82             content_type__pk=content_type.pk, object_id=obj.pk, tag=tag).delete()
83
84     def get_for_object(self, obj):
85         """
86         Create a queryset matching all tags associated with the given
87         object.
88         """
89         ctype = ContentType.objects.get_for_model(obj)
90         return self.filter(items__content_type__pk=ctype.pk,
91                            items__object_id=obj.pk)
92
93     def usage_for_model(self, model, counts=False, filters=None):
94         """
95         Obtain a list of tags associated with instances of the given
96         Model class.
97
98         If ``counts`` is True, a ``count`` attribute will be added to
99         each tag, indicating how many times it has been used against
100         the Model class in question.
101
102         To limit the tags (and counts, if specified) returned to those
103         used by a subset of the Model's instances, pass a dictionary
104         of field lookups to be applied to the given Model as the
105         ``filters`` argument.
106         """
107         # TODO: Do we really need this filters stuff?
108         if filters is None:
109             filters = {}
110
111         queryset = model.objects.filter()
112         for f in filters.items():
113             queryset.query.add_filter(f)
114         usage = self.usage_for_queryset(queryset, counts)
115         return usage
116
117     def usage_for_queryset(self, queryset, counts=False):
118         """
119         Obtain a list of tags associated with instances of a model
120         contained in the given queryset.
121
122         If ``counts`` is True, a ``count`` attribute will be added to
123         each tag, indicating how many times it has been used against
124         the Model class in question.
125         """
126         usage = self.model.objects.filter(
127             items__content_type=ContentType.objects.get_for_model(queryset.model),
128             items__object_id__in=queryset)
129         if counts:
130             usage = usage.annotate(count=models.Count('id'))
131         else:
132             usage = usage.distinct()
133         return usage
134
135     def related_for_model(self, tags, model, counts=False):
136         """
137         Obtain a list of tags related to a given list of tags - that
138         is, other tags used by items which have all the given tags.
139
140         If ``counts`` is True, a ``count`` attribute will be added to
141         each tag, indicating the number of items which have it in
142         addition to the given list of tags.
143         """
144         objs = self.model.intermediary_table_model.objects.get_by_model(model, tags)
145         qs = self.usage_for_queryset(objs, counts)
146         qs = qs.exclude(pk__in=[tag.pk for tag in tags])
147         return qs
148
149
150 class TaggedItemManager(models.Manager):
151     def __init__(self, tag_model):
152         super(TaggedItemManager, self).__init__()
153         self.tag_model = tag_model
154
155     def get_by_model(self, queryset_or_model, tags):
156         """
157         Create a ``QuerySet`` containing instances of the specified
158         model associated with a given tag or list of tags.
159         """
160         queryset, model = get_queryset_and_model(queryset_or_model)
161         tags = self.tag_model.get_tag_list(tags)
162         if not tags:
163             # No existing tags were given
164             return queryset.none()
165
166         # TODO: presumes reverse generic relation
167         # Multiple joins are WAY faster than having-count, at least on Postgres 9.1.
168         for tag in tags:
169             queryset = queryset.filter(tag_relations__tag=tag)
170         return queryset
171
172     def get_union_by_model(self, queryset_or_model, tags):
173         """
174         Create a ``QuerySet`` containing instances of the specified
175         model associated with *any* of the given list of tags.
176         """
177         queryset, model = get_queryset_and_model(queryset_or_model)
178         tags = self.tag_model.get_tag_list(tags)
179         if not tags:
180             return queryset.none()
181         # TODO: presumes reverse generic relation
182         return queryset.filter(tag_relations__tag__in=tags).distinct()
183
184     def get_related(self, obj, queryset_or_model):
185         """
186         Retrieve a list of instances of the specified model which share
187         tags with the model instance ``obj``, ordered by the number of
188         shared tags in descending order.
189         """
190         queryset, model = get_queryset_and_model(queryset_or_model)
191         # TODO: presumes reverse generic relation.
192         # Do we know it's 'tags'?
193         return queryset.filter(tag_relations__tag__in=obj.tags).annotate(
194             count=models.Count('pk')).order_by('-count').exclude(pk=obj.pk)
195
196
197 ##########
198 # Models #
199 ##########
200 def create_intermediary_table_model(model):
201     """Create an intermediary table model for the specific tag model"""
202     name = model.__name__ + 'Relation'
203
204     class Meta:
205         db_table = '%s_relation' % model._meta.db_table
206         unique_together = (('tag', 'content_type', 'object_id'),)
207         app_label = model._meta.app_label
208
209     def obj_unicode(self):
210         try:
211             return u'%s [%s]' % (self.content_type.get_object_for_this_type(pk=self.object_id), self.tag)
212         except ObjectDoesNotExist:
213             return u'<deleted> [%s]' % self.tag
214
215     # Set up a dictionary to simulate declarations within a class
216     attrs = {
217         '__module__': model.__module__,
218         'Meta': Meta,
219         'tag': models.ForeignKey(model, verbose_name=_('tag'), related_name='items'),
220         'content_type': models.ForeignKey(ContentType, verbose_name=_('content type')),
221         'object_id': models.PositiveIntegerField(_('object id'), db_index=True),
222         'content_object': GenericForeignKey('content_type', 'object_id'),
223         '__unicode__': obj_unicode,
224     }
225
226     return type(name, (models.Model,), attrs)
227
228
229 class TagMeta(ModelBase):
230     """Metaclass for tag models (models inheriting from TagBase)."""
231     def __new__(mcs, name, bases, attrs):
232         model = super(TagMeta, mcs).__new__(mcs, name, bases, attrs)
233         if not model._meta.abstract:
234             # Create an intermediary table and register custom managers for concrete models
235             model.intermediary_table_model = create_intermediary_table_model(model)
236             TagManager(model.intermediary_table_model).contribute_to_class(model, 'objects')
237             TaggedItemManager(model).contribute_to_class(model.intermediary_table_model, 'objects')
238         return model
239
240
241 class TagBase(models.Model):
242     """Abstract class to be inherited by model classes."""
243     __metaclass__ = TagMeta
244
245     class Meta:
246         abstract = True
247
248     @staticmethod
249     def get_tag_list(tag_list):
250         """
251         Utility function for accepting tag input in a flexible manner.
252
253         You should probably override this method in your subclass.
254         """
255         if isinstance(tag_list, TagBase):
256             return [tag_list]
257         else:
258             return tag_list