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])¶
- Parameters:
verbose_name – The verbose_name for this field.
help_text – The help_text to be used in forms (including the admin).
through – The through model, see Customizing taggit for more information.
blank – Controls whether this field is required.
- 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 customthrough
model, if needed.The
tag_kwargs
argument allows one to specify parameters for the tags themselves.
- remove(*tags)¶
Removes a tag from an object. No exception is raised if the object doesn’t have that tag.
- clear()¶
Removes all tags from an object.
- 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 customthrough
model, if needed.
- 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 asimilar_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.
- 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"]
- 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.