Commits

fivethreeo  committed 1763dbe

initial commit

  • Participants

Comments (0)

Files changed (24)

File CHANGELOG.txt

+========================
+Django Tagging Changelog
+========================
+
+
+SVN Trunk Changes:
+------------------
+
+* Added a ``tagging.generic`` module for working with list of objects
+  which have generic relations, containing a ``fetch_content_objects``
+  function for retrieving content objects for a list of ``TaggedItem``s
+  using ``number_of_content_types + 1`` queries rather than the
+  ``number_of_tagged_items * 2`` queries you'd get by iterating over the
+  list and accessing each item's ``object`` attribute.
+
+* Added a ``usage`` method to ``ModelTagManager``.
+
+* ``TaggedItemManager``'s methods now accept a ``QuerySet`` or a
+  ``Model`` class. If a ``QuerySet`` is given, it will be used as the
+  basis for the ``QuerySet``s the methods return, so can be used to
+  restrict results to a subset of a model's instances. The 
+  `tagged_object_list`` generic view and ModelTaggedItemManager``
+  manager have been updated accordingly.
+
+* Removed ``tagging\tests\runtests.py``, as tests can be run with
+  ``django-admin.py test --settings=tagging.tests.settings``.
+
+* A ``tagging.TagDescriptor`` is now added to models when registered.
+  This returns a ``tagging.managers.ModelTagManager`` when accessed on a
+  model class, and provide access to and control over tags when used on
+  an instance.
+
+* Added ``tagging.register`` to register models with the tagging app.
+  Initially, a ``tagging.managers.ModelTaggedItemManager`` is added for
+  convenient access to tagged items.
+
+* Moved ``TagManager`` and ``TaggedItemManager`` to ``models.py`` - gets
+  rid of some import related silliness, as ``TagManager`` needs access
+  to ``TaggedItem``.
+
+Version 0.2.1, 16th Jan 2008:
+-----------------------------
+
+* Fixed a bug with space-delimited tag input handling - duplicates
+  weren't being removed and the list of tag names wasn't sorted.
+
+Version 0.2, 12th Jan 2008:
+---------------------------
+
+Packaged from revision 122 in Subversion; download at
+http://django-tagging.googlecode.com/files/tagging-0.2.zip
+
+* Added a ``tag_cloud_for_model`` template tag.
+
+* Added a ``MAX_TAG_LENGTH`` setting.
+
+* Multi-word tags are here - simple space-delimited input still works.
+  Double quotes and/or commas are used to delineate multi- word tags.
+  As far as valid tag contents - anything goes, at least initially.
+
+* BACKWARDS-INCOMPATIBLE CHANGE - ``django.utils.get_tag_name_list`` and
+  related regular expressions have been removed in favour of a new tag
+  input parsing function, ``django.utils.parse_tag_input``.
+
+* BACKWARDS-INCOMPATIBLE CHANGE - ``Tag`` and ``TaggedItem`` no longer
+  declare an explicit ``db_table``. If you can't rename your tables,
+  you'll have to put these back in manually.
+
+* Fixed a bug in calculation of logarithmic tag clouds - ``font_size``
+  attributes were not being set in some cases when the least used tag in
+  the cloud had been used more than once.
+
+* For consistency of return type, ``TaggedItemManager.get_by_model`` now
+  returns an empty ``QuerySet`` instead of an empty ``list`` if
+  non-existent tags were given.
+
+* Fixed a bug caused by ``cloud_for_model`` not passing its
+  ``distribution`` argument to ``calculate_cloud``.
+
+* Added ``TaggedItemManager.get_union_by_model`` for looking up items
+  tagged with any one of a list of tags.
+
+* Added ``TagManager.add_tag`` for adding a single extra tag to an
+  object.
+
+* Tag names can now be forced to lowercase before they are saved to the
+  database by adding the appropriate ``FORCE_LOWERCASE_TAGS`` setting to
+  your project's settings module. This feature defaults to being off.
+
+* Fixed a bug where passing non-existent tag names to
+  ``TaggedItemManager.get_by_model`` caused database errors with some
+  backends.
+
+* Added ``tagged_object_list`` generic view for displaying paginated
+  lists of objects for a given model which have a given tag, and
+  optionally related tags for that model.
+
+
+Version 0.1, 30th May 2007:
+---------------------------
+
+Packaged from revision 79 in Subversion; download at
+http://django-tagging.googlecode.com/files/tagging-0.1.zip
+
+* First packaged version using distutils.
+Thanks for downloading django-tagging.
+
+To install it, run the following command inside this directory:
+
+    python setup.py install
+
+Or if you'd prefer you can simply place the included ``tagging``
+directory somewhere on your Python path, or symlink to it from
+somewhere on your Python path; this is useful if you're working from a
+Subversion checkout.
+
+Note that this application requires Python 2.3 or later, and Django
+0.96 or later. You can obtain Python from http://www.python.org/ and
+Django from http://www.djangoproject.com/.
+Django Tagging
+--------------
+
+Copyright (c) 2007, Jonathan Buchanan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Initially based on code from James Bennett's Cab:
+
+Cab
+---
+
+Copyright (c) 2007, James Bennett
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of the author nor the names of other
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+include CHANGELOG.txt
+include INSTALL.txt
+include LICENSE.txt
+include MANIFEST.in
+include README.txt
+recursive-include docs *.txt
+recursive-include tagging/tests *.txt
+==============
+Django Tagging
+==============
+
+This is a generic tagging application for Django projects
+
+For installation instructions, see the file "INSTALL.txt" in this
+directory; for instructions on how to use this application, and on
+what it provides, see the file "overview.txt" in the "docs/"
+directory.

File docs/overview.txt

+==============
+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
+=======================
+
+**New in developement version**
+
+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.
+
+**New in development version**
+
+* ``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
+
+**New in development version**
+
+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
+  pass it a list, so you can use ``get_by_model`` instead of calling
+  this method directly.
+
+* ``get_union_by_model(queryset_or_model, tags)`` -- creates a
+  ``QuerySet`` containing instances of the specified model which are
+  tagged with any tag in a list of tags.
+
+.. _`get_related method`:
+
+* ``get_related(obj, queryset_or_model, num=None)`` - returns a list of
+  instances of the specified 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>]
+
+Restricting objects returned
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pass in a ``QuerySet`` to restrict the objects returned::
+
+   # Retrieve all Widgets which have a price less than 50, tagged with 'house'
+   TaggedItem.objects.get_by_model(Widget.objects.filter(price__lt=50), 'house')
+
+   # Retrieve all Widgets which have a name starting with 'a', tagged with any
+   # of 'house', 'garden' or 'water'.
+   TaggedItem.objects.get_union_by_model(Widget.objects.filter(name__startswith='a'),
+                                         ['house', 'garden', 'water'])
+
+
+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.
+
+
+Form fields
+===========
+
+The ``tagging.forms`` module contains a ``Field`` for use with
+Django's `forms library`_ which takes care of validating tag name
+input when used in your forms.
+
+.. _`forms library`: http://docs.djangoproject.com/en/dev/topics/forms/
+
+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, any ``tagging.fields.TagField`` fields in your
+model will automatically be represented by a ``tagging.forms.TagField``
+in the generated form.
+
+
+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:**
+
+   * ``queryset_or_model``: A ``QuerySet`` or Django model class for the
+     object which 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://docs.djangoproject.com/en/dev/ref/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(queryset_or_model=Widget, paginate_by=10, allow_empty=True,
+                template_object_name='widget'),
+           name='widget_tag_detail'),
+   )
+
+The following sample view demonstrates wrapping this generic view to
+perform filtering of the objects which are listed::
+
+   from myapp.models import People
+
+   from tagging.views import tagged_object_list
+
+   def tagged_people(request, country_code, tag):
+       queryset = People.objects.filter(country__code=country_code)
+       return tagged_object_list(request, queryset, tag, paginate_by=25,
+           allow_empty=True, template_object_name='people')
+
+
+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 %}
+"""
+Based entirely on Django's own ``setup.py``.
+"""
+import os
+from distutils.command.install import INSTALL_SCHEMES
+from distutils.core import setup
+
+def fullsplit(path, result=None):
+    """
+    Split a pathname into components (the opposite of os.path.join) in a
+    platform-neutral way.
+    """
+    if result is None:
+        result = []
+    head, tail = os.path.split(path)
+    if head == '':
+        return [tail] + result
+    if head == path:
+        return result
+    return fullsplit(head, [tail] + result)
+
+# Tell distutils to put the data_files in platform-specific installation
+# locations. See here for an explanation:
+# http://groups.google.com/group/comp.lang.python/browse_thread/thread/35ec7b2fed36eaec/2105ee4d9e8042cb
+for scheme in INSTALL_SCHEMES.values():
+    scheme['data'] = scheme['purelib']
+
+# Compile the list of packages available, because distutils doesn't have
+# an easy way to do this.
+packages, data_files = [], []
+root_dir = os.path.dirname(__file__)
+tagging_dir = os.path.join(root_dir, 'tagging')
+pieces = fullsplit(root_dir)
+if pieces[-1] == '':
+    len_root_dir = len(pieces) - 1
+else:
+    len_root_dir = len(pieces)
+
+for dirpath, dirnames, filenames in os.walk(tagging_dir):
+    # Ignore dirnames that start with '.'
+    for i, dirname in enumerate(dirnames):
+        if dirname.startswith('.'): del dirnames[i]
+    if '__init__.py' in filenames:
+        packages.append('.'.join(fullsplit(dirpath)[len_root_dir:]))
+    elif filenames:
+        data_files.append([dirpath, [os.path.join(dirpath, f) for f in filenames]])
+
+# Dynamically calculate the version based on tagging.VERSION
+version_tuple = (0, 3, 'pre')
+if version_tuple[2] is not None:
+    version = "%d.%d_%s" % version_tuple
+else:
+    version = "%d.%d" % version_tuple[:2]
+
+setup(
+    name = 'tagging',
+    version = version,
+    description = 'Generic tagging application for Django',
+    author = 'Jonathan Buchanan',
+    author_email = 'jonathan.buchanan@gmail.com',
+    url = 'http://code.google.com/p/django-tagging/',
+    packages = packages,
+    data_files = data_files,
+    classifiers = ['Development Status :: 4 - Beta',
+                   'Environment :: Web Environment',
+                   'Framework :: Django',
+                   'Intended Audience :: Developers',
+                   'License :: OSI Approved :: BSD License',
+                   'Operating System :: OS Independent',
+                   'Programming Language :: Python',
+                   'Topic :: Utilities'],
+)

File tagging/__init__.py

+from django.utils.translation import ugettext as _
+
+from tagging.managers import ModelTaggedItemManager, TagDescriptor
+
+VERSION = (0, 3, 'pre')
+
+class AlreadyRegistered(Exception):
+    """
+    An attempt was made to register a model more than once.
+    """
+    pass
+
+registry = []
+
+def register(model, tag_descriptor_attr='tags',
+             tagged_item_manager_attr='tagged'):
+    """
+    Sets the given model class up for working with tags.
+    """
+    if model in registry:
+        raise AlreadyRegistered(
+            _('The model %s has already been registered.') % model.__name__)
+    registry.append(model)
+
+    # Add tag descriptor
+    setattr(model, tag_descriptor_attr, TagDescriptor())
+
+    # Add custom manager
+    ModelTaggedItemManager().contribute_to_class(model,
+                                                 tagged_item_manager_attr)

File tagging/admin.py

+from django.contrib import admin
+from tagging.models import Tag, TaggedItem
+
+admin.site.register(TaggedItem)
+admin.site.register(Tag)

File tagging/fields.py

+"""
+A custom Model Field for tagging.
+"""
+from django.db.models import signals
+from django.db.models.fields import CharField
+from django.utils.translation import ugettext_lazy as _
+
+from tagging import settings
+from tagging.models import Tag
+from tagging.utils import edit_string_for_tags
+
+class TagField(CharField):
+    """
+    A "special" character field that actually works as a relationship to tags
+    "under the hood". This exposes a space-separated string of tags, but does
+    the splitting/reordering/etc. under the hood.
+    """
+    def __init__(self, *args, **kwargs):
+        kwargs['max_length'] = kwargs.get('max_length', 255)
+        kwargs['blank'] = kwargs.get('blank', True)
+        super(TagField, self).__init__(*args, **kwargs)
+
+    def contribute_to_class(self, cls, name):
+        super(TagField, self).contribute_to_class(cls, name)
+
+        # Make this object the descriptor for field access.
+        setattr(cls, self.name, self)
+
+        # Save tags back to the database post-save
+        signals.post_save.connect(self._save, cls, True)
+
+    def __get__(self, instance, owner=None):
+        """
+        Tag getter. Returns an instance's tags if accessed on an instance, and
+        all of a model's tags if called on a class. That is, this model::
+
+           class Link(models.Model):
+               ...
+               tags = TagField()
+
+        Lets you do both of these::
+
+           >>> l = Link.objects.get(...)
+           >>> l.tags
+           'tag1 tag2 tag3'
+
+           >>> Link.tags
+           'tag1 tag2 tag3 tag4'
+
+        """
+        # Handle access on the model (i.e. Link.tags)
+        if instance is None:
+            return edit_string_for_tags(Tag.objects.usage_for_model(owner))
+
+        tags = self._get_instance_tag_cache(instance)
+        if tags is None:
+            if instance.pk is None:
+                self._set_instance_tag_cache(instance, '')
+            else:
+                self._set_instance_tag_cache(
+                    instance, edit_string_for_tags(Tag.objects.get_for_object(instance)))
+        return self._get_instance_tag_cache(instance)
+
+    def __set__(self, instance, value):
+        """
+        Set an object's tags.
+        """
+        if instance is None:
+            raise AttributeError(_('%s can only be set on instances.') % self.name)
+        if settings.FORCE_LOWERCASE_TAGS and value is not None:
+            value = value.lower()
+        self._set_instance_tag_cache(instance, value)
+
+    def _save(self, **kwargs): #signal, sender, instance):
+        """
+        Save tags back to the database
+        """
+        tags = self._get_instance_tag_cache(kwargs['instance'])
+        if tags is not None:
+            Tag.objects.update_tags(kwargs['instance'], tags)
+
+    def __delete__(self, instance):
+        """
+        Clear all of an object's tags.
+        """
+        self._set_instance_tag_cache(instance, '')
+
+    def _get_instance_tag_cache(self, instance):
+        """
+        Helper: get an instance's tag cache.
+        """
+        return getattr(instance, '_%s_cache' % self.attname, None)
+
+    def _set_instance_tag_cache(self, instance, tags):
+        """
+        Helper: set an instance's tag cache.
+        """
+        setattr(instance, '_%s_cache' % self.attname, tags)
+
+    def get_internal_type(self):
+        return 'CharField'
+
+    def formfield(self, **kwargs):
+        from tagging import forms
+        defaults = {'form_class': forms.TagField}
+        defaults.update(kwargs)
+        return super(TagField, self).formfield(**defaults)

File tagging/forms.py

+"""
+Tagging components for Django's form library.
+"""
+from django import forms
+from django.utils.translation import ugettext as _
+
+from tagging import settings
+from tagging.models import Tag
+from tagging.utils import parse_tag_input
+
+class AdminTagForm(forms.ModelForm):
+    class Meta:
+        model = Tag
+
+    def clean_name(self):
+        value = self.cleaned_data['name']
+        tag_names = parse_tag_input(value)
+        if len(tag_names) > 1:
+            raise ValidationError(_('Multiple tags were given.'))
+        elif len(tag_names[0]) > settings.MAX_TAG_LENGTH:
+            raise forms.ValidationError(
+                _('A tag may be no more than %s characters long.') %
+                    settings.MAX_TAG_LENGTH)
+        return value
+
+class TagField(forms.CharField):
+    """
+    A ``CharField`` which validates that its input is a valid list of
+    tag names.
+    """
+    def clean(self, value):
+        value = super(TagField, self).clean(value)
+        if value == u'':
+            return value
+        for tag_name in parse_tag_input(value):
+            if len(tag_name) > settings.MAX_TAG_LENGTH:
+                raise forms.ValidationError(
+                    _('Each tag may be no more than %s characters long.') %
+                        settings.MAX_TAG_LENGTH)
+        return value

File tagging/generic.py

+from django.contrib.contenttypes.models import ContentType
+
+def fetch_content_objects(tagged_items, select_related_for=None):
+    """
+    Retrieves ``ContentType`` and content objects for the given list of
+    ``TaggedItems``, grouping the retrieval of content objects by model
+    type to reduce the number of queries executed.
+
+    This results in ``number_of_content_types + 1`` queries rather than
+    the ``number_of_tagged_items * 2`` queries you'd get by iterating
+    over the list and accessing each item's ``object`` attribute.
+
+    A ``select_related_for`` argument can be used to specify a list of
+    of model names (corresponding to the ``model`` field of a
+    ``ContentType``) for which ``select_related`` should be used when
+    retrieving model instances.
+    """
+    if select_related_for is None: select_related_for = []
+
+    # Group content object pks by their content type pks
+    objects = {}
+    for item in tagged_items:
+        objects.setdefault(item.content_type_id, []).append(item.object_id)
+
+    # Retrieve content types and content objects in bulk
+    content_types = ContentType._default_manager.in_bulk(objects.keys())
+    for content_type_pk, object_pks in objects.iteritems():
+        model = content_types[content_type_pk].model_class()
+        if content_types[content_type_pk].model in select_related_for:
+            objects[content_type_pk] = model._default_manager.select_related().in_bulk(object_pks)
+        else:
+            objects[content_type_pk] = model._default_manager.in_bulk(object_pks)
+
+    # Set content types and content objects in the appropriate cache
+    # attributes, so accessing the 'content_type' and 'object'
+    # attributes on each tagged item won't result in further database
+    # hits.
+    for item in tagged_items:
+        item._object_cache = objects[item.content_type_id][item.object_id]
+        item._content_type_cache = content_types[item.content_type_id]

File tagging/managers.py

+"""
+Custom managers for Django models registered with the tagging
+application.
+"""
+from django.contrib.contenttypes.models import ContentType
+from django.db import models
+
+from tagging.models import Tag, TaggedItem
+
+class ModelTagManager(models.Manager):
+    """
+    A manager for retrieving tags for a particular model.
+    """
+    def get_query_set(self):
+        ctype = ContentType.objects.get_for_model(self.model)
+        return Tag.objects.filter(
+            items__content_type__pk=ctype.pk).distinct()
+
+    def cloud(self, *args, **kwargs):
+        return Tag.objects.cloud_for_model(self.model, *args, **kwargs)
+
+    def related(self, tags, *args, **kwargs):
+        return Tag.objects.related_for_model(tags, self.model, *args, **kwargs)
+
+    def usage(self, *args, **kwargs):
+        return Tag.objects.usage_for_model(self.model, *args, **kwargs)
+
+class ModelTaggedItemManager(models.Manager):
+    """
+    A manager for retrieving model instances based on their tags.
+    """
+    def related_to(self, obj, queryset=None, num=None):
+        if queryset is None:
+            return TaggedItem.objects.get_related(obj, self.model, num=num)
+        else:
+            return TaggedItem.objects.get_related(obj, queryset, num=num)
+
+    def with_all(self, tags, queryset=None):
+        if queryset is None:
+            return TaggedItem.objects.get_by_model(self.model, tags)
+        else:
+            return TaggedItem.objects.get_by_model(queryset, tags)
+
+    def with_any(self, tags, queryset=None):
+        if queryset is None:
+            return TaggedItem.objects.get_union_by_model(self.model, tags)
+        else:
+            return TaggedItem.objects.get_union_by_model(queryset, tags)
+
+class TagDescriptor(object):
+    """
+    A descriptor which provides access to a ``ModelTagManager`` for
+    model classes and simple retrieval, updating and deletion of tags
+    for model instances.
+    """
+    def __get__(self, instance, owner):
+        if not instance:
+            tag_manager = ModelTagManager()
+            tag_manager.model = owner
+            return tag_manager
+        else:
+            return Tag.objects.get_for_object(instance)
+
+    def __set__(self, instance, value):
+        Tag.objects.update_tags(instance, value)
+
+    def __delete__(self, instance):
+        Tag.objects.update_tags(instance, None)

File tagging/models.py

+"""
+Models and managers for generic tagging.
+"""
+# Python 2.3 compatibility
+try:
+    set
+except NameError:
+    from sets import Set as set
+
+from django.contrib.contenttypes import generic
+from django.contrib.contenttypes.models import ContentType
+from django.db import connection, models
+from django.db.models.query import QuerySet
+from django.utils.translation import ugettext_lazy as _
+
+from tagging import settings
+from tagging.utils import calculate_cloud, get_tag_list, get_queryset_and_model, parse_tag_input
+from tagging.utils import LOGARITHMIC
+
+qn = connection.ops.quote_name
+
+############
+# Managers #
+############
+
+class TagManager(models.Manager):
+    def update_tags(self, obj, tag_names):
+        """
+        Update tags associated with an object.
+        """
+        ctype = ContentType.objects.get_for_model(obj)
+        current_tags = list(self.filter(items__content_type__pk=ctype.pk,
+                                        items__object_id=obj.pk))
+        updated_tag_names = parse_tag_input(tag_names)
+        if settings.FORCE_LOWERCASE_TAGS:
+            updated_tag_names = [t.lower() for t in updated_tag_names]
+
+        # Remove tags which no longer apply
+        tags_for_removal = [tag for tag in current_tags \
+                            if tag.name not in updated_tag_names]
+        if len(tags_for_removal):
+            TaggedItem._default_manager.filter(content_type__pk=ctype.pk,
+                                               object_id=obj.pk,
+                                               tag__in=tags_for_removal).delete()
+        # Add new tags
+        current_tag_names = [tag.name for tag in current_tags]
+        for tag_name in updated_tag_names:
+            if tag_name not in current_tag_names:
+                tag, created = self.get_or_create(name=tag_name)
+                TaggedItem._default_manager.create(tag=tag, object=obj)
+
+    def add_tag(self, obj, tag_name):
+        """
+        Associates the given object with a tag.
+        """
+        tag_names = parse_tag_input(tag_name)
+        if not len(tag_names):
+            raise AttributeError(_('No tags were given: "%s".') % tag_name)
+        if len(tag_names) > 1:
+            raise AttributeError(_('Multiple tags were given: "%s".') % tag_name)
+        tag_name = tag_names[0]
+        if settings.FORCE_LOWERCASE_TAGS:
+            tag_name = tag_name.lower()
+        tag, created = self.get_or_create(name=tag_name)
+        ctype = ContentType.objects.get_for_model(obj)
+        TaggedItem._default_manager.get_or_create(
+            tag=tag, content_type=ctype, object_id=obj.pk)
+
+    def get_for_object(self, obj):
+        """
+        Create a queryset matching all tags associated with the given
+        object.
+        """
+        ctype = ContentType.objects.get_for_model(obj)
+        return self.filter(items__content_type__pk=ctype.pk,
+                           items__object_id=obj.pk)
+
+    def _get_usage(self, model, counts=False, min_count=None, extra_joins=None, extra_criteria=None, params=None):
+        """
+        Perform the custom SQL query for ``usage_for_model`` and
+        ``usage_for_queryset``.
+        """
+        if min_count is not None: counts = True
+
+        model_table = qn(model._meta.db_table)
+        model_pk = '%s.%s' % (model_table, qn(model._meta.pk.column))
+        query = """
+        SELECT DISTINCT %(tag)s.id, %(tag)s.name%(count_sql)s
+        FROM
+            %(tag)s
+            INNER JOIN %(tagged_item)s
+                ON %(tag)s.id = %(tagged_item)s.tag_id
+            INNER JOIN %(model)s
+                ON %(tagged_item)s.object_id = %(model_pk)s
+            %%s
+        WHERE %(tagged_item)s.content_type_id = %(content_type_id)s
+            %%s
+        GROUP BY %(tag)s.id, %(tag)s.name
+        %%s
+        ORDER BY %(tag)s.name ASC""" % {
+            'tag': qn(self.model._meta.db_table),
+            'count_sql': counts and (', COUNT(%s)' % model_pk) or '',
+            'tagged_item': qn(TaggedItem._meta.db_table),
+            'model': model_table,
+            'model_pk': model_pk,
+            'content_type_id': ContentType.objects.get_for_model(model).pk,
+        }
+
+        min_count_sql = ''
+        if min_count is not None:
+            min_count_sql = 'HAVING COUNT(%s) >= %%s' % model_pk
+            params.append(min_count)
+
+        cursor = connection.cursor()
+        cursor.execute(query % (extra_joins, extra_criteria, min_count_sql), params)
+        tags = []
+        for row in cursor.fetchall():
+            t = self.model(*row[:2])
+            if counts:
+                t.count = row[2]
+            tags.append(t)
+        return tags
+
+    def usage_for_model(self, model, counts=False, min_count=None, filters=None):
+        """
+        Obtain a list of tags associated with instances of the given
+        Model class.
+
+        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``.
+
+        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 the given Model as the
+        ``filters`` argument.
+        """
+        if filters is None: filters = {}
+
+        queryset = model._default_manager.filter()
+        for f in filters.items():
+            queryset.query.add_filter(f)
+        usage = self.usage_for_queryset(queryset, counts, min_count)
+
+        return usage
+
+    def usage_for_queryset(self, queryset, counts=False, min_count=None):
+        """
+        Obtain 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``.
+        """
+
+        extra_joins = ' '.join(queryset.query.get_from_clause()[0][1:])
+        where, params = queryset.query.where.as_sql()
+        if where:
+            extra_criteria = 'AND %s' % where
+        else:
+            extra_criteria = ''
+        return self._get_usage(queryset.model, counts, min_count, extra_joins, extra_criteria, params)
+
+    def related_for_model(self, tags, model, counts=False, min_count=None):
+        """
+        Obtain 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``.
+        """
+        if min_count is not None: counts = True
+        tags = get_tag_list(tags)
+        tag_count = len(tags)
+        tagged_item_table = qn(TaggedItem._meta.db_table)
+        query = """
+        SELECT %(tag)s.id, %(tag)s.name%(count_sql)s
+        FROM %(tagged_item)s INNER JOIN %(tag)s ON %(tagged_item)s.tag_id = %(tag)s.id
+        WHERE %(tagged_item)s.content_type_id = %(content_type_id)s
+          AND %(tagged_item)s.object_id IN
+          (
+              SELECT %(tagged_item)s.object_id
+              FROM %(tagged_item)s, %(tag)s
+              WHERE %(tagged_item)s.content_type_id = %(content_type_id)s
+                AND %(tag)s.id = %(tagged_item)s.tag_id
+                AND %(tag)s.id IN (%(tag_id_placeholders)s)
+              GROUP BY %(tagged_item)s.object_id
+              HAVING COUNT(%(tagged_item)s.object_id) = %(tag_count)s
+          )
+          AND %(tag)s.id NOT IN (%(tag_id_placeholders)s)
+        GROUP BY %(tag)s.id, %(tag)s.name
+        %(min_count_sql)s
+        ORDER BY %(tag)s.name ASC""" % {
+            'tag': qn(self.model._meta.db_table),
+            'count_sql': counts and ', COUNT(%s.object_id)' % tagged_item_table or '',
+            'tagged_item': tagged_item_table,
+            'content_type_id': ContentType.objects.get_for_model(model).pk,
+            'tag_id_placeholders': ','.join(['%s'] * tag_count),
+            'tag_count': tag_count,
+            'min_count_sql': min_count is not None and ('HAVING COUNT(%s.object_id) >= %%s' % tagged_item_table) or '',
+        }
+
+        params = [tag.pk for tag in tags] * 2
+        if min_count is not None:
+            params.append(min_count)
+
+        cursor = connection.cursor()
+        cursor.execute(query, params)
+        related = []
+        for row in cursor.fetchall():
+            tag = self.model(*row[:2])
+            if counts is True:
+                tag.count = row[2]
+            related.append(tag)
+        return related
+
+    def cloud_for_model(self, model, steps=4, distribution=LOGARITHMIC,
+                        filters=None, min_count=None):
+        """
+        Obtain a list of tags associated with instances of the given
+        Model, giving each tag a ``count`` attribute indicating how
+        many times it has been used and a ``font_size`` attribute for
+        use in displaying a tag cloud.
+
+        ``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`` 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.
+        """
+        tags = list(self.usage_for_model(model, counts=True, filters=filters,
+                                         min_count=min_count))
+        return calculate_cloud(tags, steps, distribution)
+
+class TaggedItemManager(models.Manager):
+    """
+    FIXME There's currently no way to get the ``GROUP BY`` and ``HAVING``
+          SQL clauses required by many of this manager's methods into
+          Django's ORM.
+
+          For now, we manually execute a query to retrieve the PKs of
+          objects we're interested in, then use the ORM's ``__in``
+          lookup to return a ``QuerySet``.
+
+          Now that the queryset-refactor branch is in the trunk, this can be
+          tidied up significantly.
+    """
+    def get_by_model(self, queryset_or_model, tags):
+        """
+        Create a ``QuerySet`` containing instances of the specified
+        model associated with a given tag or list of tags.
+        """
+        tags = get_tag_list(tags)
+        tag_count = len(tags)
+        if tag_count == 0:
+            # No existing tags were given
+            queryset, model = get_queryset_and_model(queryset_or_model)
+            return model._default_manager.none()
+        elif tag_count == 1:
+            # Optimisation for single tag - fall through to the simpler
+            # query below.
+            tag = tags[0]
+        else:
+            return self.get_intersection_by_model(queryset_or_model, tags)
+
+        queryset, model = get_queryset_and_model(queryset_or_model)
+        content_type = ContentType.objects.get_for_model(model)
+        opts = self.model._meta
+        tagged_item_table = qn(opts.db_table)
+        return queryset.extra(
+            tables=[opts.db_table],
+            where=[
+                '%s.content_type_id = %%s' % tagged_item_table,
+                '%s.tag_id = %%s' % tagged_item_table,
+                '%s.%s = %s.object_id' % (qn(model._meta.db_table),
+                                          qn(model._meta.pk.column),
+                                          tagged_item_table)
+            ],
+            params=[content_type.pk, tag.pk],
+        )
+
+    def get_intersection_by_model(self, queryset_or_model, tags):
+        """
+        Create a ``QuerySet`` containing instances of the specified
+        model associated with *all* of the given list of tags.
+        """
+        tags = get_tag_list(tags)
+        tag_count = len(tags)
+        queryset, model = get_queryset_and_model(queryset_or_model)
+
+        if not tag_count:
+            return model._default_manager.none()
+
+        model_table = qn(model._meta.db_table)
+        # This query selects the ids of all objects which have all the
+        # given tags.
+        query = """
+        SELECT %(model_pk)s
+        FROM %(model)s, %(tagged_item)s
+        WHERE %(tagged_item)s.content_type_id = %(content_type_id)s
+          AND %(tagged_item)s.tag_id IN (%(tag_id_placeholders)s)
+          AND %(model_pk)s = %(tagged_item)s.object_id
+        GROUP BY %(model_pk)s
+        HAVING COUNT(%(model_pk)s) = %(tag_count)s""" % {
+            'model_pk': '%s.%s' % (model_table, qn(model._meta.pk.column)),
+            'model': model_table,
+            'tagged_item': qn(self.model._meta.db_table),
+            'content_type_id': ContentType.objects.get_for_model(model).pk,
+            'tag_id_placeholders': ','.join(['%s'] * tag_count),
+            'tag_count': tag_count,
+        }
+
+        cursor = connection.cursor()
+        cursor.execute(query, [tag.pk for tag in tags])
+        object_ids = [row[0] for row in cursor.fetchall()]
+        if len(object_ids) > 0:
+            return queryset.filter(pk__in=object_ids)
+        else:
+            return model._default_manager.none()
+
+    def get_union_by_model(self, queryset_or_model, tags):
+        """
+        Create a ``QuerySet`` containing instances of the specified
+        model associated with *any* of the given list of tags.
+        """
+        tags = get_tag_list(tags)
+        tag_count = len(tags)
+        queryset, model = get_queryset_and_model(queryset_or_model)
+
+        if not tag_count:
+            return model._default_manager.none()
+
+        model_table = qn(model._meta.db_table)
+        # This query selects the ids of all objects which have any of
+        # the given tags.
+        query = """
+        SELECT %(model_pk)s
+        FROM %(model)s, %(tagged_item)s
+        WHERE %(tagged_item)s.content_type_id = %(content_type_id)s
+          AND %(tagged_item)s.tag_id IN (%(tag_id_placeholders)s)
+          AND %(model_pk)s = %(tagged_item)s.object_id
+        GROUP BY %(model_pk)s""" % {
+            'model_pk': '%s.%s' % (model_table, qn(model._meta.pk.column)),
+            'model': model_table,
+            'tagged_item': qn(self.model._meta.db_table),
+            'content_type_id': ContentType.objects.get_for_model(model).pk,
+            'tag_id_placeholders': ','.join(['%s'] * tag_count),
+        }
+
+        cursor = connection.cursor()
+        cursor.execute(query, [tag.pk for tag in tags])
+        object_ids = [row[0] for row in cursor.fetchall()]
+        if len(object_ids) > 0:
+            return queryset.filter(pk__in=object_ids)
+        else:
+            return model._default_manager.none()
+
+    def get_related(self, obj, queryset_or_model, num=None):
+        """
+        Retrieve a list of instances of the specified 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.
+        """
+        queryset, model = get_queryset_and_model(queryset_or_model)
+        model_table = qn(model._meta.db_table)
+        content_type = ContentType.objects.get_for_model(obj)
+        related_content_type = ContentType.objects.get_for_model(model)
+        query = """
+        SELECT %(model_pk)s, COUNT(related_tagged_item.object_id) AS %(count)s
+        FROM %(model)s, %(tagged_item)s, %(tag)s, %(tagged_item)s related_tagged_item
+        WHERE %(tagged_item)s.object_id = %%s
+          AND %(tagged_item)s.content_type_id = %(content_type_id)s
+          AND %(tag)s.id = %(tagged_item)s.tag_id
+          AND related_tagged_item.content_type_id = %(related_content_type_id)s
+          AND related_tagged_item.tag_id = %(tagged_item)s.tag_id
+          AND %(model_pk)s = related_tagged_item.object_id"""
+        if content_type.pk == related_content_type.pk:
+            # Exclude the given instance itself if determining related
+            # instances for the same model.
+            query += """
+          AND related_tagged_item.object_id != %(tagged_item)s.object_id"""
+        query += """
+        GROUP BY %(model_pk)s
+        ORDER BY %(count)s DESC
+        %(limit_offset)s"""
+        query = query % {
+            'model_pk': '%s.%s' % (model_table, qn(model._meta.pk.column)),
+            'count': qn('count'),
+            'model': model_table,
+            'tagged_item': qn(self.model._meta.db_table),
+            'tag': qn(self.model._meta.get_field('tag').rel.to._meta.db_table),
+            'content_type_id': content_type.pk,
+            'related_content_type_id': related_content_type.pk,
+            # Hardcoding this for now just to get tests working again - this
+            # should now be handled by the query object.
+            'limit_offset': num is not None and 'LIMIT %s' or '',
+        }
+
+        cursor = connection.cursor()
+        params = [obj.pk]
+        if num is not None:
+            params.append(num)
+        cursor.execute(query, params)
+        object_ids = [row[0] for row in cursor.fetchall()]
+        if len(object_ids) > 0:
+            # Use in_bulk here instead of an id__in lookup, because id__in would
+            # clobber the ordering.
+            object_dict = queryset.in_bulk(object_ids)
+            return [object_dict[object_id] for object_id in object_ids \
+                    if object_id in object_dict]
+        else:
+            return []
+
+##########
+# Models #
+##########
+
+class Tag(models.Model):
+    """
+    A tag.
+    """
+    name = models.CharField(_('name'), max_length=50, unique=True, db_index=True)
+
+    objects = TagManager()
+
+    class Meta:
+        ordering = ('name',)
+        verbose_name = _('tag')
+        verbose_name_plural = _('tags')
+
+    def __unicode__(self):
+        return self.name
+
+class TaggedItem(models.Model):
+    """
+    Holds the relationship between a tag and the item being tagged.
+    """
+    tag          = models.ForeignKey(Tag, verbose_name=_('tag'), related_name='items')
+    content_type = models.ForeignKey(ContentType, verbose_name=_('content type'))
+    object_id    = models.PositiveIntegerField(_('object id'), db_index=True)
+    object       = generic.GenericForeignKey('content_type', 'object_id')
+
+    objects = TaggedItemManager()
+
+    class Meta:
+        # Enforce unique tag association per object
+        unique_together = (('tag', 'content_type', 'object_id'),)
+        verbose_name = _('tagged item')
+        verbose_name_plural = _('tagged items')
+
+    def __unicode__(self):
+        return u'%s [%s]' % (self.object, self.tag)

File tagging/settings.py

+"""
+Convenience module for access of custom tagging application settings,
+which enforces default settings when the main settings module does not
+contain the appropriate settings.
+"""
+from django.conf import settings
+
+# The maximum length of a tag's name.
+MAX_TAG_LENGTH = getattr(settings, 'MAX_TAG_LENGTH', 50)
+
+# Whether to force all tags to lowercase before they are saved to the
+# database.
+FORCE_LOWERCASE_TAGS = getattr(settings, 'FORCE_LOWERCASE_TAGS', False)

File tagging/templatetags/__init__.py

Empty file added.

File tagging/templatetags/tagging_tags.py

+from django.db.models import get_model
+from django.template import Library, Node, TemplateSyntaxError, Variable, resolve_variable
+from django.utils.translation import ugettext as _
+
+from tagging.models import Tag, TaggedItem
+from tagging.utils import LINEAR, LOGARITHMIC
+
+register = Library()
+
+class TagsForModelNode(Node):
+    def __init__(self, model, context_var, counts):
+        self.model = model
+        self.context_var = context_var
+        self.counts = counts
+
+    def render(self, context):
+        model = get_model(*self.model.split('.'))
+        if model is None:
+            raise TemplateSyntaxError(_('tags_for_model tag was given an invalid model: %s') % self.model)
+        context[self.context_var] = Tag.objects.usage_for_model(model, counts=self.counts)
+        return ''
+
+class TagCloudForModelNode(Node):
+    def __init__(self, model, context_var, **kwargs):
+        self.model = model
+        self.context_var = context_var
+        self.kwargs = kwargs
+
+    def render(self, context):
+        model = get_model(*self.model.split('.'))
+        if model is None:
+            raise TemplateSyntaxError(_('tag_cloud_for_model tag was given an invalid model: %s') % self.model)
+        context[self.context_var] = \
+            Tag.objects.cloud_for_model(model, **self.kwargs)
+        return ''
+
+class TagsForObjectNode(Node):
+    def __init__(self, obj, context_var):
+        self.obj = Variable(obj)
+        self.context_var = context_var
+
+    def render(self, context):
+        context[self.context_var] = \
+            Tag.objects.get_for_object(self.obj.resolve(context))
+        return ''
+
+class TaggedObjectsNode(Node):
+    def __init__(self, tag, model, context_var):
+        self.tag = Variable(tag)
+        self.context_var = context_var
+        self.model = model
+
+    def render(self, context):
+        model = get_model(*self.model.split('.'))
+        if model is None:
+            raise TemplateSyntaxError(_('tagged_objects tag was given an invalid model: %s') % self.model)
+        context[self.context_var] = \
+            TaggedItem.objects.get_by_model(model, self.tag.resolve(context))
+        return ''
+
+def do_tags_for_model(parser, token):
+    """
+    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 %}
+
+    """
+    bits = token.contents.split()
+    len_bits = len(bits)
+    if len_bits not in (4, 6):
+        raise TemplateSyntaxError(_('%s tag requires either three or five arguments') % bits[0])
+    if bits[2] != 'as':
+        raise TemplateSyntaxError(_("second argument to %s tag must be 'as'") % bits[0])
+    if len_bits == 6:
+        if bits[4] != 'with':
+            raise TemplateSyntaxError(_("if given, fourth argument to %s tag must be 'with'") % bits[0])
+        if bits[5] != 'counts':
+            raise TemplateSyntaxError(_("if given, fifth argument to %s tag must be 'counts'") % bits[0])
+    if len_bits == 4:
+        return TagsForModelNode(bits[1], bits[3], counts=False)
+    else:
+        return TagsForModelNode(bits[1], bits[3], counts=True)
+
+def do_tag_cloud_for_model(parser, token):
+    """
+    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