Imported Upstream version 0.2.1upstream/0.2.1

1 files changed, 751 insertions, 596 deletions

diff --git a/docs/overview.txt b/docs/overview.txt
index 61cb086..c5c72e6 100644
--- a/docs/overview.txt
+++ b/docs/overview.txt
@@ -1,596 +1,751 @@
-==============
-Django Tagging
-==============
-
-A generic tagging application for `Django`_ projects, which allows
-association of a number of tags with any ``Model`` instance and makes
-retrieval of tags simple.
-
-.. _`Django`: http://www.djangoproject.com
-
-
-Installation
-============
-
-Downloading django-tagging
---------------------------
-
-There are two options for downloading; one is to download the latest
-packaged version from http://code.google.com/p/django-tagging/ and
-unpack it; inside is a script called setup.py. Type this command::
-
-    python setup.py install
-
-...and the package will install automatically.
-
-The other method is to perform a Subversion checkout from somewhere on
-your Python path:
-
-    svn checkout http://django-tagging.googlecode.com/svn/trunk/tagging/
-
-Keep in mind that the current code in SVN may be different from the
-packaged release, and may contain bugs and backwards-incompatible
-changes.
-
-Using django-tagging in your projects
--------------------------------------
-
-Once you've downloaded django-tagging and want to use it in your
-projects, 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 django-tagging's behaviour may 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 tags to lowercase before they
-are saved to the database.
-
-
-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
-      consisting only of unicode alphanumeric characters, numbers,
-      underscores and hyphens.
-
-Manager functions
-~~~~~~~~~~~~~~~~~
-
-The ``Tag`` model has a custom manager which has the following helper
-functions:
-
-    * ``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. Valid tag names may contain unicode
-      alphanumeric characters, numbers, underscores or hyphens.
-      Multiple tag names may be specified, separated by any number of
-      commas and spaces.
-
-      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. Valid tag names may contain unicode
-      alphanumeric characters, numbers, underscores or hyphens.
-
-    * ``get_for_object(obj)`` -- Returns a ``QuerySet`` containing all
-      ``Tag`` objects associated with ``obj``.
-
-    * ``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(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(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.
-
-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_tags``::
-
-    >>> 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://www.djangoproject.com/documentation/db-api/#field-lookups
-
-
-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 object.
-    * ``object_id`` -- The id of the associated object.
-    * ``object`` -- The associated object.
-
-Manager functions
-~~~~~~~~~~~~~~~~~
-
-The ``TaggedItem`` model has a custom manager which has the following
-helper functions:
-
-    * ``get_by_model(Model, tag)`` -- If ``tag`` is an instance of a
-      ``Tag``, returns a ``QuerySet`` containing all instances of
-      ``Model`` which are tagged with it.
-
-      If ``tag`` is a list of tags, returns a ``QuerySet`` containing
-      all instances of ``Model`` which are tagged with every tag in
-      the list.
-
-    * ``get_intersection_by_model(Model, tags)`` -- Returns a
-      ``QuerySet`` containing all instances of ``Model`` which are
-      tagged with every tag in the list.
-
-      ``get_by_model`` will call this function behind the scenes when
-      you pass it a list, so it's recommended that you use
-      ``get_by_model`` instead of calling this function directly.
-
-    * ``get_related(obj, Model, num=None)`` - Returns instances of
-       ``Model`` which share tags with the model instance ``obj``,
-       ordered by the number of shared tags in descending order.
-
-       If ``num`` is given, a maximum of ``num`` instances will be
-       returned.
-
-Basic usage
------------
-
-Retrieving tagged objects
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Objects may be retrieved based on their tags using the ``get_by_model``
-helper function::
-
-    >>> from shop.apps.products.models import Widget
-    >>> from tagging.models import Tag
-    >>> house_tag = Tag.objects.get(name='house')
-    >>> TaggedItem.objects.get_by_model(Widget, house_tag)
-    [<Widget: pk=1>, <Widget: pk=2>]
-
-Passing a list of tags to ``get_by_model`` returns an intersection of
-objects which have those tags, i.e. tag1 AND tag2 ... AND tagN::
-
-    >>> thing_tag = Tag.objects.get(name='thing')
-    >>> TaggedItem.objects.get_by_model(Widget, [house_tag, thing_tag])
-    [<Widget: pk=1>]
-
-Functions which take tags are flexible when it comes to tag input::
-
-    >>> TaggedItem.objects.get_by_model(Widget, Tag.objects.filter(name__in=['house', 'thing']))
-    [<Widget: pk=1>]
-    >>> TaggedItem.objects.get_by_model(Widget, 'house thing')
-    [<Widget: pk=1>]
-    >>> TaggedItem.objects.get_by_model(Widget, ['house', 'thing'])
-    [<Widget: pk=1>]
-
-
-Utilities
-=========
-
-Tag-related utility functions are defined in the ``tagging.utils``
-module:
-
-get_tag_name_list(tags_names)
------------------------------
-
-Finds tag names in the given string and return them in a list.
-
-get_tag_list(tags)
-------------------
-
-Utility function for accepting tag input in a flexible manner.
-
-If a ``Tag`` object is given, it will be returned in a list as its
-single occupant.
-
-If given, the tag names in the following will be used to create a
-``Tag`` ``QuerySet``:
-
-    * A string, which may contain multiple tag names.
-    * A list or tuple of strings corresponding to tag names.
-    * A list or tuple of integers corresponding to tag ids.
-
-If given, the following will be returned as-is:
-
-    * A list or tuple of ``Tag`` objects.
-    * A ``Tag`` ``QuerySet``.
-
-calculate_cloud(tags, steps=4, distribution=tagging.utils.LOGARITHMIC)
-----------------------------------------------------------------------
-
-Adds a ``font_size`` attribute to each tag given according to the
-frequency of its use, as indicated by its ``count`` attribute.
-
-``steps`` defines the range of font sizes - ``font_size`` will 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`` (default) or ``tagging.utils.LINEAR``.
-
-The algorithm to scale the tags logarithmically is from a blog post by
-Anders Pearson, `Scaling tag clouds`_.
-
-.. _`Scaling tag clouds`: http://thraxil.com/users/anders/posts/2005/12/13/scaling-tag-clouds/
-
-
-Model Fields
-============
-
-The ``tagging.fields`` module contains fields which make it easy to
-integrate tagging into your models and into the
-``django.contrib.admin`` application.
-
-Field types
------------
-
-``TagField``
-~~~~~~~~~~~~
-
-A ``CharField`` that actually works as a relationship to tags "under
-the hood".
-
-Using this example model::
-
-    class Link(models.Model):
-        ...
-        tags = TagField()
-
-Setting tags::
-
-    >>> l = Link.objects.get(...)
-    >>> l.tags = 'tag1 tag2 tag3'
-
-Getting tags for an instance::
-
-    >>> l.tags
-    'tag1 tag2 tag3'
-
-Getting tags for a model - i.e. all tags used by all instances of the
-model::
-
-    >>> Link.tags
-    'tag1 tag2 tag3 tag4 tag5'
-
-This field will also validate that it has been given a valid list of
-tag names, separated by a single comma, a single space or a comma
-followed by a space, using the ``isTagList`` validator from
-``tagging.validators``.
-
-
-Form Fields
-===========
-
-The ``tagging.forms`` module contains a ``Field`` for use with
-Django's `newforms library`_ which takes care of validating tag name
-input when used in your forms.
-
-.. _`newforms library`: http://www.djangoproject.com/documentation/newforms/
-
-Field types
------------
-
-``TagField``
-~~~~~~~~~~~~
-
-A form ``Field`` which is displayed as a single-line text input, which
-validates that the input it receives is a valid list of tag names,
-separated by a single comma, a single space or a comma followed by a
-space.
-
-When you generate a form for one of your models automatically, using
-the ``form_for_model`` or ``form_for_instance`` functions provided by
-the newforms library, any ``tagging.fields.TagField`` fields in your
-model will automatically be represented by a
-``tagging.forms.TagField`` in the generated form.
-
-
-Simplified tagging and retrieval of tags with properties
-========================================================
-
-If you're not using ``TagField``, a useful method for simplifying
-tagging and retrieval of tags for your models is to set up a
-property::
-
-    from django.db import models
-    from tagging.models import Tag
-
-    class MyModel(models.Model):
-        name = models.CharField(maxlength=100)
-        tag_list = models.CharField(maxlength=255)
-
-        def save(self):
-            super(MyModel, self).save()
-            self.tags = self.tag_list
-
-        def _get_tags(self):
-            return Tag.objects.get_for_object(self)
-
-        def _set_tags(self, tag_list):
-            Tag.objects.update_tags(self, tag_list)
-
-        tags = property(_get_tags, _set_tags)
-
-        def __str__(self):
-            return self.name
-
-Once you've set this up, you can access and set tags in a fairly
-natural way::
-
-    >>> obj = MyModel.objects.get(pk=1)
-    >>> obj.tags = 'foo bar'
-    >>> obj.tags
-    [<Tag: bar>, <Tag: foo>]
-
-Remember that ``obj.tags`` will return a ``QuerySet``, so you can
-perform further filtering on it, should you need to.
-
-
-Generic Views
-=============
-
-**New in django-tagging development version**
-
-The ``tagging.views`` module contains views to handle common display
-ogic related to tagging.
-
-The following sample URLconf demonstrates using a generic view to list
-items of a particular model which have a given tag::
-
-    from django.conf.urls.defaults import *
-    from tagging.views import tagged_object_list
-    from shop.apps.products.models import Widget
-
-    urlpatterns = patterns('',
-        (r'^widgets/tag/(?P<tag>[^/]+(?u))/$', tagged_object_list,
-            dict(model=Widget, paginate_by=10, allow_empty=True,
-                 template_object_name='widget')),
-    )
-
-``tagging.views.tagged_object_list``
-------------------------------------
-
-**Description:**
-
-A view that displays a list of objects for a given model which have a
-given tag. This is a thin wrapper around the
-``django.views.generic.list_detail.object_list`` view, which takes a
-model and a tag as its arguments (in addition to the other optional
-arguments supported by ``object_list``), building the appropriate
-``QuerySet`` for you instead of expecting one to be passed in.
-
-**Required arguments:**
-
-    * ``model``: The Django model class of the object that will be
-      listed.
-
-    * ``tag``: The tag which objects of the given model must have in
-      order to be listed.
-
-**Optional arguments:**
-
-Please refer to the `object_list documentation`_ for additional optional
-arguments which may be given.
-
-    * ``related_tags``: If ``True``, a ``related_tags`` context variable
-      will also contain tags related to the given tag for the given
-      model.
-
-    * ``related_tag_counts``: If ``True`` and ``related_tags`` is
-      ``True``, each related tag will have a ``count`` attribute
-      indicating the number of items which have it in addition to the
-      given tag.
-
-**Template context:**
-
-    * ``tag``: The ``Tag`` instance for the given tag.
-
-Please refer to the `object_list documentation`_ for  additional
-template context variables which may be provided.
-
-.. _`object_list documentation`: http://www.djangoproject.com/documentation/generic_views/#django-views-generic-list-detail-object-list
-
-Template tags
-=============
-
-The ``tagging.templatetags.tagging_tags`` module defines a number of
-template tags which may be used to work with tags.
-
-Tag reference
--------------
-
-tags_for_model
-~~~~~~~~~~~~~~
-
-Retrieves a list of tags associated with the given model and stores
-them in a context variable.
-
-The model is specified in ``[appname].[modelname]`` format.
-
-If specified - by providing extra ``with counts`` arguments - adds a
-``count`` attribute to each tag containing the number of instances of
-the given model which have been tagged with it.
-
-Example usage::
-
-    {% tags_for_model products.Widget as widget_tags %}
-
-    {% tags_for_model products.Widget as widget_tags with counts %}
-
-tags_for_object
-~~~~~~~~~~~~~~~
-
-Retrieves a list of tags associated with an object and stores them in
-a context variable.
-
-Example usage::
-
-    {% tags_for_object widget as tag_list %}
-
-tagged_objects
-~~~~~~~~~~~~~~
-
-Retrieves a list of objects for a given model which are tagged with
-a given tag and stores them in a context variable.
-
-The tag must be an instance of a ``Tag``, not the name of a tag.
-
-The model is specified in ``[appname].[modelname]`` format.
-
-Example usage::
-
-    {% tagged_objects house_tag in products.Widget as widgets %}
\ No newline at end of file
+==============

+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

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

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

+``mptt-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, 2, '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://docs.python.org/tut/node8.html#SECTION008110000000000000000

+.. _`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 Django Tagging's behaviour may 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 maxiumum length which any tag is allowed

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

+application and in any ``newforms`` forms automatically generated using

+``ModelForm``.

+

+

+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

+functions:

+

+   * ``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(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(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(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.

+

+Basic usage

+-----------

+

+Tag input

+~~~~~~~~~

+

+Tag input from users is treated as follows:

+

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

+  simply treated as a space-delimited list of tag names.

+

+* If the tag 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              Resulting tag names                     Notes

+====================== ======================================= ================================================

+apple ball cat         [``apple``], [``ball``], [``cat``]      No commas or quotes, 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

+====================== ======================================= ================================================

+

+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_tags``::

+

+   >>> 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://www.djangoproject.com/documentation/db-api/#field-lookups

+

+

+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 functions:

+

+   * ``get_by_model(Model, tag)`` -- If ``tag`` is an instance of a

+     ``Tag``, returns a ``QuerySet`` containing all instances of

+     ``Model`` which are tagged with it.

+

+     If ``tag`` is a list of tags, returns a ``QuerySet`` containing

+     all instances of ``Model`` which are tagged with every tag in

+     the list.

+

+   * ``get_intersection_by_model(Model, tags)`` -- Returns a

+     ``QuerySet`` containing all instances of ``Model`` which are

+     tagged with every tag in the list.

+

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

+     you pass it a list, so it's recommended that you use

+     ``get_by_model`` instead of calling this function directly.

+

+   * ``get_union_by_model(Model, tags)`` -- Returns a ``QuerySet``

+     containing all instances of ``Model`` which are tagged with any tag

+     in the list.

+

+   * ``get_related(obj, Model, num=None)`` - Returns instances of

+     ``Model`` which share tags with the model instance ``obj``,

+     ordered by the number of shared tags in descending order.

+

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

+     returned.

+

+Basic usage

+-----------

+

+Retrieving tagged objects

+~~~~~~~~~~~~~~~~~~~~~~~~~

+

+Objects may be retrieved based on their tags using the ``get_by_model``

+manager method::

+

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

+   >>> from tagging.models import Tag

+   >>> house_tag = Tag.objects.get(name='house')

+   >>> TaggedItem.objects.get_by_model(Widget, house_tag)

+   [<Widget: pk=1>, <Widget: pk=2>]

+

+Passing a list of tags to ``get_by_model`` returns an intersection of

+objects which have those tags, i.e. tag1 AND tag2 ... AND tagN::

+

+   >>> thing_tag = Tag.objects.get(name='thing')

+   >>> TaggedItem.objects.get_by_model(Widget, [house_tag, thing_tag])

+   [<Widget: pk=1>]

+

+Functions which take tags are flexible when it comes to tag input::

+

+   >>> TaggedItem.objects.get_by_model(Widget, Tag.objects.filter(name__in=['house', 'thing']))

+   [<Widget: pk=1>]

+   >>> TaggedItem.objects.get_by_model(Widget, 'house thing')

+   [<Widget: pk=1>]

+   >>> TaggedItem.objects.get_by_model(Widget, ['house', 'thing'])

+   [<Widget: pk=1>]

+

+

+Utilities

+=========

+

+Tag-related utility functions are defined in the ``tagging.utils``

+module:

+

+``parse_tag_input(input)``

+--------------------------

+

+Parses tag input, with multiple word input being activated and

+delineated by commas and double quotes. Quotes take precedence, so they

+may contain commas.

+

+Returns a sorted list of unique tag names.

+

+See `tag input`_ for more details.

+

+``edit_string_for_tags(tags)``

+------------------------------

+Given list of ``Tag`` instances, creates a string representation of the

+list suitable for editing by the user, such that submitting the given

+string representation back without changing it will give the same list

+of tags.

+

+Tag names which contain commas will be double quoted.

+

+If any tag name which isn't being quoted contains whitespace, the

+resulting string of tag names will be comma-delimited, otherwise it will

+be space-delimited.

+

+``get_tag_list(tags)``

+----------------------

+

+Utility function for accepting tag input in a flexible manner.

+

+If a ``Tag`` object is given, it will be returned in a list as its

+single occupant.

+

+If given, the tag names in the following will be used to create a

+``Tag`` ``QuerySet``:

+

+   * A string, which may contain multiple tag names.

+   * A list or tuple of strings corresponding to tag names.

+   * A list or tuple of integers corresponding to tag ids.

+

+If given, the following will be returned as-is:

+

+   * A list or tuple of ``Tag`` objects.

+   * A ``Tag`` ``QuerySet``.

+

+``calculate_cloud(tags, steps=4, distribution=tagging.utils.LOGARITHMIC)``

+--------------------------------------------------------------------------

+

+Add a ``font_size`` attribute to each tag according to the frequency of

+its use, as indicated by its ``count`` attribute.

+

+``steps`` defines the range of font sizes - ``font_size`` will 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 one of

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

+

+

+Model Fields

+============

+

+The ``tagging.fields`` module contains fields which make it easy to

+integrate tagging into your models and into the

+``django.contrib.admin`` application.

+

+Field types

+-----------

+

+``TagField``

+~~~~~~~~~~~~

+

+A ``CharField`` that actually works as a relationship to tags "under

+the hood".

+

+Using this example model::

+

+   class Link(models.Model):

+       ...

+       tags = TagField()

+

+Setting tags::

+

+   >>> l = Link.objects.get(...)

+   >>> l.tags = 'tag1 tag2 tag3'

+

+Getting tags for an instance::

+

+   >>> l.tags

+   'tag1 tag2 tag3'

+

+Getting tags for a model - i.e. all tags used by all instances of the

+model::

+

+   >>> Link.tags

+   'tag1 tag2 tag3 tag4 tag5'

+

+This field will also validate that it has been given a valid list of

+tag names, separated by a single comma, a single space or a comma

+followed by a space, using the ``isTagList`` validator from

+``tagging.validators``.

+

+

+Form fields

+===========

+

+The ``tagging.forms`` module contains a ``Field`` for use with

+Django's `newforms library`_ which takes care of validating tag name

+input when used in your forms.

+

+.. _`newforms library`: http://www.djangoproject.com/documentation/newforms/

+

+Field types

+-----------

+

+``TagField``

+~~~~~~~~~~~~

+

+A form ``Field`` which is displayed as a single-line text input, which

+validates that the input it receives is a valid list of tag names.

+

+When you generate a form for one of your models automatically, using

+the ``ModelForm`` class provided by newforms, any

+``tagging.fields.TagField`` fields in your model will automatically be

+represented by a ``tagging.forms.TagField`` in the generated form.

+

+

+Simplified tagging and retrieval of tags with properties

+========================================================

+

+If you're not using ``TagField``, a useful method for simplifying

+tagging and retrieval of tags for your models is to set up a

+property::

+

+   from django.db import models

+   from tagging.models import Tag

+

+   class MyModel(models.Model):

+       name = models.CharField(maxlength=100)

+       tag_list = models.CharField(maxlength=255)

+

+       def save(self):

+           super(MyModel, self).save()

+           self.tags = self.tag_list

+

+       def _get_tags(self):

+           return Tag.objects.get_for_object(self)

+

+       def _set_tags(self, tag_list):

+           Tag.objects.update_tags(self, tag_list)

+

+       tags = property(_get_tags, _set_tags)

+

+       def __unicode__(self):

+           return self.name

+

+Once you've set this up, you can access and set tags in a fairly

+natural way::

+

+   >>> obj = MyModel.objects.get(pk=1)

+   >>> obj.tags = 'foo bar'

+   >>> obj.tags

+   [<Tag: bar>, <Tag: foo>]

+

+Remember that ``obj.tags`` will return a ``QuerySet``, so you can

+perform further filtering on it, should you need to.

+

+

+Generic views

+=============

+

+The ``tagging.views`` module contains views to handle simple cases of

+common display logic related to tagging.

+

+``tagging.views.tagged_object_list``

+------------------------------------

+

+**Description:**

+

+A view that displays a list of objects for a given model which have a

+given tag. This is a thin wrapper around the

+``django.views.generic.list_detail.object_list`` view, which takes a

+model and a tag as its arguments (in addition to the other optional

+arguments supported by ``object_list``), building the appropriate

+``QuerySet`` for you instead of expecting one to be passed in.

+

+**Required arguments:**

+

+   * ``model``: The Django model class of the object that will be

+     listed.

+

+   * ``tag``: The tag which objects of the given model must have in

+     order to be listed.

+

+**Optional arguments:**

+

+Please refer to the `object_list documentation`_ for additional optional

+arguments which may be given.

+

+   * ``related_tags``: If ``True``, a ``related_tags`` context variable

+     will also contain tags related to the given tag for the given

+     model.

+

+   * ``related_tag_counts``: If ``True`` and ``related_tags`` is

+     ``True``, each related tag will have a ``count`` attribute

+     indicating the number of items which have it in addition to the

+     given tag.

+

+**Template context:**

+

+Please refer to the `object_list documentation`_ for  additional

+template context variables which may be provided.

+

+   * ``tag``: The ``Tag`` instance for the given tag.

+

+.. _`object_list documentation`: http://www.djangoproject.com/documentation/generic_views/#django-views-generic-list-detail-object-list

+

+Example usage

+~~~~~~~~~~~~~

+

+The following sample URLconf demonstrates using this generic view to

+list items of a particular model class which have a given tag::

+

+   from django.conf.urls.defaults import *

+   from tagging.views import tagged_object_list

+   from shop.apps.products.models import Widget

+

+   urlpatterns = patterns('',

+       url(r'^widgets/tag/(?P<tag>[^/]+)/$',

+           tagged_object_list,

+           dict(model=Widget, paginate_by=10, allow_empty=True,

+                template_object_name='widget'),

+           name='widget_tag_detail'),

+   )

+

+

+Template tags

+=============

+

+The ``tagging.templatetags.tagging_tags`` module defines a number of

+template tags which may be used to work with tags.

+

+Tag reference

+-------------

+

+tags_for_model

+~~~~~~~~~~~~~~

+

+Retrieves a list of ``Tag`` objects associated with a given model and

+stores them in a context variable.

+

+Usage::

+

+   {% tags_for_model [model] as [varname] %}

+

+The model is specified in ``[appname].[modelname]`` format.

+

+Extended usage::

+

+   {% tags_for_model [model] as [varname] with counts %}

+

+If specified - by providing extra ``with counts`` arguments - adds a

+``count`` attribute to each tag containing the number of instances of

+the given model which have been tagged with it.

+

+Examples::

+

+   {% tags_for_model products.Widget as widget_tags %}

+   {% tags_for_model products.Widget as widget_tags with counts %}

+

+tag_cloud_for_model

+~~~~~~~~~~~~~~~~~~~

+

+Retrieves a list of ``Tag`` objects for a given model, with tag cloud

+attributes set, and stores them in a context variable.

+

+Usage::

+

+   {% tag_cloud_for_model [model] as [varname] %}

+

+The model is specified in ``[appname].[modelname]`` format.

+

+Extended usage::

+

+   {% tag_cloud_for_model [model] as [varname] with [options] %}

+

+Extra options can be provided after an optional ``with`` argument, with

+each option being specified in ``[name]=[value]`` format. Valid extra

+options are:

+

+   ``steps``

+      Integer. Defines the range of font sizes.

+

+   ``min_count``

+      Integer. Defines the minimum number of times a tag must have

+      been used to appear in the cloud.

+

+   ``distribution``

+      One of ``linear`` or ``log``. Defines the font-size

+      distribution algorithm to use when generating the tag cloud.

+

+Examples::

+

+   {% tag_cloud_for_model products.Widget as widget_tags %}

+   {% tag_cloud_for_model products.Widget as widget_tags with steps=9 min_count=3 distribution=log %}

+

+tags_for_object

+~~~~~~~~~~~~~~~

+

+Retrieves a list of ``Tag`` objects associated with an object and stores

+them in a context variable.

+

+Usage::

+

+   {% tags_for_object [object] as [varname] %}

+

+Example::

+

+    {% tags_for_object foo_object as tag_list %}

+

+tagged_objects

+~~~~~~~~~~~~~~

+

+Retrieves a list of instances of a given model which are tagged with a

+given ``Tag`` and stores them in a context variable.

+

+Usage::

+

+   {% tagged_objects [tag] in [model] as [varname] %}

+

+The model is specified in ``[appname].[modelname]`` format.

+

+The tag must be an instance of a ``Tag``, not the name of a tag.

+

+Example::

+

+    {% tagged_objects comedy_tag in tv.Show as comedies %}