==============

Django Tagging

==============

A generic tagging application for `Django`_ projects, which allows

association of a number of tags with any Django model instance and makes

retrieval of tags simple.

.. _`Django`: http://www.djangoproject.com

.. contents::

   :depth: 3

Installation

============

Installing an official release

------------------------------

Official releases are made available from

http://code.google.com/p/django-tagging/

Source distribution

~~~~~~~~~~~~~~~~~~~

Download the .zip distribution file and unpack it. Inside is a script

named ``setup.py``. Enter this command::

   python setup.py install

...and the package will install automatically.

Windows installer

~~~~~~~~~~~~~~~~~

A Windows installer is also made available - download the .exe

distribution file and launch it to install the application.

An uninstaller will also be created, accessible through Add/Remove

Programs in your Control Panel.

Installing the development version

----------------------------------

Alternatively, if you'd like to update Django Tagging occasionally to pick

up the latest bug fixes and enhancements before they make it into an

official release, perform a `Subversion`_ checkout instead. The following

command will check the application's development branch out to an

``tagging-trunk`` directory::

   svn checkout http://django-tagging.googlecode.com/svn/trunk/ tagging-trunk

Add the resulting folder to your `PYTHONPATH`_ or symlink (`junction`_,

if you're on Windows) the ``tagging`` directory inside it into a

directory which is on your PYTHONPATH, such as your Python

installation's ``site-packages`` directory.

You can verify that the application is available on your PYTHONPATH by

opening a Python interpreter and entering the following commands::

   >>> import tagging

   >>> tagging.VERSION

   (0, 3, 'pre')

When you want to update your copy of the Django Tagging source code, run

the command ``svn update`` from within the ``tagging-trunk`` directory.

.. caution::

   The development version may contain bugs which are not present in the

   release version and introduce backwards-incompatible changes.

   If you're tracking trunk, keep an eye on the `CHANGELOG`_ and the

   `backwards-incompatible changes wiki page`_ before you update your

   copy of the source code.

.. _`Subversion`: http://subversion.tigris.org

.. _`PYTHONPATH`: http://www.python.org/doc/2.5.2/tut/node8.html#SECTION008120000000000000000

.. _`junction`: http://www.microsoft.com/technet/sysinternals/FileAndDisk/Junction.mspx

.. _`CHANGELOG`: http://django-tagging.googlecode.com/svn/trunk/CHANGELOG.txt

.. _`backwards-incompatible changes wiki page`: http://code.google.com/p/django-tagging/wiki/BackwardsIncompatibleChanges

Using Django Tagging in your applications

-----------------------------------------

Once you've installed Django Tagging and want to use it in your Django

applications, do the following:

   1. Put ``'tagging'`` in your ``INSTALLED_APPS`` setting.

   2. Run the command ``manage.py syncdb``.

The ``syncdb`` command creates the necessary database tables and

creates permission objects for all installed apps that need them.

That's it!

Settings

========

Some of the application's behaviour can be configured by adding the

appropriate settings to your project's settings file.

The following settings are available:

FORCE_LOWERCASE_TAGS

--------------------

Default: ``False``

A boolean that turns on/off forcing of all tag names to lowercase before

they are saved to the database.

MAX_TAG_LENGTH

--------------

Default: ``50``

An integer which specifies the maximum length which any tag is allowed

to have. This is used for validation in the ``django.contrib.admin``

application and in any forms automatically generated using ``ModelForm``.

Registering your models

=======================

Your Django models can be registered with the tagging application to

access some additional tagging-related features.

.. note::

   You don't *have* to register your models in order to use them with

   the tagging application - many of the features added by registration

   are just convenience wrappers around the tagging API provided by the

   ``Tag`` and ``TaggedItem`` models and their managers, as documented

   further below.

The ``register`` function

-------------------------

To register a model, import the ``tagging`` module and call its

``register`` function, like so::

   from django.db import models

   import tagging

   class Widget(models.Model):

       name = models.CharField(max_length=50)

   tagging.register(Widget)

The following argument is required:

``model``

   The model class to be registered.

   An exception will be raised if you attempt to register the same class

   more than once.

The following arguments are optional, with some recommended defaults -

take care to specify different attribute names if the defaults clash

with your model class' definition:

``tag_descriptor_attr``

   The name of an attribute in the model class which will hold a tag

   descriptor for the model. Default: ``'tags'``

   See `TagDescriptor`_ below for details about the use of this

   descriptor.

``tagged_item_manger_attr``

   The name of an attribute in the model class which will hold a custom

   manager for accessing tagged items for the model. Default:

   ``'tagged'``.

   See `ModelTaggedItemManager`_ below for details about the use of this

   manager.

``TagDescriptor``

-----------------

When accessed through the model class itself, this descriptor will return

a ``ModelTagManager`` for the model. See `ModelTagManager`_ below for

more details about its use.

When accessed through a model instance, this descriptor provides a handy

means of retrieving, updating and deleting the instance's tags. For

example::

   >>> widget = Widget.objects.create(name='Testing descriptor')

   >>> widget.tags

   []

   >>> widget.tags = 'toast, melted cheese, butter'

   >>> widget.tags

   [<Tag: butter>, <Tag: melted cheese>, <Tag: toast>]

   >>> del widget.tags

   >>> widget.tags

   []

``ModelTagManager``

-------------------

A manager for retrieving tags used by a particular model.

Defines the following methods:

* ``get_query_set()`` -- as this method is redefined, any ``QuerySets``

  created by this model will be initially restricted to contain the

  distinct tags used by all the model's instances.

* ``cloud(*args, **kwargs)`` -- creates a list of tags used by the

  model's instances, with ``count`` and ``font_size`` attributes set for

  use in displaying a tag cloud.

  See the documentation on ``Tag``'s manager's `cloud_for_model method`_

  for information on additional arguments which can be given.

* ``related(self, tags, *args, **kwargs)`` -- creates a list of tags

  used by the model's instances, which are also used by all instance

  which have the given ``tags``.

  See the documentation on ``Tag``'s manager's

  `related_for_model method`_ for information on additional arguments

  which can be given.

* ``usage(self, *args, **kwargs))`` -- creates a list of tags used by

  the model's instances, with optional usages counts, restriction based

  on usage counts and restriction of the model instances from which

  usage and counts are determined.

  See the documentation on ``Tag``'s manager's `usage_for_model method`_

  for information on additional arguments which can be given.

