<commit_before>The API
=======

After you've got your ``TaggableManager`` added to your model you can start
playing around with the API.


add(*tags)
~~~~~~~~~~

This adds tags to an object. The tags can be either ``Tag`` instances, or
strings::

    >>> apple.tags.all()
    []
    >>> apple.tags.add("red", "green", "fruit")


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)
~~~~~~~~~~

Removes all the current tags and then adds the specified tags to the object.

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.

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 using generic tagging (the default), this method searches all tagged
objects. If querying on a model with its own tagging through table, only other
instances of the same model will be returned.

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, who's ``TaggableManager`` was named ``tags``, you could find all the delicious fruit like so::

    >>> Food.objects.filter(tags__in=["delicious"])
    [<Food: apple>, <Food: pear>, <Food: plum>] <commit_msg>79 char lines<commit_after>The API
=======

After you've got your ``TaggableManager`` added to your model you can start
playing around with the API.


add(*tags)
~~~~~~~~~~

This adds tags to an object. The tags can be either ``Tag`` instances, or
strings::

    >>> apple.tags.all()
    []
    >>> apple.tags.add("red", "green", "fruit")


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)
~~~~~~~~~~

Removes all the current tags and then adds the specified tags to the object.

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.

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 using generic tagging (the default), this method searches all tagged
objects. If querying on a model with its own tagging through table, only other
instances of the same model will be returned.

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, who's
``TaggableManager`` was named ``tags``, you could find all the delicious fruit
like so::

    >>> Food.objects.filter(tags__in=["delicious"])
    [<Food: apple>, <Food: pear>, <Food: plum>] 
{'fraction_non_alphanumeric': 0.13693901035673187, 'fraction_numerical': 0.0005753739930955121, 'mean_word_length': 4.45839874411303, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 27, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3770296', 'n_tokens_mistral': 1016, 'n_tokens_neox': 961, 'n_words': 486}