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