Example usage::

   # Create a ``QuerySet`` of tags used by Widget instances

   Widget.tags.all()

   # Retrieve a list of tags used by Widget instances with usage counts

   Widget.tags.usage(counts=True)

   # Retrieve tags used by instances of WIdget which are also tagged with

   # 'cheese' and 'toast'

   Widget.tags.related(['cheese', 'toast'], counts=True, min_count=3)

``ModelTaggedItemManager``

--------------------------

A manager for retrieving model instance for a particular model, based on

their tags.

* ``related_to(obj, queryset=None, num=None)`` -- creates a list

  of model instances which are related to ``obj``, based on its tags. If

  a ``queryset`` argument is provided, it will be used to restrict the

  resulting list of model instances.

  If ``num`` is given, a maximum of ``num`` instances will be returned.

* ``with_all(tags, queryset=None)`` -- creates a ``QuerySet`` containing

  model instances which are tagged with *all* the given tags. If a

  ``queryset`` argument is provided, it will be used as the basis for

  the resulting ``QuerySet``.

* ``with_any(tags, queryset=None)`` -- creates a ``QuerySet`` containing model

  instances which are tagged with *any* the given tags. If a ``queryset``

  argument is provided, it will be used as the basis for the resulting

  ``QuerySet``.

Tags

====

Tags are represented by the ``Tag`` model, which lives in the

``tagging.models`` module.

API reference

-------------

Fields

~~~~~~

``Tag`` objects have the following fields:

* ``name`` -- The name of the tag. This is a unique value.

Manager functions

~~~~~~~~~~~~~~~~~

The ``Tag`` model has a custom manager which has the following helper

methods:

* ``update_tags(obj, tag_names)`` -- updates tags associated with an

  object.

  ``tag_names`` is a string containing tag names with which ``obj``

  should be tagged.

  If ``tag_names`` is ``None`` or ``''``, the object's tags will be

  cleared.

