1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
The API
=======
After you've got your ``TaggableManager`` added to your model you can start
playing around with the API.
.. class:: TaggableManager([verbose_name="Tags", help_text="A comma-separated list of tags.", through=None, blank=False])
:param verbose_name: The verbose_name for this field.
:param help_text: The help_text to be used in forms (including the admin).
:param through: The through model, see :doc:`custom_tagging` for more
information.
:param blank: Controls whether this field is required.
.. method:: add(*tags, through_defaults=None, tag_kwargs=None)
This adds tags to an object. The tags can be either ``Tag`` instances, or
strings::
>>> apple.tags.all()
[]
>>> apple.tags.add("red", "green", "fruit")
Use the ``through_defaults`` argument to specify values for your custom
``through`` model, if needed.
The ``tag_kwargs`` argument allows one to specify parameters for the tags
themselves.
.. method:: remove(*tags)
Removes a tag from an object. No exception is raised if the object
doesn't have that tag.
.. method:: clear()
Removes all tags from an object.
.. method:: set(tags, *, through_defaults=None, clear=False)
If ``clear = True`` removes all the current tags and then adds the
specified tags to the object. Otherwise sets the object's tags to those
specified, removing only the missing tags and adding only the new tags.
Use the ``through_defaults`` argument to specify values for your custom
``through`` model, if needed.
.. method: most_common()
Returns a ``QuerySet`` of all tags, annotated with the number of times
they appear, available as the ``num_times`` attribute on each tag. The
``QuerySet``is ordered by ``num_times``, descending. The ``QuerySet``
is lazily evaluated, and can be sliced efficiently.
:param min_count: Specify a min count to limit the returned queryset
.. method:: similar_objects()
Returns a list (not a lazy ``QuerySet``) of other objects tagged
similarly to this one, ordered with most similar first. Each object in
the list is decorated with a ``similar_tags`` attribute, the number of
tags it shares with this object.
If the model is using generic tagging (the default), this method
searches tagged objects from all classes. If you are querying on a
model with its own tagging through table, only other instances of the
same model will be returned.
.. method:: names()
Convenience method, returning a ``ValuesListQuerySet`` (basically
just an iterable) containing the name of each tag as a string::
>>> apple.tags.names()
["green and juicy", "red"]
.. method:: slugs()
Convenience method, returning a ``ValuesListQuerySet`` (basically
just an iterable) containing the slug of each tag as a string::
>>> apple.tags.slugs()
["green-and-juicy", "red"]
.. hint::
You can subclass ``_TaggableManager`` (note the underscore) to add
methods or functionality. ``TaggableManager`` takes an optional
manager keyword argument for your custom class, like this::
class Food(models.Model):
# ... fields here
tags = TaggableManager(manager=_CustomTaggableManager)
Filtering
~~~~~~~~~
To find all of a model with a specific tags you can filter, using the normal
Django ORM API. For example if you had a ``Food`` model, whose
``TaggableManager`` was named ``tags``, you could find all the delicious fruit
like so::
>>> Food.objects.filter(tags__name__in=["delicious"])
[<Food: apple>, <Food: pear>, <Food: plum>]
If you're filtering on multiple tags, it's very common to get duplicate
results, because of the way relational databases work. Often you'll want to
make use of the ``distinct()`` method on ``QuerySets``::
>>> Food.objects.filter(tags__name__in=["delicious", "red"])
[<Food: apple>, <Food: apple>]
>>> Food.objects.filter(tags__name__in=["delicious", "red"]).distinct()
[<Food: apple>]
You can also filter by the slug on tags. If you're using a custom ``Tag``
model you can use this API to filter on any fields it has.
|