* ``add_tag(obj, tag_name)`` -- associates a tag with an an object.

  ``tag_name`` is a string containing a tag name with which ``obj``

  should be tagged.

* ``get_for_object(obj)`` -- returns a ``QuerySet`` containing all

  ``Tag`` objects associated with ``obj``.

.. _`usage_for_model method`:

* ``usage_for_model(model, counts=False, min_count=None, filters=None)``

  -- returns a list of ``Tag`` objects associated with instances of

  ``model``.

  If ``counts`` is ``True``, a ``count`` attribute will be added to each

  tag, indicating how many times it has been associated with instances

  of ``model``.

  If ``min_count`` is given, only tags which have a ``count`` greater

  than or equal to ``min_count`` will be returned. Passing a value for

  ``min_count`` implies ``counts=True``.

  To limit the tags (and counts, if specified) returned to those used by

  a subset of the model's instances, pass a dictionary of field lookups

  to be applied to ``model`` as the ``filters`` argument.

.. _`related_for_model method`:

* ``related_for_model(tags, Model, counts=False, min_count=None)``

  -- returns a list of tags related to a given list of tags - that is,

  other tags used by items which have all the given tags.

  If ``counts`` is ``True``, a ``count`` attribute will be added to each

  tag, indicating the number of items which have it in addition to the

  given list of tags.

  If ``min_count`` is given, only tags which have a ``count`` greater

  than or equal to ``min_count`` will be returned. Passing a value for

  ``min_count`` implies ``counts=True``.

.. _`cloud_for_model method`:

* ``cloud_for_model(Model, steps=4, distribution=LOGARITHMIC,

  filters=None, min_count=None)`` -- returns a list of the distinct

  ``Tag`` objects associated with instances of ``Model``, each having a

  ``count`` attribute as above and an additional ``font_size``

  attribute, for use in creation of a tag cloud (a type of weighted

  list).

  ``steps`` defines the number of font sizes available - ``font_size``

  may be an integer between ``1`` and ``steps``, inclusive.

  ``distribution`` defines the type of font size distribution algorithm

  which will be used - logarithmic or linear. It must be either

  ``tagging.utils.LOGARITHMIC`` or ``tagging.utils.LINEAR``.

  To limit the tags displayed in the cloud to those associated with a

  subset of the Model's instances, pass a dictionary of field lookups to

  be applied to the given Model as the ``filters`` argument.

  To limit the tags displayed in the cloud to those with a ``count``

  greater than or equal to ``min_count``, pass a value for the

  ``min_count`` argument.

* ``usage_for_queryset(queryset, counts=False, min_count=None)`` --

  Obtains a list of tags associated with instances of a model contained

  in the given queryset.

  If ``counts`` is True, a ``count`` attribute will be added to each tag,

  indicating how many times it has been used against the Model class in

  question.

  If ``min_count`` is given, only tags which have a ``count`` greater

  than or equal to ``min_count`` will be returned.

  Passing a value for ``min_count`` implies ``counts=True``.

Basic usage

-----------

Tagging objects and retrieving an object's tags

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Objects may be tagged using the ``update_tags`` helper function::

   >>> from shop.apps.products.models import Widget

   >>> from tagging.models import Tag

   >>> widget = Widget.objects.get(pk=1)

   >>> Tag.objects.update_tags(widget, 'house thing')

Retrieve tags for an object using the ``get_for_object`` helper

function::

   >>> Tag.objects.get_for_object(widget)

   [<Tag: house>, <Tag: thing>]

Tags are created, associated and unassociated accordingly when you use

``update_tags`` and ``add_tag``::

   >>> Tag.objects.update_tags(widget, 'house monkey')

   >>> Tag.objects.get_for_object(widget)

   [<Tag: house>, <Tag: monkey>]

   >>> Tag.objects.add_tag(widget, 'tiles')

   >>> Tag.objects.get_for_object(widget)

   [<Tag: house>, <Tag: monkey>, <Tag: tiles>]

Clear an object's tags by passing ``None`` or ``''`` to

``update_tags``::

   >>> Tag.objects.update_tags(widget, None)

   >>> Tag.objects.get_for_object(widget)

   []

Retrieving tags used by a particular model

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To retrieve all tags used for a particular model, use the

``get_for_model`` helper function::

   >>> widget1 = Widget.objects.get(pk=1)

   >>> Tag.objects.update_tags(widget1, 'house thing')

   >>> widget2 = Widget.objects.get(pk=2)

   >>> Tag.objects.update_tags(widget2, 'cheese toast house')

   >>> Tag.objects.usage_for_model(Widget)

   [<Tag: cheese>, <Tag: house>, <Tag: thing>, <Tag: toast>]

To get a count of how many times each tag was used for a particular

model, pass in ``True`` for the ``counts`` argument::

   >>> tags = Tag.objects.usage_for_model(Widget, counts=True)

   >>> [(tag.name, tag.count) for tag in tags]

   [('cheese', 1), ('house', 2), ('thing', 1), ('toast', 1)]

To get counts and limit the tags returned to those with counts above a

certain size, pass in a ``min_count`` argument::

   >>> tags = Tag.objects.usage_for_model(Widget, min_count=2)

   >>> [(tag.name, tag.count) for tag in tags]

   [('house', 2)]

You can also specify a dictionary of `field lookups`_ to be used to

restrict the tags and counts returned based on a subset of the

model's instances. For example, the following would retrieve all tags

used on Widgets created by a user named Alan which have a size

greater than 99::

   >>> Tag.objects.usage_for_model(Widget, filters=dict(size__gt=99, user__username='Alan'))

.. _`field lookups`: http://docs.djangoproject.com/en/dev/topics/db/queries/#field-lookups

The ``usage_for_queryset`` method allows you to pass a pre-filtered

queryset to be used when determining tag usage::

   >>> Tag.objects.usage_for_queryset(Widget.objects.filter(size__gt=99, user__username='Alan'))

Tag input

---------

Tag input from users is treated as follows:

* If the input doesn't contain any commas or double quotes, it is simply

  treated as a space-delimited list of tag names.

* If the input does contain either of these characters, we parse the

  input like so:

  * Groups of characters which appear between double quotes take

    precedence as multi-word tags (so double quoted tag names may

    contain commas). An unclosed double quote will be ignored.

  * For the remaining input, if there are any unquoted commas in the

    input, the remainder will be treated as comma-delimited. Otherwise,

    it will be treated as space-delimited.

Examples:

====================== ======================================= ================================================

Tag input string       Resulting tags                          Notes

====================== ======================================= ================================================

apple ball cat         [``apple``], [``ball``], [``cat``]      No commas, so space delimited

apple, ball cat        [``apple``], [``ball cat``]             Comma present, so comma delimited

"apple, ball" cat dog  [``apple, ball``], [``cat``], [``dog``] All commas are quoted, so space delimited

"apple, ball", cat dog [``apple, ball``], [``cat dog``]        Contains an unquoted comma, so comma delimited

apple "ball cat" dog   [``apple``], [``ball cat``], [``dog``]  No commas, so space delimited

"apple" "ball dog      [``apple``], [``ball``], [``dog``]      Unclosed double quote is ignored

====================== ======================================= ================================================

Tagged items

============

The relationship between a ``Tag`` and an object is represented by

the ``TaggedItem`` model, which lives in the ``tagging.models``

module.

API reference

-------------

Fields

~~~~~~

``TaggedItem`` objects have the following fields:

* ``tag`` -- The ``Tag`` an object is associated with.

* ``content_type`` -- The ``ContentType`` of the associated model

  instance.

* ``object_id`` -- The id of the associated object.

* ``object`` -- The associated object itself, accessible via the

  Generic Relations API.

Manager functions

~~~~~~~~~~~~~~~~~

The ``TaggedItem`` model has a custom manager which has the following

helper methods, which accept either a ``QuerySet`` or a ``Model``

class as one of their arguments. To restrict the objects which are

returned, pass in a filtered ``QuerySet`` for this argument:

* ``get_by_model(queryset_or_model, tag)`` -- creates a ``QuerySet``

  containing instances of the specififed model which are tagged with

  the given tag or tags.

* ``get_intersection_by_model(queryset_or_model, tags)`` -- creates a

  ``QuerySet`` containing instances of the specified model which are

  tagged with every tag in a list of tags.

  ``get_by_model`` will call this function behind the scenes when you