diff options
33 files changed, 3656 insertions, 0 deletions
diff --git a/._CHANGELOG.txt b/._CHANGELOG.txt Binary files differnew file mode 100644 index 0000000..9bf97be --- /dev/null +++ b/._CHANGELOG.txt diff --git a/._MANIFEST.in b/._MANIFEST.in Binary files differnew file mode 100644 index 0000000..8af97db --- /dev/null +++ b/._MANIFEST.in diff --git a/._README.txt b/._README.txt Binary files differnew file mode 100644 index 0000000..8645f1c --- /dev/null +++ b/._README.txt diff --git a/CHANGELOG.txt b/CHANGELOG.txt new file mode 100644 index 0000000..4303c2a --- /dev/null +++ b/CHANGELOG.txt @@ -0,0 +1,111 @@ +======================== +Django Tagging Changelog +======================== + +Version 0.3.1, Not released: +---------------------------- + +* Fixed Django 1.2 support (did not add anything new) + +Version 0.3.0, 22nd August 2009: +-------------------------------- + +* Fixes for Django 1.0 compatibility. + +* 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. diff --git a/INSTALL.txt b/INSTALL.txt new file mode 100644 index 0000000..9f13a3a --- /dev/null +++ b/INSTALL.txt @@ -0,0 +1,14 @@ +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 +1.0 or later. You can obtain Python from http://www.python.org/ and +Django from http://www.djangoproject.com/.
\ No newline at end of file diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..1654536 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,55 @@ +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.
\ No newline at end of file diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..618270b --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,7 @@ +include CHANGELOG.txt +include INSTALL.txt +include LICENSE.txt +include MANIFEST.in +include README.txt +recursive-include docs *.txt +recursive-include tagging/tests *.txt diff --git a/PKG-INFO b/PKG-INFO new file mode 100644 index 0000000..2d1e79c --- /dev/null +++ b/PKG-INFO @@ -0,0 +1,18 @@ +Metadata-Version: 1.0 +Name: django-tagging +Version: 0.3.1 +Summary: Generic tagging application for Django +Home-page: http://code.google.com/p/django-tagging/ +Author: Jonathan Buchanan +Author-email: jonathan.buchanan@gmail.com +License: UNKNOWN +Description: UNKNOWN +Platform: UNKNOWN +Classifier: Development Status :: 4 - Beta +Classifier: Environment :: Web Environment +Classifier: Framework :: Django +Classifier: Intended Audience :: Developers +Classifier: License :: OSI Approved :: BSD License +Classifier: Operating System :: OS Independent +Classifier: Programming Language :: Python +Classifier: Topic :: Utilities diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..acb2d47 --- /dev/null +++ b/README.txt @@ -0,0 +1,10 @@ +============== +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.
\ No newline at end of file diff --git a/docs/._overview.txt b/docs/._overview.txt Binary files differnew file mode 100644 index 0000000..c4db396 --- /dev/null +++ b/docs/._overview.txt diff --git a/docs/overview.txt b/docs/overview.txt new file mode 100644 index 0000000..feb08c9 --- /dev/null +++ b/docs/overview.txt @@ -0,0 +1,904 @@ +============== +Django Tagging +============== + +A generic tagging application for `Django`_ projects, which allows +association of a number of tags with any Django model instance and makes +retrieval of tags simple. + +.. _`Django`: http://www.djangoproject.com + +.. contents:: + :depth: 3 + + +Installation +============ + +Installing an official release +------------------------------ + +Official releases are made available from +http://code.google.com/p/django-tagging/ + +Source distribution +~~~~~~~~~~~~~~~~~~~ + +Download the .zip distribution file and unpack it. Inside is a script +named ``setup.py``. Enter this command:: + + python setup.py install + +...and the package will install automatically. + +Windows installer +~~~~~~~~~~~~~~~~~ + +A Windows installer is also made available - download the .exe +distribution file and launch it to install the application. + +An uninstaller will also be created, accessible through Add/Remove +Programs in your Control Panel. + +Installing the development version +---------------------------------- + +Alternatively, if you'd like to update Django Tagging occasionally to pick +up the latest bug fixes and enhancements before they make it into an +official release, perform a `Subversion`_ checkout instead. The following +command will check the application's development branch out to an +``tagging-trunk`` directory:: + + svn checkout http://django-tagging.googlecode.com/svn/trunk/ tagging-trunk + +Add the resulting folder to your `PYTHONPATH`_ or symlink (`junction`_, +if you're on Windows) the ``tagging`` directory inside it into a +directory which is on your PYTHONPATH, such as your Python +installation's ``site-packages`` directory. + +You can verify that the application is available on your PYTHONPATH by +opening a Python interpreter and entering the following commands:: + + >>> import tagging + >>> tagging.VERSION + (0, 3, 'pre') + +When you want to update your copy of the Django Tagging source code, run +the command ``svn update`` from within the ``tagging-trunk`` directory. + +.. caution:: + + The development version may contain bugs which are not present in the + release version and introduce backwards-incompatible changes. + + If you're tracking trunk, keep an eye on the `CHANGELOG`_ and the + `backwards-incompatible changes wiki page`_ before you update your + copy of the source code. + +.. _`Subversion`: http://subversion.tigris.org +.. _`PYTHONPATH`: http://www.python.org/doc/2.5.2/tut/node8.html#SECTION008120000000000000000 +.. _`junction`: http://www.microsoft.com/technet/sysinternals/FileAndDisk/Junction.mspx +.. _`CHANGELOG`: http://django-tagging.googlecode.com/svn/trunk/CHANGELOG.txt +.. _`backwards-incompatible changes wiki page`: http://code.google.com/p/django-tagging/wiki/BackwardsIncompatibleChanges + +Using Django Tagging in your applications +----------------------------------------- + +Once you've installed Django Tagging and want to use it in your Django +applications, do the following: + + 1. Put ``'tagging'`` in your ``INSTALLED_APPS`` setting. + 2. Run the command ``manage.py syncdb``. + +The ``syncdb`` command creates the necessary database tables and +creates permission objects for all installed apps that need them. + +That's it! + + +Settings +======== + +Some of the application's behaviour can be configured by adding the +appropriate settings to your project's settings file. + +The following settings are available: + +FORCE_LOWERCASE_TAGS +-------------------- + +Default: ``False`` + +A boolean that turns on/off forcing of all tag names to lowercase before +they are saved to the database. + +MAX_TAG_LENGTH +-------------- + +Default: ``50`` + +An integer which specifies the maximum length which any tag is allowed +to have. This is used for validation in the ``django.contrib.admin`` +application and in any forms automatically generated using ``ModelForm``. + + +Registering your models +======================= + +Your Django models can be registered with the tagging application to +access some additional tagging-related features. + +.. note:: + + You don't *have* to register your models in order to use them with + the tagging application - many of the features added by registration + are just convenience wrappers around the tagging API provided by the + ``Tag`` and ``TaggedItem`` models and their managers, as documented + further below. + +The ``register`` function +------------------------- + +To register a model, import the ``tagging`` module and call its +``register`` function, like so:: + + from django.db import models + + import tagging + + class Widget(models.Model): + name = models.CharField(max_length=50) + + tagging.register(Widget) + +The following argument is required: + +``model`` + The model class to be registered. + + An exception will be raised if you attempt to register the same class + more than once. + +The following arguments are optional, with some recommended defaults - +take care to specify different attribute names if the defaults clash +with your model class' definition: + +``tag_descriptor_attr`` + The name of an attribute in the model class which will hold a tag + descriptor for the model. Default: ``'tags'`` + + See `TagDescriptor`_ below for details about the use of this + descriptor. + +``tagged_item_manger_attr`` + The name of an attribute in the model class which will hold a custom + manager for accessing tagged items for the model. Default: + ``'tagged'``. + + See `ModelTaggedItemManager`_ below for details about the use of this + manager. + +``TagDescriptor`` +----------------- + +When accessed through the model class itself, this descriptor will return +a ``ModelTagManager`` for the model. See `ModelTagManager`_ below for +more details about its use. + +When accessed through a model instance, this descriptor provides a handy +means of retrieving, updating and deleting the instance's tags. For +example:: + + >>> widget = Widget.objects.create(name='Testing descriptor') + >>> widget.tags + [] + >>> widget.tags = 'toast, melted cheese, butter' + >>> widget.tags + [<Tag: butter>, <Tag: melted cheese>, <Tag: toast>] + >>> del widget.tags + >>> widget.tags + [] + +``ModelTagManager`` +------------------- + +A manager for retrieving tags used by a particular model. + +Defines the following methods: + +* ``get_query_set()`` -- as this method is redefined, any ``QuerySets`` + created by this model will be initially restricted to contain the + distinct tags used by all the model's instances. + +* ``cloud(*args, **kwargs)`` -- creates a list of tags used by the + model's instances, with ``count`` and ``font_size`` attributes set for + use in displaying a tag cloud. + + See the documentation on ``Tag``'s manager's `cloud_for_model method`_ + for information on additional arguments which can be given. + +* ``related(self, tags, *args, **kwargs)`` -- creates a list of tags + used by the model's instances, which are also used by all instance + which have the given ``tags``. + + See the documentation on ``Tag``'s manager's + `related_for_model method`_ for information on additional arguments + which can be given. + +* ``usage(self, *args, **kwargs))`` -- creates a list of tags used by + the model's instances, with optional usages counts, restriction based + on usage counts and restriction of the model instances from which + usage and counts are determined. + + See the documentation on ``Tag``'s manager's `usage_for_model method`_ + for information on additional arguments which can be given. + +Example usage:: + + # Create a ``QuerySet`` of tags used by Widget instances + Widget.tags.all() + + # Retrieve a list of tags used by Widget instances with usage counts + Widget.tags.usage(counts=True) + + # Retrieve tags used by instances of WIdget which are also tagged with + # 'cheese' and 'toast' + Widget.tags.related(['cheese', 'toast'], counts=True, min_count=3) + +``ModelTaggedItemManager`` +-------------------------- + +A manager for retrieving model instance for a particular model, based on +their tags. + +* ``related_to(obj, queryset=None, num=None)`` -- creates a list + of model instances which are related to ``obj``, based on its tags. If + a ``queryset`` argument is provided, it will be used to restrict the + resulting list of model instances. + + If ``num`` is given, a maximum of ``num`` instances will be returned. + +* ``with_all(tags, queryset=None)`` -- creates a ``QuerySet`` containing + model instances which are tagged with *all* the given tags. If a + ``queryset`` argument is provided, it will be used as the basis for + the resulting ``QuerySet``. + +* ``with_any(tags, queryset=None)`` -- creates a ``QuerySet`` containing model + instances which are tagged with *any* the given tags. If a ``queryset`` + argument is provided, it will be used as the basis for the resulting + ``QuerySet``. + + +Tags +==== + +Tags are represented by the ``Tag`` model, which lives in the +``tagging.models`` module. + +API reference +------------- + +Fields +~~~~~~ + +``Tag`` objects have the following fields: + +* ``name`` -- The name of the tag. This is a unique value. + +Manager functions +~~~~~~~~~~~~~~~~~ + +The ``Tag`` model has a custom manager which has the following helper +methods: + +* ``update_tags(obj, tag_names)`` -- updates tags associated with an + object. + + ``tag_names`` is a string containing tag names with which ``obj`` + should be tagged. + + If ``tag_names`` is ``None`` or ``''``, the object's tags will be + cleared. + +* ``add_tag(obj, tag_name)`` -- associates a tag with an an object. + + ``tag_name`` is a string containing a tag name with which ``obj`` + should be tagged. + +* ``get_for_object(obj)`` -- returns a ``QuerySet`` containing all + ``Tag`` objects associated with ``obj``. + +.. _`usage_for_model method`: + +* ``usage_for_model(model, counts=False, min_count=None, filters=None)`` + -- returns a list of ``Tag`` objects associated with instances of + ``model``. + + If ``counts`` is ``True``, a ``count`` attribute will be added to each + tag, indicating how many times it has been associated with instances + of ``model``. + + If ``min_count`` is given, only tags which have a ``count`` greater + than or equal to ``min_count`` will be returned. Passing a value for + ``min_count`` implies ``counts=True``. + + To limit the tags (and counts, if specified) returned to those used by + a subset of the model's instances, pass a dictionary of field lookups + to be applied to ``model`` as the ``filters`` argument. + +.. _`related_for_model method`: + +* ``related_for_model(tags, Model, counts=False, min_count=None)`` + -- returns a list of tags related to a given list of tags - that is, + other tags used by items which have all the given tags. + + If ``counts`` is ``True``, a ``count`` attribute will be added to each + tag, indicating the number of items which have it in addition to the + given list of tags. + + If ``min_count`` is given, only tags which have a ``count`` greater + than or equal to ``min_count`` will be returned. Passing a value for + ``min_count`` implies ``counts=True``. + +.. _`cloud_for_model method`: + +* ``cloud_for_model(Model, steps=4, distribution=LOGARITHMIC, + filters=None, min_count=None)`` -- returns a list of the distinct + ``Tag`` objects associated with instances of ``Model``, each having a + ``count`` attribute as above and an additional ``font_size`` + attribute, for use in creation of a tag cloud (a type of weighted + list). + + ``steps`` defines the number of font sizes available - ``font_size`` + may be an integer between ``1`` and ``steps``, inclusive. + + ``distribution`` defines the type of font size distribution algorithm + which will be used - logarithmic or linear. It must be either + ``tagging.utils.LOGARITHMIC`` or ``tagging.utils.LINEAR``. + + To limit the tags displayed in the cloud to those associated with a + subset of the Model's instances, pass a dictionary of field lookups to + be applied to the given Model as the ``filters`` argument. + + To limit the tags displayed in the cloud to those with a ``count`` + greater than or equal to ``min_count``, pass a value for the + ``min_count`` argument. + +* ``usage_for_queryset(queryset, counts=False, min_count=None)`` -- + Obtains a list of tags associated with instances of a model contained + in the given queryset. + + If ``counts`` is True, a ``count`` attribute will be added to each tag, + indicating how many times it has been used against the Model class in + question. + + If ``min_count`` is given, only tags which have a ``count`` greater + than or equal to ``min_count`` will be returned. + + Passing a value for ``min_count`` implies ``counts=True``. + +Basic usage +----------- + +Tagging objects and retrieving an object's tags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Objects may be tagged using the ``update_tags`` helper function:: + + >>> from shop.apps.products.models import Widget + >>> from tagging.models import Tag + >>> widget = Widget.objects.get(pk=1) + >>> Tag.objects.update_tags(widget, 'house thing') + +Retrieve tags for an object using the ``get_for_object`` helper +function:: + + >>> Tag.objects.get_for_object(widget) + [<Tag: house>, <Tag: thing>] + +Tags are created, associated and unassociated accordingly when you use +``update_tags`` and ``add_tag``:: + + >>> Tag.objects.update_tags(widget, 'house monkey') + >>> Tag.objects.get_for_object(widget) + [<Tag: house>, <Tag: monkey>] + >>> Tag.objects.add_tag(widget, 'tiles') + >>> Tag.objects.get_for_object(widget) + [<Tag: house>, <Tag: monkey>, <Tag: tiles>] + +Clear an object's tags by passing ``None`` or ``''`` to +``update_tags``:: + + >>> Tag.objects.update_tags(widget, None) + >>> Tag.objects.get_for_object(widget) + [] + +Retrieving tags used by a particular model +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To retrieve all tags used for a particular model, use the +``get_for_model`` helper function:: + + >>> widget1 = Widget.objects.get(pk=1) + >>> Tag.objects.update_tags(widget1, 'house thing') + >>> widget2 = Widget.objects.get(pk=2) + >>> Tag.objects.update_tags(widget2, 'cheese toast house') + >>> Tag.objects.usage_for_model(Widget) + [<Tag: cheese>, <Tag: house>, <Tag: thing>, <Tag: toast>] + +To get a count of how many times each tag was used for a particular +model, pass in ``True`` for the ``counts`` argument:: + + >>> tags = Tag.objects.usage_for_model(Widget, counts=True) + >>> [(tag.name, tag.count) for tag in tags] + [('cheese', 1), ('house', 2), ('thing', 1), ('toast', 1)] + +To get counts and limit the tags returned to those with counts above a +certain size, pass in a ``min_count`` argument:: + + >>> tags = Tag.objects.usage_for_model(Widget, min_count=2) + >>> [(tag.name, tag.count) for tag in tags] + [('house', 2)] + +You can also specify a dictionary of `field lookups`_ to be used to +restrict the tags and counts returned based on a subset of the +model's instances. For example, the following would retrieve all tags +used on Widgets created by a user named Alan which have a size +greater than 99:: + + >>> Tag.objects.usage_for_model(Widget, filters=dict(size__gt=99, user__username='Alan')) + +.. _`field lookups`: http://docs.djangoproject.com/en/dev/topics/db/queries/#field-lookups + +The ``usage_for_queryset`` method allows you to pass a pre-filtered +queryset to be used when determining tag usage:: + + >>> Tag.objects.usage_for_queryset(Widget.objects.filter(size__gt=99, user__username='Alan')) + +Tag input +--------- + +Tag input from users is treated as follows: + +* If the input doesn't contain any commas or double quotes, it is simply + treated as a space-delimited list of tag names. + +* If the input does contain either of these characters, we parse the + input like so: + + * Groups of characters which appear between double quotes take + precedence as multi-word tags (so double quoted tag names may + contain commas). An unclosed double quote will be ignored. + + * For the remaining input, if there are any unquoted commas in the + input, the remainder will be treated as comma-delimited. Otherwise, + it will be treated as space-delimited. + +Examples: + +====================== ======================================= ================================================ +Tag input string Resulting tags Notes +====================== ======================================= ================================================ +apple ball cat [``apple``], [``ball``], [``cat``] No commas, so space delimited +apple, ball cat [``apple``], [``ball cat``] Comma present, so comma delimited +"apple, ball" cat dog [``apple, ball``], [``cat``], [``dog``] All commas are quoted, so space delimited +"apple, ball", cat dog [``apple, ball``], [``cat dog``] Contains an unquoted comma, so comma delimited +apple "ball cat" dog [``apple``], [``ball cat``], [``dog``] No commas, so space delimited +"apple" "ball dog [``apple``], [``ball``], [``dog``] Unclosed double quote is ignored +====================== ======================================= ================================================ + + +Tagged items +============ + +The relationship between a ``Tag`` and an object is represented by +the ``TaggedItem`` model, which lives in the ``tagging.models`` +module. + +API reference +------------- + +Fields +~~~~~~ + +``TaggedItem`` objects have the following fields: + +* ``tag`` -- The ``Tag`` an object is associated with. +* ``content_type`` -- The ``ContentType`` of the associated model + instance. +* ``object_id`` -- The id of the associated object. +* ``object`` -- The associated object itself, accessible via the + Generic Relations API. + +Manager functions +~~~~~~~~~~~~~~~~~ + +The ``TaggedItem`` model has a custom manager which has the following +helper methods, which accept either a ``QuerySet`` or a ``Model`` +class as one of their arguments. To restrict the objects which are +returned, pass in a filtered ``QuerySet`` for this argument: + +* ``get_by_model(queryset_or_model, tag)`` -- creates a ``QuerySet`` + containing instances of the specififed model which are tagged with + the given tag or tags. + +* ``get_intersection_by_model(queryset_or_model, tags)`` -- creates a + ``QuerySet`` containing instances of the specified model which are + tagged with every tag in a list of tags. + + ``get_by_model`` will call this function behind the scenes when you + 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 %} diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..0670dfe --- /dev/null +++ b/setup.py @@ -0,0 +1,70 @@ +""" +Based entirely on Django's own ``setup.py``. +""" +import os +from distutils.command.install import INSTALL_SCHEMES +from distutils.core import setup + +import tagging + + + +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]]) + + +setup( + name = 'django-tagging', + version = tagging.get_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'], +) diff --git a/tagging/._models.py b/tagging/._models.py Binary files differnew file mode 100644 index 0000000..bdd7231 --- /dev/null +++ b/tagging/._models.py diff --git a/tagging/._settings.py b/tagging/._settings.py Binary files differnew file mode 100644 index 0000000..3c4ee38 --- /dev/null +++ b/tagging/._settings.py diff --git a/tagging/__init__.py b/tagging/__init__.py new file mode 100644 index 0000000..03d6c03 --- /dev/null +++ b/tagging/__init__.py @@ -0,0 +1,62 @@ +VERSION = (0, 3, 1, "final", 0) + + + +def get_version(): + if VERSION[3] == "final": + return "%s.%s.%s" % (VERSION[0], VERSION[1], VERSION[2]) + elif VERSION[3] == "dev": + if VERSION[2] == 0: + return "%s.%s.%s%s" % (VERSION[0], VERSION[1], VERSION[3], VERSION[4]) + return "%s.%s.%s.%s%s" % (VERSION[0], VERSION[1], VERSION[2], VERSION[3], VERSION[4]) + else: + return "%s.%s.%s%s" % (VERSION[0], VERSION[1], VERSION[2], VERSION[3]) + + +__version__ = get_version() + + +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. + """ + + from tagging.managers import ModelTaggedItemManager, TagDescriptor + + if model in registry: + raise AlreadyRegistered("The model '%s' has already been " + "registered." % model._meta.object_name) + if hasattr(model, tag_descriptor_attr): + raise AttributeError("'%s' already has an attribute '%s'. You must " + "provide a custom tag_descriptor_attr to register." % ( + model._meta.object_name, + tag_descriptor_attr, + ) + ) + if hasattr(model, tagged_item_manager_attr): + raise AttributeError("'%s' already has an attribute '%s'. You must " + "provide a custom tagged_item_manager_attr to register." % ( + model._meta.object_name, + tagged_item_manager_attr, + ) + ) + + # Add tag descriptor + setattr(model, tag_descriptor_attr, TagDescriptor()) + + # Add custom manager + ModelTaggedItemManager().contribute_to_class(model, tagged_item_manager_attr) + + # Finally register in registry + registry.append(model) diff --git a/tagging/admin.py b/tagging/admin.py new file mode 100644 index 0000000..bec3922 --- /dev/null +++ b/tagging/admin.py @@ -0,0 +1,13 @@ +from django.contrib import admin +from tagging.models import Tag, TaggedItem +from tagging.forms import TagAdminForm + +class TagAdmin(admin.ModelAdmin): + form = TagAdminForm + +admin.site.register(TaggedItem) +admin.site.register(Tag, TagAdmin) + + + + diff --git a/tagging/fields.py b/tagging/fields.py new file mode 100644 index 0000000..f52daff --- /dev/null +++ b/tagging/fields.py @@ -0,0 +1,107 @@ +""" +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) diff --git a/tagging/forms.py b/tagging/forms.py new file mode 100644 index 0000000..a2d9fd9 --- /dev/null +++ b/tagging/forms.py @@ -0,0 +1,40 @@ +""" +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 TagAdminForm(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 forms.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 diff --git a/tagging/generic.py b/tagging/generic.py new file mode 100644 index 0000000..75d1b8e --- /dev/null +++ b/tagging/generic.py @@ -0,0 +1,40 @@ +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] diff --git a/tagging/managers.py b/tagging/managers.py new file mode 100644 index 0000000..02cd1c2 --- /dev/null +++ b/tagging/managers.py @@ -0,0 +1,68 @@ +""" +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) diff --git a/tagging/models.py b/tagging/models.py new file mode 100644 index 0000000..860cf81 --- /dev/null +++ b/tagging/models.py @@ -0,0 +1,490 @@ +""" +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``. + """ + + if getattr(queryset.query, 'get_compiler', None): + # Django 1.2+ + compiler = queryset.query.get_compiler(using='default') + extra_joins = ' '.join(compiler.get_from_clause()[0][1:]) + where, params = queryset.query.where.as_sql( + compiler.quote_name_unless_alias, compiler.connection + ) + else: + # Django pre-1.2 + 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) diff --git a/tagging/settings.py b/tagging/settings.py new file mode 100644 index 0000000..1d6224c --- /dev/null +++ b/tagging/settings.py @@ -0,0 +1,13 @@ +""" +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) diff --git a/tagging/templatetags/__init__.py b/tagging/templatetags/__init__.py new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tagging/templatetags/__init__.py diff --git a/tagging/templatetags/tagging_tags.py b/tagging/templatetags/tagging_tags.py new file mode 100644 index 0000000..11d31cc --- /dev/null +++ b/tagging/templatetags/tagging_tags.py @@ -0,0 +1,231 @@ +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 + 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 %} + + """ + bits = token.contents.split() + len_bits = len(bits) + if len_bits != 4 and len_bits not in range(6, 9): + raise TemplateSyntaxError(_('%s tag requires either three or between five and seven arguments') % bits[0]) + if bits[2] != 'as': + raise TemplateSyntaxError(_("second argument to %s tag must be 'as'") % bits[0]) + kwargs = {} + if len_bits > 5: + if bits[4] != 'with': + raise TemplateSyntaxError(_("if given, fourth argument to %s tag must be 'with'") % bits[0]) + for i in range(5, len_bits): + try: + name, value = bits[i].split('=') + if name == 'steps' or name == 'min_count': + try: + kwargs[str(name)] = int(value) + except ValueError: + raise TemplateSyntaxError(_("%(tag)s tag's '%(option)s' option was not a valid integer: '%(value)s'") % { + 'tag': bits[0], + 'option': name, + 'value': value, + }) + elif name == 'distribution': + if value in ['linear', 'log']: + kwargs[str(name)] = {'linear': LINEAR, 'log': LOGARITHMIC}[value] + else: + raise TemplateSyntaxError(_("%(tag)s tag's '%(option)s' option was not a valid choice: '%(value)s'") % { + 'tag': bits[0], + 'option': name, + 'value': value, + }) + else: + raise TemplateSyntaxError(_("%(tag)s tag was given an invalid option: '%(option)s'") % { + 'tag': bits[0], + 'option': name, + }) + except ValueError: + raise TemplateSyntaxError(_("%(tag)s tag was given a badly formatted option: '%(option)s'") % { + 'tag': bits[0], + 'option': bits[i], + }) + return TagCloudForModelNode(bits[1], bits[3], **kwargs) + +def do_tags_for_object(parser, token): + """ + 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 %} + """ + bits = token.contents.split() + if len(bits) != 4: + raise TemplateSyntaxError(_('%s tag requires exactly three arguments') % bits[0]) + if bits[2] != 'as': + raise TemplateSyntaxError(_("second argument to %s tag must be 'as'") % bits[0]) + return TagsForObjectNode(bits[1], bits[3]) + +def do_tagged_objects(parser, token): + """ + 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 %} + + """ + bits = token.contents.split() + if len(bits) != 6: + raise TemplateSyntaxError(_('%s tag requires exactly five arguments') % bits[0]) + if bits[2] != 'in': + raise TemplateSyntaxError(_("second argument to %s tag must be 'in'") % bits[0]) + if bits[4] != 'as': + raise TemplateSyntaxError(_("fourth argument to %s tag must be 'as'") % bits[0]) + return TaggedObjectsNode(bits[1], bits[3], bits[5]) + +register.tag('tags_for_model', do_tags_for_model) +register.tag('tag_cloud_for_model', do_tag_cloud_for_model) +register.tag('tags_for_object', do_tags_for_object) +register.tag('tagged_objects', do_tagged_objects) diff --git a/tagging/tests/._settings.py b/tagging/tests/._settings.py Binary files differnew file mode 100644 index 0000000..6092bc4 --- /dev/null +++ b/tagging/tests/._settings.py diff --git a/tagging/tests/._tags.txt b/tagging/tests/._tags.txt Binary files differnew file mode 100644 index 0000000..3348eaa --- /dev/null +++ b/tagging/tests/._tags.txt diff --git a/tagging/tests/__init__.py b/tagging/tests/__init__.py new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tagging/tests/__init__.py diff --git a/tagging/tests/models.py b/tagging/tests/models.py new file mode 100644 index 0000000..0708686 --- /dev/null +++ b/tagging/tests/models.py @@ -0,0 +1,38 @@ +from django.db import models + +from tagging.fields import TagField + +class Perch(models.Model): + size = models.IntegerField() + smelly = models.BooleanField(default=True) + +class Parrot(models.Model): + state = models.CharField(max_length=50) + perch = models.ForeignKey(Perch, null=True) + + def __unicode__(self): + return self.state + + class Meta: + ordering = ['state'] + +class Link(models.Model): + name = models.CharField(max_length=50) + + def __unicode__(self): + return self.name + + class Meta: + ordering = ['name'] + +class Article(models.Model): + name = models.CharField(max_length=50) + + def __unicode__(self): + return self.name + + class Meta: + ordering = ['name'] + +class FormTest(models.Model): + tags = TagField('Test', help_text='Test') diff --git a/tagging/tests/settings.py b/tagging/tests/settings.py new file mode 100644 index 0000000..74eb909 --- /dev/null +++ b/tagging/tests/settings.py @@ -0,0 +1,27 @@ +import os +DIRNAME = os.path.dirname(__file__) + +DEFAULT_CHARSET = 'utf-8' + +test_engine = os.environ.get("TAGGING_TEST_ENGINE", "sqlite3") + +DATABASE_ENGINE = test_engine +DATABASE_NAME = os.environ.get("TAGGING_DATABASE_NAME", "tagging_test") +DATABASE_USER = os.environ.get("TAGGING_DATABASE_USER", "") +DATABASE_PASSWORD = os.environ.get("TAGGING_DATABASE_PASSWORD", "") +DATABASE_HOST = os.environ.get("TAGGING_DATABASE_HOST", "localhost") + +if test_engine == "sqlite": + DATABASE_NAME = os.path.join(DIRNAME, 'tagging_test.db') + DATABASE_HOST = "" +elif test_engine == "mysql": + DATABASE_PORT = os.environ.get("TAGGING_DATABASE_PORT", 3306) +elif test_engine == "postgresql_psycopg2": + DATABASE_PORT = os.environ.get("TAGGING_DATABASE_PORT", 5432) + + +INSTALLED_APPS = ( + 'django.contrib.contenttypes', + 'tagging', + 'tagging.tests', +) diff --git a/tagging/tests/tags.txt b/tagging/tests/tags.txt new file mode 100644 index 0000000..8543411 --- /dev/null +++ b/tagging/tests/tags.txt @@ -0,0 +1,122 @@ +NewMedia 53 +Website 45 +PR 44 +Status 44 +Collaboration 41 +Drupal 34 +Journalism 31 +Transparency 30 +Theory 29 +Decentralization 25 +EchoChamberProject 24 +OpenSource 23 +Film 22 +Blog 21 +Interview 21 +Political 21 +Worldview 21 +Communications 19 +Conference 19 +Folksonomy 15 +MediaCriticism 15 +Volunteer 15 +Dialogue 13 +InternationalLaw 13 +Rosen 12 +Evolution 11 +KentBye 11 +Objectivity 11 +Plante 11 +ToDo 11 +Advisor 10 +Civics 10 +Roadmap 10 +Wilber 9 +About 8 +CivicSpace 8 +Ecosystem 8 +Choice 7 +Murphy 7 +Sociology 7 +ACH 6 +del.icio.us 6 +IntelligenceAnalysis 6 +Science 6 +Credibility 5 +Distribution 5 +Diversity 5 +Errors 5 +FinalCutPro 5 +Fundraising 5 +Law 5 +PhilosophyofScience 5 +Podcast 5 +PoliticalBias 5 +Activism 4 +Analysis 4 +CBS 4 +DeceptionDetection 4 +Editing 4 +History 4 +RSS 4 +Social 4 +Subjectivity 4 +Vlog 4 +ABC 3 +ALTubes 3 +Economics 3 +FCC 3 +NYT 3 +Sirota 3 +Sundance 3 +Training 3 +Wiki 3 +XML 3 +Borger 2 +Brody 2 +Deliberation 2 +EcoVillage 2 +Identity 2 +LAMP 2 +Lobe 2 +Maine 2 +May 2 +MediaLogic 2 +Metaphor 2 +Mitchell 2 +NBC 2 +OHanlon 2 +Psychology 2 +Queen 2 +Software 2 +SpiralDynamics 2 +Strobel 2 +Sustainability 2 +Transcripts 2 +Brown 1 +Buddhism 1 +Community 1 +DigitalDivide 1 +Donnelly 1 +Education 1 +FairUse 1 +FireANT 1 +Google 1 +HumanRights 1 +KM 1 +Kwiatkowski 1 +Landay 1 +Loiseau 1 +Math 1 +Music 1 +Nature 1 +Schechter 1 +Screencast 1 +Sivaraksa 1 +Skype 1 +SocialCapital 1 +TagCloud 1 +Thielmann 1 +Thomas 1 +Tiger 1 +Wedgwood 1
\ No newline at end of file diff --git a/tagging/tests/tests.py b/tagging/tests/tests.py new file mode 100644 index 0000000..f5c9e37 --- /dev/null +++ b/tagging/tests/tests.py @@ -0,0 +1,901 @@ +# -*- coding: utf-8 -*- + +import os +from django import forms +from django.db.models import Q +from django.test import TestCase +from tagging.forms import TagField +from tagging import settings +from tagging.models import Tag, TaggedItem +from tagging.tests.models import Article, Link, Perch, Parrot, FormTest +from tagging.utils import calculate_cloud, edit_string_for_tags, get_tag_list, get_tag, parse_tag_input +from tagging.utils import LINEAR + +############# +# Utilities # +############# + +class TestParseTagInput(TestCase): + def test_with_simple_space_delimited_tags(self): + """ Test with simple space-delimited tags. """ + + self.assertEquals(parse_tag_input('one'), [u'one']) + self.assertEquals(parse_tag_input('one two'), [u'one', u'two']) + self.assertEquals(parse_tag_input('one two three'), [u'one', u'three', u'two']) + self.assertEquals(parse_tag_input('one one two two'), [u'one', u'two']) + + def test_with_comma_delimited_multiple_words(self): + """ Test with comma-delimited multiple words. + An unquoted comma in the input will trigger this. """ + + self.assertEquals(parse_tag_input(',one'), [u'one']) + self.assertEquals(parse_tag_input(',one two'), [u'one two']) + self.assertEquals(parse_tag_input(',one two three'), [u'one two three']) + self.assertEquals(parse_tag_input('a-one, a-two and a-three'), + [u'a-one', u'a-two and a-three']) + + def test_with_double_quoted_multiple_words(self): + """ Test with double-quoted multiple words. + A completed quote will trigger this. Unclosed quotes are ignored. """ + + self.assertEquals(parse_tag_input('"one'), [u'one']) + self.assertEquals(parse_tag_input('"one two'), [u'one', u'two']) + self.assertEquals(parse_tag_input('"one two three'), [u'one', u'three', u'two']) + self.assertEquals(parse_tag_input('"one two"'), [u'one two']) + self.assertEquals(parse_tag_input('a-one "a-two and a-three"'), + [u'a-one', u'a-two and a-three']) + + def test_with_no_loose_commas(self): + """ Test with no loose commas -- split on spaces. """ + self.assertEquals(parse_tag_input('one two "thr,ee"'), [u'one', u'thr,ee', u'two']) + + def test_with_loose_commas(self): + """ Loose commas - split on commas """ + self.assertEquals(parse_tag_input('"one", two three'), [u'one', u'two three']) + + def test_tags_with_double_quotes_can_contain_commas(self): + """ Double quotes can contain commas """ + self.assertEquals(parse_tag_input('a-one "a-two, and a-three"'), + [u'a-one', u'a-two, and a-three']) + self.assertEquals(parse_tag_input('"two", one, one, two, "one"'), + [u'one', u'two']) + + def test_with_naughty_input(self): + """ Test with naughty input. """ + + # Bad users! Naughty users! + self.assertEquals(parse_tag_input(None), []) + self.assertEquals(parse_tag_input(''), []) + self.assertEquals(parse_tag_input('"'), []) + self.assertEquals(parse_tag_input('""'), []) + self.assertEquals(parse_tag_input('"' * 7), []) + self.assertEquals(parse_tag_input(',,,,,,'), []) + self.assertEquals(parse_tag_input('",",",",",",","'), [u',']) + self.assertEquals(parse_tag_input('a-one "a-two" and "a-three'), + [u'a-one', u'a-three', u'a-two', u'and']) + +class TestNormalisedTagListInput(TestCase): + def setUp(self): + self.cheese = Tag.objects.create(name='cheese') + self.toast = Tag.objects.create(name='toast') + + def test_single_tag_object_as_input(self): + self.assertEquals(get_tag_list(self.cheese), [self.cheese]) + + def test_space_delimeted_string_as_input(self): + ret = get_tag_list('cheese toast') + self.assertEquals(len(ret), 2) + self.failUnless(self.cheese in ret) + self.failUnless(self.toast in ret) + + def test_comma_delimeted_string_as_input(self): + ret = get_tag_list('cheese,toast') + self.assertEquals(len(ret), 2) + self.failUnless(self.cheese in ret) + self.failUnless(self.toast in ret) + + def test_with_empty_list(self): + self.assertEquals(get_tag_list([]), []) + + def test_list_of_two_strings(self): + ret = get_tag_list(['cheese', 'toast']) + self.assertEquals(len(ret), 2) + self.failUnless(self.cheese in ret) + self.failUnless(self.toast in ret) + + def test_list_of_tag_primary_keys(self): + ret = get_tag_list([self.cheese.id, self.toast.id]) + self.assertEquals(len(ret), 2) + self.failUnless(self.cheese in ret) + self.failUnless(self.toast in ret) + + def test_list_of_strings_with_strange_nontag_string(self): + ret = get_tag_list(['cheese', 'toast', 'ŠĐĆŽćžšđ']) + self.assertEquals(len(ret), 2) + self.failUnless(self.cheese in ret) + self.failUnless(self.toast in ret) + + def test_list_of_tag_instances(self): + ret = get_tag_list([self.cheese, self.toast]) + self.assertEquals(len(ret), 2) + self.failUnless(self.cheese in ret) + self.failUnless(self.toast in ret) + + def test_tuple_of_instances(self): + ret = get_tag_list((self.cheese, self.toast)) + self.assertEquals(len(ret), 2) + self.failUnless(self.cheese in ret) + self.failUnless(self.toast in ret) + + def test_with_tag_filter(self): + ret = get_tag_list(Tag.objects.filter(name__in=['cheese', 'toast'])) + self.assertEquals(len(ret), 2) + self.failUnless(self.cheese in ret) + self.failUnless(self.toast in ret) + + def test_with_invalid_input_mix_of_string_and_instance(self): + try: + get_tag_list(['cheese', self.toast]) + except ValueError, ve: + self.assertEquals(str(ve), + 'If a list or tuple of tags is provided, they must all be tag names, Tag objects or Tag ids.') + except Exception, e: + raise self.failureException('the wrong type of exception was raised: type [%s] value [%]' %\ + (str(type(e)), str(e))) + else: + raise self.failureException('a ValueError exception was supposed to be raised!') + + def test_with_invalid_input(self): + try: + get_tag_list(29) + except ValueError, ve: + self.assertEquals(str(ve), 'The tag input given was invalid.') + except Exception, e: + raise self.failureException('the wrong type of exception was raised: type [%s] value [%s]' %\ + (str(type(e)), str(e))) + else: + raise self.failureException('a ValueError exception was supposed to be raised!') + + def test_with_tag_instance(self): + self.assertEquals(get_tag(self.cheese), self.cheese) + + def test_with_string(self): + self.assertEquals(get_tag('cheese'), self.cheese) + + def test_with_primary_key(self): + self.assertEquals(get_tag(self.cheese.id), self.cheese) + + def test_nonexistent_tag(self): + self.assertEquals(get_tag('mouse'), None) + +class TestCalculateCloud(TestCase): + def setUp(self): + self.tags = [] + for line in open(os.path.join(os.path.dirname(__file__), 'tags.txt')).readlines(): + name, count = line.rstrip().split() + tag = Tag(name=name) + tag.count = int(count) + self.tags.append(tag) + + def test_default_distribution(self): + sizes = {} + for tag in calculate_cloud(self.tags, steps=5): + sizes[tag.font_size] = sizes.get(tag.font_size, 0) + 1 + + # This isn't a pre-calculated test, just making sure it's consistent + self.assertEquals(sizes[1], 48) + self.assertEquals(sizes[2], 30) + self.assertEquals(sizes[3], 19) + self.assertEquals(sizes[4], 15) + self.assertEquals(sizes[5], 10) + + def test_linear_distribution(self): + sizes = {} + for tag in calculate_cloud(self.tags, steps=5, distribution=LINEAR): + sizes[tag.font_size] = sizes.get(tag.font_size, 0) + 1 + + # This isn't a pre-calculated test, just making sure it's consistent + self.assertEquals(sizes[1], 97) + self.assertEquals(sizes[2], 12) + self.assertEquals(sizes[3], 7) + self.assertEquals(sizes[4], 2) + self.assertEquals(sizes[5], 4) + + def test_invalid_distribution(self): + try: + calculate_cloud(self.tags, steps=5, distribution='cheese') + except ValueError, ve: + self.assertEquals(str(ve), 'Invalid distribution algorithm specified: cheese.') + except Exception, e: + raise self.failureException('the wrong type of exception was raised: type [%s] value [%s]' %\ + (str(type(e)), str(e))) + else: + raise self.failureException('a ValueError exception was supposed to be raised!') + +########### +# Tagging # +########### + +class TestBasicTagging(TestCase): + def setUp(self): + self.dead_parrot = Parrot.objects.create(state='dead') + + def test_update_tags(self): + Tag.objects.update_tags(self.dead_parrot, 'foo,bar,"ter"') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 3) + self.failUnless(get_tag('foo') in tags) + self.failUnless(get_tag('bar') in tags) + self.failUnless(get_tag('ter') in tags) + + Tag.objects.update_tags(self.dead_parrot, '"foo" bar "baz"') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 3) + self.failUnless(get_tag('bar') in tags) + self.failUnless(get_tag('baz') in tags) + self.failUnless(get_tag('foo') in tags) + + def test_add_tag(self): + # start off in a known, mildly interesting state + Tag.objects.update_tags(self.dead_parrot, 'foo bar baz') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 3) + self.failUnless(get_tag('bar') in tags) + self.failUnless(get_tag('baz') in tags) + self.failUnless(get_tag('foo') in tags) + + # try to add a tag that already exists + Tag.objects.add_tag(self.dead_parrot, 'foo') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 3) + self.failUnless(get_tag('bar') in tags) + self.failUnless(get_tag('baz') in tags) + self.failUnless(get_tag('foo') in tags) + + # now add a tag that doesn't already exist + Tag.objects.add_tag(self.dead_parrot, 'zip') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 4) + self.failUnless(get_tag('zip') in tags) + self.failUnless(get_tag('bar') in tags) + self.failUnless(get_tag('baz') in tags) + self.failUnless(get_tag('foo') in tags) + + def test_add_tag_invalid_input_no_tags_specified(self): + # start off in a known, mildly interesting state + Tag.objects.update_tags(self.dead_parrot, 'foo bar baz') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 3) + self.failUnless(get_tag('bar') in tags) + self.failUnless(get_tag('baz') in tags) + self.failUnless(get_tag('foo') in tags) + + try: + Tag.objects.add_tag(self.dead_parrot, ' ') + except AttributeError, ae: + self.assertEquals(str(ae), 'No tags were given: " ".') + except Exception, e: + raise self.failureException('the wrong type of exception was raised: type [%s] value [%s]' %\ + (str(type(e)), str(e))) + else: + raise self.failureException('an AttributeError exception was supposed to be raised!') + + def test_add_tag_invalid_input_multiple_tags_specified(self): + # start off in a known, mildly interesting state + Tag.objects.update_tags(self.dead_parrot, 'foo bar baz') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 3) + self.failUnless(get_tag('bar') in tags) + self.failUnless(get_tag('baz') in tags) + self.failUnless(get_tag('foo') in tags) + + try: + Tag.objects.add_tag(self.dead_parrot, 'one two') + except AttributeError, ae: + self.assertEquals(str(ae), 'Multiple tags were given: "one two".') + except Exception, e: + raise self.failureException('the wrong type of exception was raised: type [%s] value [%s]' %\ + (str(type(e)), str(e))) + else: + raise self.failureException('an AttributeError exception was supposed to be raised!') + + def test_update_tags_exotic_characters(self): + # start off in a known, mildly interesting state + Tag.objects.update_tags(self.dead_parrot, 'foo bar baz') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 3) + self.failUnless(get_tag('bar') in tags) + self.failUnless(get_tag('baz') in tags) + self.failUnless(get_tag('foo') in tags) + + Tag.objects.update_tags(self.dead_parrot, u'ŠĐĆŽćžšđ') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 1) + self.assertEquals(tags[0].name, u'ŠĐĆŽćžšđ') + + Tag.objects.update_tags(self.dead_parrot, u'你好') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 1) + self.assertEquals(tags[0].name, u'你好') + + def test_update_tags_with_none(self): + # start off in a known, mildly interesting state + Tag.objects.update_tags(self.dead_parrot, 'foo bar baz') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 3) + self.failUnless(get_tag('bar') in tags) + self.failUnless(get_tag('baz') in tags) + self.failUnless(get_tag('foo') in tags) + + Tag.objects.update_tags(self.dead_parrot, None) + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 0) + +class TestModelTagField(TestCase): + """ Test the 'tags' field on models. """ + + def test_create_with_tags_specified(self): + f1 = FormTest.objects.create(tags=u'test3 test2 test1') + tags = Tag.objects.get_for_object(f1) + test1_tag = get_tag('test1') + test2_tag = get_tag('test2') + test3_tag = get_tag('test3') + self.failUnless(None not in (test1_tag, test2_tag, test3_tag)) + self.assertEquals(len(tags), 3) + self.failUnless(test1_tag in tags) + self.failUnless(test2_tag in tags) + self.failUnless(test3_tag in tags) + + def test_update_via_tags_field(self): + f1 = FormTest.objects.create(tags=u'test3 test2 test1') + tags = Tag.objects.get_for_object(f1) + test1_tag = get_tag('test1') + test2_tag = get_tag('test2') + test3_tag = get_tag('test3') + self.failUnless(None not in (test1_tag, test2_tag, test3_tag)) + self.assertEquals(len(tags), 3) + self.failUnless(test1_tag in tags) + self.failUnless(test2_tag in tags) + self.failUnless(test3_tag in tags) + + f1.tags = u'test4' + f1.save() + tags = Tag.objects.get_for_object(f1) + test4_tag = get_tag('test4') + self.assertEquals(len(tags), 1) + self.assertEquals(tags[0], test4_tag) + + f1.tags = '' + f1.save() + tags = Tag.objects.get_for_object(f1) + self.assertEquals(len(tags), 0) + +class TestSettings(TestCase): + def setUp(self): + self.original_force_lower_case_tags = settings.FORCE_LOWERCASE_TAGS + self.dead_parrot = Parrot.objects.create(state='dead') + + def tearDown(self): + settings.FORCE_LOWERCASE_TAGS = self.original_force_lower_case_tags + + def test_force_lowercase_tags(self): + """ Test forcing tags to lowercase. """ + + settings.FORCE_LOWERCASE_TAGS = True + + Tag.objects.update_tags(self.dead_parrot, 'foO bAr Ter') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 3) + foo_tag = get_tag('foo') + bar_tag = get_tag('bar') + ter_tag = get_tag('ter') + self.failUnless(foo_tag in tags) + self.failUnless(bar_tag in tags) + self.failUnless(ter_tag in tags) + + Tag.objects.update_tags(self.dead_parrot, 'foO bAr baZ') + tags = Tag.objects.get_for_object(self.dead_parrot) + baz_tag = get_tag('baz') + self.assertEquals(len(tags), 3) + self.failUnless(bar_tag in tags) + self.failUnless(baz_tag in tags) + self.failUnless(foo_tag in tags) + + Tag.objects.add_tag(self.dead_parrot, 'FOO') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 3) + self.failUnless(bar_tag in tags) + self.failUnless(baz_tag in tags) + self.failUnless(foo_tag in tags) + + Tag.objects.add_tag(self.dead_parrot, 'Zip') + tags = Tag.objects.get_for_object(self.dead_parrot) + self.assertEquals(len(tags), 4) + zip_tag = get_tag('zip') + self.failUnless(bar_tag in tags) + self.failUnless(baz_tag in tags) + self.failUnless(foo_tag in tags) + self.failUnless(zip_tag in tags) + + f1 = FormTest.objects.create() + f1.tags = u'TEST5' + f1.save() + tags = Tag.objects.get_for_object(f1) + test5_tag = get_tag('test5') + self.assertEquals(len(tags), 1) + self.failUnless(test5_tag in tags) + self.assertEquals(f1.tags, u'test5') + +class TestTagUsageForModelBaseCase(TestCase): + def test_tag_usage_for_model_empty(self): + self.assertEquals(Tag.objects.usage_for_model(Parrot), []) + +class TestTagUsageForModel(TestCase): + def setUp(self): + parrot_details = ( + ('pining for the fjords', 9, True, 'foo bar'), + ('passed on', 6, False, 'bar baz ter'), + ('no more', 4, True, 'foo ter'), + ('late', 2, False, 'bar ter'), + ) + + for state, perch_size, perch_smelly, tags in parrot_details: + perch = Perch.objects.create(size=perch_size, smelly=perch_smelly) + parrot = Parrot.objects.create(state=state, perch=perch) + Tag.objects.update_tags(parrot, tags) + + def test_tag_usage_for_model(self): + tag_usage = Tag.objects.usage_for_model(Parrot, counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 4) + self.failUnless((u'bar', 3) in relevant_attribute_list) + self.failUnless((u'baz', 1) in relevant_attribute_list) + self.failUnless((u'foo', 2) in relevant_attribute_list) + self.failUnless((u'ter', 3) in relevant_attribute_list) + + def test_tag_usage_for_model_with_min_count(self): + tag_usage = Tag.objects.usage_for_model(Parrot, min_count = 2) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 3) + self.failUnless((u'bar', 3) in relevant_attribute_list) + self.failUnless((u'foo', 2) in relevant_attribute_list) + self.failUnless((u'ter', 3) in relevant_attribute_list) + + def test_tag_usage_with_filter_on_model_objects(self): + tag_usage = Tag.objects.usage_for_model(Parrot, counts=True, filters=dict(state='no more')) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 2) + self.failUnless((u'foo', 1) in relevant_attribute_list) + self.failUnless((u'ter', 1) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_model(Parrot, counts=True, filters=dict(state__startswith='p')) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 4) + self.failUnless((u'bar', 2) in relevant_attribute_list) + self.failUnless((u'baz', 1) in relevant_attribute_list) + self.failUnless((u'foo', 1) in relevant_attribute_list) + self.failUnless((u'ter', 1) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_model(Parrot, counts=True, filters=dict(perch__size__gt=4)) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 4) + self.failUnless((u'bar', 2) in relevant_attribute_list) + self.failUnless((u'baz', 1) in relevant_attribute_list) + self.failUnless((u'foo', 1) in relevant_attribute_list) + self.failUnless((u'ter', 1) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_model(Parrot, counts=True, filters=dict(perch__smelly=True)) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 3) + self.failUnless((u'bar', 1) in relevant_attribute_list) + self.failUnless((u'foo', 2) in relevant_attribute_list) + self.failUnless((u'ter', 1) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_model(Parrot, min_count=2, filters=dict(perch__smelly=True)) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 1) + self.failUnless((u'foo', 2) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_model(Parrot, filters=dict(perch__size__gt=4)) + relevant_attribute_list = [(tag.name, hasattr(tag, 'counts')) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 4) + self.failUnless((u'bar', False) in relevant_attribute_list) + self.failUnless((u'baz', False) in relevant_attribute_list) + self.failUnless((u'foo', False) in relevant_attribute_list) + self.failUnless((u'ter', False) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_model(Parrot, filters=dict(perch__size__gt=99)) + relevant_attribute_list = [(tag.name, hasattr(tag, 'counts')) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 0) + +class TestTagsRelatedForModel(TestCase): + def setUp(self): + parrot_details = ( + ('pining for the fjords', 9, True, 'foo bar'), + ('passed on', 6, False, 'bar baz ter'), + ('no more', 4, True, 'foo ter'), + ('late', 2, False, 'bar ter'), + ) + + for state, perch_size, perch_smelly, tags in parrot_details: + perch = Perch.objects.create(size=perch_size, smelly=perch_smelly) + parrot = Parrot.objects.create(state=state, perch=perch) + Tag.objects.update_tags(parrot, tags) + + def test_related_for_model_with_tag_query_sets_as_input(self): + related_tags = Tag.objects.related_for_model(Tag.objects.filter(name__in=['bar']), Parrot, counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in related_tags] + self.assertEquals(len(relevant_attribute_list), 3) + self.failUnless((u'baz', 1) in relevant_attribute_list) + self.failUnless((u'foo', 1) in relevant_attribute_list) + self.failUnless((u'ter', 2) in relevant_attribute_list) + + related_tags = Tag.objects.related_for_model(Tag.objects.filter(name__in=['bar']), Parrot, min_count=2) + relevant_attribute_list = [(tag.name, tag.count) for tag in related_tags] + self.assertEquals(len(relevant_attribute_list), 1) + self.failUnless((u'ter', 2) in relevant_attribute_list) + + related_tags = Tag.objects.related_for_model(Tag.objects.filter(name__in=['bar']), Parrot, counts=False) + relevant_attribute_list = [tag.name for tag in related_tags] + self.assertEquals(len(relevant_attribute_list), 3) + self.failUnless(u'baz' in relevant_attribute_list) + self.failUnless(u'foo' in relevant_attribute_list) + self.failUnless(u'ter' in relevant_attribute_list) + + related_tags = Tag.objects.related_for_model(Tag.objects.filter(name__in=['bar', 'ter']), Parrot, counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in related_tags] + self.assertEquals(len(relevant_attribute_list), 1) + self.failUnless((u'baz', 1) in relevant_attribute_list) + + related_tags = Tag.objects.related_for_model(Tag.objects.filter(name__in=['bar', 'ter', 'baz']), Parrot, counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in related_tags] + self.assertEquals(len(relevant_attribute_list), 0) + + def test_related_for_model_with_tag_strings_as_input(self): + # Once again, with feeling (strings) + related_tags = Tag.objects.related_for_model('bar', Parrot, counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in related_tags] + self.assertEquals(len(relevant_attribute_list), 3) + self.failUnless((u'baz', 1) in relevant_attribute_list) + self.failUnless((u'foo', 1) in relevant_attribute_list) + self.failUnless((u'ter', 2) in relevant_attribute_list) + + related_tags = Tag.objects.related_for_model('bar', Parrot, min_count=2) + relevant_attribute_list = [(tag.name, tag.count) for tag in related_tags] + self.assertEquals(len(relevant_attribute_list), 1) + self.failUnless((u'ter', 2) in relevant_attribute_list) + + related_tags = Tag.objects.related_for_model('bar', Parrot, counts=False) + relevant_attribute_list = [tag.name for tag in related_tags] + self.assertEquals(len(relevant_attribute_list), 3) + self.failUnless(u'baz' in relevant_attribute_list) + self.failUnless(u'foo' in relevant_attribute_list) + self.failUnless(u'ter' in relevant_attribute_list) + + related_tags = Tag.objects.related_for_model(['bar', 'ter'], Parrot, counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in related_tags] + self.assertEquals(len(relevant_attribute_list), 1) + self.failUnless((u'baz', 1) in relevant_attribute_list) + + related_tags = Tag.objects.related_for_model(['bar', 'ter', 'baz'], Parrot, counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in related_tags] + self.assertEquals(len(relevant_attribute_list), 0) + +class TestGetTaggedObjectsByModel(TestCase): + def setUp(self): + parrot_details = ( + ('pining for the fjords', 9, True, 'foo bar'), + ('passed on', 6, False, 'bar baz ter'), + ('no more', 4, True, 'foo ter'), + ('late', 2, False, 'bar ter'), + ) + + for state, perch_size, perch_smelly, tags in parrot_details: + perch = Perch.objects.create(size=perch_size, smelly=perch_smelly) + parrot = Parrot.objects.create(state=state, perch=perch) + Tag.objects.update_tags(parrot, tags) + + self.foo = Tag.objects.get(name='foo') + self.bar = Tag.objects.get(name='bar') + self.baz = Tag.objects.get(name='baz') + self.ter = Tag.objects.get(name='ter') + + self.pining_for_the_fjords_parrot = Parrot.objects.get(state='pining for the fjords') + self.passed_on_parrot = Parrot.objects.get(state='passed on') + self.no_more_parrot = Parrot.objects.get(state='no more') + self.late_parrot = Parrot.objects.get(state='late') + + def test_get_by_model_simple(self): + parrots = TaggedItem.objects.get_by_model(Parrot, self.foo) + self.assertEquals(len(parrots), 2) + self.failUnless(self.no_more_parrot in parrots) + self.failUnless(self.pining_for_the_fjords_parrot in parrots) + + parrots = TaggedItem.objects.get_by_model(Parrot, self.bar) + self.assertEquals(len(parrots), 3) + self.failUnless(self.late_parrot in parrots) + self.failUnless(self.passed_on_parrot in parrots) + self.failUnless(self.pining_for_the_fjords_parrot in parrots) + + def test_get_by_model_intersection(self): + parrots = TaggedItem.objects.get_by_model(Parrot, [self.foo, self.baz]) + self.assertEquals(len(parrots), 0) + + parrots = TaggedItem.objects.get_by_model(Parrot, [self.foo, self.bar]) + self.assertEquals(len(parrots), 1) + self.failUnless(self.pining_for_the_fjords_parrot in parrots) + + parrots = TaggedItem.objects.get_by_model(Parrot, [self.bar, self.ter]) + self.assertEquals(len(parrots), 2) + self.failUnless(self.late_parrot in parrots) + self.failUnless(self.passed_on_parrot in parrots) + + # Issue 114 - Intersection with non-existant tags + parrots = TaggedItem.objects.get_intersection_by_model(Parrot, []) + self.assertEquals(len(parrots), 0) + + def test_get_by_model_with_tag_querysets_as_input(self): + parrots = TaggedItem.objects.get_by_model(Parrot, Tag.objects.filter(name__in=['foo', 'baz'])) + self.assertEquals(len(parrots), 0) + + parrots = TaggedItem.objects.get_by_model(Parrot, Tag.objects.filter(name__in=['foo', 'bar'])) + self.assertEquals(len(parrots), 1) + self.failUnless(self.pining_for_the_fjords_parrot in parrots) + + parrots = TaggedItem.objects.get_by_model(Parrot, Tag.objects.filter(name__in=['bar', 'ter'])) + self.assertEquals(len(parrots), 2) + self.failUnless(self.late_parrot in parrots) + self.failUnless(self.passed_on_parrot in parrots) + + def test_get_by_model_with_strings_as_input(self): + parrots = TaggedItem.objects.get_by_model(Parrot, 'foo baz') + self.assertEquals(len(parrots), 0) + + parrots = TaggedItem.objects.get_by_model(Parrot, 'foo bar') + self.assertEquals(len(parrots), 1) + self.failUnless(self.pining_for_the_fjords_parrot in parrots) + + parrots = TaggedItem.objects.get_by_model(Parrot, 'bar ter') + self.assertEquals(len(parrots), 2) + self.failUnless(self.late_parrot in parrots) + self.failUnless(self.passed_on_parrot in parrots) + + def test_get_by_model_with_lists_of_strings_as_input(self): + parrots = TaggedItem.objects.get_by_model(Parrot, ['foo', 'baz']) + self.assertEquals(len(parrots), 0) + + parrots = TaggedItem.objects.get_by_model(Parrot, ['foo', 'bar']) + self.assertEquals(len(parrots), 1) + self.failUnless(self.pining_for_the_fjords_parrot in parrots) + + parrots = TaggedItem.objects.get_by_model(Parrot, ['bar', 'ter']) + self.assertEquals(len(parrots), 2) + self.failUnless(self.late_parrot in parrots) + self.failUnless(self.passed_on_parrot in parrots) + + def test_get_by_nonexistent_tag(self): + # Issue 50 - Get by non-existent tag + parrots = TaggedItem.objects.get_by_model(Parrot, 'argatrons') + self.assertEquals(len(parrots), 0) + + def test_get_union_by_model(self): + parrots = TaggedItem.objects.get_union_by_model(Parrot, ['foo', 'ter']) + self.assertEquals(len(parrots), 4) + self.failUnless(self.late_parrot in parrots) + self.failUnless(self.no_more_parrot in parrots) + self.failUnless(self.passed_on_parrot in parrots) + self.failUnless(self.pining_for_the_fjords_parrot in parrots) + + parrots = TaggedItem.objects.get_union_by_model(Parrot, ['bar', 'baz']) + self.assertEquals(len(parrots), 3) + self.failUnless(self.late_parrot in parrots) + self.failUnless(self.passed_on_parrot in parrots) + self.failUnless(self.pining_for_the_fjords_parrot in parrots) + + # Issue 114 - Union with non-existant tags + parrots = TaggedItem.objects.get_union_by_model(Parrot, []) + self.assertEquals(len(parrots), 0) + +class TestGetRelatedTaggedItems(TestCase): + def setUp(self): + parrot_details = ( + ('pining for the fjords', 9, True, 'foo bar'), + ('passed on', 6, False, 'bar baz ter'), + ('no more', 4, True, 'foo ter'), + ('late', 2, False, 'bar ter'), + ) + + for state, perch_size, perch_smelly, tags in parrot_details: + perch = Perch.objects.create(size=perch_size, smelly=perch_smelly) + parrot = Parrot.objects.create(state=state, perch=perch) + Tag.objects.update_tags(parrot, tags) + + self.l1 = Link.objects.create(name='link 1') + Tag.objects.update_tags(self.l1, 'tag1 tag2 tag3 tag4 tag5') + self.l2 = Link.objects.create(name='link 2') + Tag.objects.update_tags(self.l2, 'tag1 tag2 tag3') + self.l3 = Link.objects.create(name='link 3') + Tag.objects.update_tags(self.l3, 'tag1') + self.l4 = Link.objects.create(name='link 4') + + self.a1 = Article.objects.create(name='article 1') + Tag.objects.update_tags(self.a1, 'tag1 tag2 tag3 tag4') + + def test_get_related_objects_of_same_model(self): + related_objects = TaggedItem.objects.get_related(self.l1, Link) + self.assertEquals(len(related_objects), 2) + self.failUnless(self.l2 in related_objects) + self.failUnless(self.l3 in related_objects) + + related_objects = TaggedItem.objects.get_related(self.l4, Link) + self.assertEquals(len(related_objects), 0) + + def test_get_related_objects_of_same_model_limited_number_of_results(self): + # This fails on Oracle because it has no support for a 'LIMIT' clause. + # See http://asktom.oracle.com/pls/asktom/f?p=100:11:0::::P11_QUESTION_ID:127412348064 + + # ask for no more than 1 result + related_objects = TaggedItem.objects.get_related(self.l1, Link, num=1) + self.assertEquals(len(related_objects), 1) + self.failUnless(self.l2 in related_objects) + + def test_get_related_objects_of_same_model_limit_related_items(self): + related_objects = TaggedItem.objects.get_related(self.l1, Link.objects.exclude(name='link 3')) + self.assertEquals(len(related_objects), 1) + self.failUnless(self.l2 in related_objects) + + def test_get_related_objects_of_different_model(self): + related_objects = TaggedItem.objects.get_related(self.a1, Link) + self.assertEquals(len(related_objects), 3) + self.failUnless(self.l1 in related_objects) + self.failUnless(self.l2 in related_objects) + self.failUnless(self.l3 in related_objects) + + Tag.objects.update_tags(self.a1, 'tag6') + related_objects = TaggedItem.objects.get_related(self.a1, Link) + self.assertEquals(len(related_objects), 0) + +class TestTagUsageForQuerySet(TestCase): + def setUp(self): + parrot_details = ( + ('pining for the fjords', 9, True, 'foo bar'), + ('passed on', 6, False, 'bar baz ter'), + ('no more', 4, True, 'foo ter'), + ('late', 2, False, 'bar ter'), + ) + + for state, perch_size, perch_smelly, tags in parrot_details: + perch = Perch.objects.create(size=perch_size, smelly=perch_smelly) + parrot = Parrot.objects.create(state=state, perch=perch) + Tag.objects.update_tags(parrot, tags) + + def test_tag_usage_for_queryset(self): + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.filter(state='no more'), counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 2) + self.failUnless((u'foo', 1) in relevant_attribute_list) + self.failUnless((u'ter', 1) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.filter(state__startswith='p'), counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 4) + self.failUnless((u'bar', 2) in relevant_attribute_list) + self.failUnless((u'baz', 1) in relevant_attribute_list) + self.failUnless((u'foo', 1) in relevant_attribute_list) + self.failUnless((u'ter', 1) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.filter(perch__size__gt=4), counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 4) + self.failUnless((u'bar', 2) in relevant_attribute_list) + self.failUnless((u'baz', 1) in relevant_attribute_list) + self.failUnless((u'foo', 1) in relevant_attribute_list) + self.failUnless((u'ter', 1) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.filter(perch__smelly=True), counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 3) + self.failUnless((u'bar', 1) in relevant_attribute_list) + self.failUnless((u'foo', 2) in relevant_attribute_list) + self.failUnless((u'ter', 1) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.filter(perch__smelly=True), min_count=2) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 1) + self.failUnless((u'foo', 2) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.filter(perch__size__gt=4)) + relevant_attribute_list = [(tag.name, hasattr(tag, 'counts')) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 4) + self.failUnless((u'bar', False) in relevant_attribute_list) + self.failUnless((u'baz', False) in relevant_attribute_list) + self.failUnless((u'foo', False) in relevant_attribute_list) + self.failUnless((u'ter', False) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.filter(perch__size__gt=99)) + relevant_attribute_list = [(tag.name, hasattr(tag, 'counts')) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 0) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.filter(Q(perch__size__gt=6) | Q(state__startswith='l')), counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 3) + self.failUnless((u'bar', 2) in relevant_attribute_list) + self.failUnless((u'foo', 1) in relevant_attribute_list) + self.failUnless((u'ter', 1) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.filter(Q(perch__size__gt=6) | Q(state__startswith='l')), min_count=2) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 1) + self.failUnless((u'bar', 2) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.filter(Q(perch__size__gt=6) | Q(state__startswith='l'))) + relevant_attribute_list = [(tag.name, hasattr(tag, 'counts')) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 3) + self.failUnless((u'bar', False) in relevant_attribute_list) + self.failUnless((u'foo', False) in relevant_attribute_list) + self.failUnless((u'ter', False) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.exclude(state='passed on'), counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 3) + self.failUnless((u'bar', 2) in relevant_attribute_list) + self.failUnless((u'foo', 2) in relevant_attribute_list) + self.failUnless((u'ter', 2) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.exclude(state__startswith='p'), min_count=2) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 1) + self.failUnless((u'ter', 2) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.exclude(Q(perch__size__gt=6) | Q(perch__smelly=False)), counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 2) + self.failUnless((u'foo', 1) in relevant_attribute_list) + self.failUnless((u'ter', 1) in relevant_attribute_list) + + tag_usage = Tag.objects.usage_for_queryset(Parrot.objects.exclude(perch__smelly=True).filter(state__startswith='l'), counts=True) + relevant_attribute_list = [(tag.name, tag.count) for tag in tag_usage] + self.assertEquals(len(relevant_attribute_list), 2) + self.failUnless((u'bar', 1) in relevant_attribute_list) + self.failUnless((u'ter', 1) in relevant_attribute_list) + +################ +# Model Fields # +################ + +class TestTagFieldInForms(TestCase): + def test_tag_field_in_modelform(self): + # Ensure that automatically created forms use TagField + class TestForm(forms.ModelForm): + class Meta: + model = FormTest + + form = TestForm() + self.assertEquals(form.fields['tags'].__class__.__name__, 'TagField') + + def test_recreation_of_tag_list_string_representations(self): + plain = Tag.objects.create(name='plain') + spaces = Tag.objects.create(name='spa ces') + comma = Tag.objects.create(name='com,ma') + self.assertEquals(edit_string_for_tags([plain]), u'plain') + self.assertEquals(edit_string_for_tags([plain, spaces]), u'plain, spa ces') + self.assertEquals(edit_string_for_tags([plain, spaces, comma]), u'plain, spa ces, "com,ma"') + self.assertEquals(edit_string_for_tags([plain, comma]), u'plain "com,ma"') + self.assertEquals(edit_string_for_tags([comma, spaces]), u'"com,ma", spa ces') + + def test_tag_d_validation(self): + t = TagField() + self.assertEquals(t.clean('foo'), u'foo') + self.assertEquals(t.clean('foo bar baz'), u'foo bar baz') + self.assertEquals(t.clean('foo,bar,baz'), u'foo,bar,baz') + self.assertEquals(t.clean('foo, bar, baz'), u'foo, bar, baz') + self.assertEquals(t.clean('foo qwertyuiopasdfghjklzxcvbnmqwertyuiopasdfghjklzxcvb bar'), + u'foo qwertyuiopasdfghjklzxcvbnmqwertyuiopasdfghjklzxcvb bar') + try: + t.clean('foo qwertyuiopasdfghjklzxcvbnmqwertyuiopasdfghjklzxcvbn bar') + except forms.ValidationError, ve: + self.assertEquals(str(ve), "[u'Each tag may be no more than 50 characters long.']") + except Exception, e: + raise e + else: + raise self.failureException('a ValidationError exception was supposed to have been raised.') diff --git a/tagging/utils.py b/tagging/utils.py new file mode 100644 index 0000000..e89bab0 --- /dev/null +++ b/tagging/utils.py @@ -0,0 +1,263 @@ +""" +Tagging utilities - from user tag input parsing to tag cloud +calculation. +""" +import math +import types + +from django.db.models.query import QuerySet +from django.utils.encoding import force_unicode +from django.utils.translation import ugettext as _ + +# Python 2.3 compatibility +try: + set +except NameError: + from sets import Set as set + +def 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. + """ + if not input: + return [] + + input = force_unicode(input) + + # Special case - if there are no commas or double quotes in the + # input, we don't *do* a recall... I mean, we know we only need to + # split on spaces. + if u',' not in input and u'"' not in input: + words = list(set(split_strip(input, u' '))) + words.sort() + return words + + words = [] + buffer = [] + # Defer splitting of non-quoted sections until we know if there are + # any unquoted commas. + to_be_split = [] + saw_loose_comma = False + open_quote = False + i = iter(input) + try: + while 1: + c = i.next() + if c == u'"': + if buffer: + to_be_split.append(u''.join(buffer)) + buffer = [] + # Find the matching quote + open_quote = True + c = i.next() + while c != u'"': + buffer.append(c) + c = i.next() + if buffer: + word = u''.join(buffer).strip() + if word: + words.append(word) + buffer = [] + open_quote = False + else: + if not saw_loose_comma and c == u',': + saw_loose_comma = True + buffer.append(c) + except StopIteration: + # If we were parsing an open quote which was never closed treat + # the buffer as unquoted. + if buffer: + if open_quote and u',' in buffer: + saw_loose_comma = True + to_be_split.append(u''.join(buffer)) + if to_be_split: + if saw_loose_comma: + delimiter = u',' + else: + delimiter = u' ' + for chunk in to_be_split: + words.extend(split_strip(chunk, delimiter)) + words = list(set(words)) + words.sort() + return words + +def split_strip(input, delimiter=u','): + """ + Splits ``input`` on ``delimiter``, stripping each resulting string + and returning a list of non-empty strings. + """ + if not input: + return [] + + words = [w.strip() for w in input.split(delimiter)] + return [w for w in words if w] + +def 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. + """ + names = [] + use_commas = False + for tag in tags: + name = tag.name + if u',' in name: + names.append('"%s"' % name) + continue + elif u' ' in name: + if not use_commas: + use_commas = True + names.append(name) + if use_commas: + glue = u', ' + else: + glue = u' ' + return glue.join(names) + +def get_queryset_and_model(queryset_or_model): + """ + Given a ``QuerySet`` or a ``Model``, returns a two-tuple of + (queryset, model). + + If a ``Model`` is given, the ``QuerySet`` returned will be created + using its default manager. + """ + try: + return queryset_or_model, queryset_or_model.model + except AttributeError: + return queryset_or_model._default_manager.all(), queryset_or_model + +def 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``. + + """ + from tagging.models import Tag + if isinstance(tags, Tag): + return [tags] + elif isinstance(tags, QuerySet) and tags.model is Tag: + return tags + elif isinstance(tags, types.StringTypes): + return Tag.objects.filter(name__in=parse_tag_input(tags)) + elif isinstance(tags, (types.ListType, types.TupleType)): + if len(tags) == 0: + return tags + contents = set() + for item in tags: + if isinstance(item, types.StringTypes): + contents.add('string') + elif isinstance(item, Tag): + contents.add('tag') + elif isinstance(item, (types.IntType, types.LongType)): + contents.add('int') + if len(contents) == 1: + if 'string' in contents: + return Tag.objects.filter(name__in=[force_unicode(tag) \ + for tag in tags]) + elif 'tag' in contents: + return tags + elif 'int' in contents: + return Tag.objects.filter(id__in=tags) + else: + raise ValueError(_('If a list or tuple of tags is provided, they must all be tag names, Tag objects or Tag ids.')) + else: + raise ValueError(_('The tag input given was invalid.')) + +def get_tag(tag): + """ + Utility function for accepting single tag input in a flexible + manner. + + If a ``Tag`` object is given it will be returned as-is; if a + string or integer are given, they will be used to lookup the + appropriate ``Tag``. + + If no matching tag can be found, ``None`` will be returned. + """ + from tagging.models import Tag + if isinstance(tag, Tag): + return tag + + try: + if isinstance(tag, types.StringTypes): + return Tag.objects.get(name=tag) + elif isinstance(tag, (types.IntType, types.LongType)): + return Tag.objects.get(id=tag) + except Tag.DoesNotExist: + pass + + return None + +# Font size distribution algorithms +LOGARITHMIC, LINEAR = 1, 2 + +def _calculate_thresholds(min_weight, max_weight, steps): + delta = (max_weight - min_weight) / float(steps) + return [min_weight + i * delta for i in range(1, steps + 1)] + +def _calculate_tag_weight(weight, max_weight, distribution): + """ + Logarithmic tag weight calculation is based on code from the + `Tag Cloud`_ plugin for Mephisto, by Sven Fuchs. + + .. _`Tag Cloud`: http://www.artweb-design.de/projects/mephisto-plugin-tag-cloud + """ + if distribution == LINEAR or max_weight == 1: + return weight + elif distribution == LOGARITHMIC: + return math.log(weight) * max_weight / math.log(max_weight) + raise ValueError(_('Invalid distribution algorithm specified: %s.') % distribution) + +def calculate_cloud(tags, steps=4, distribution=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``. + """ + if len(tags) > 0: + counts = [tag.count for tag in tags] + min_weight = float(min(counts)) + max_weight = float(max(counts)) + thresholds = _calculate_thresholds(min_weight, max_weight, steps) + for tag in tags: + font_set = False + tag_weight = _calculate_tag_weight(tag.count, max_weight, distribution) + for i in range(steps): + if not font_set and tag_weight <= thresholds[i]: + tag.font_size = i + 1 + font_set = True + return tags diff --git a/tagging/views.py b/tagging/views.py new file mode 100644 index 0000000..9e7e2f5 --- /dev/null +++ b/tagging/views.py @@ -0,0 +1,52 @@ +""" +Tagging related views. +""" +from django.http import Http404 +from django.utils.translation import ugettext as _ +from django.views.generic.list_detail import object_list + +from tagging.models import Tag, TaggedItem +from tagging.utils import get_tag, get_queryset_and_model + +def tagged_object_list(request, queryset_or_model=None, tag=None, + related_tags=False, related_tag_counts=True, **kwargs): + """ + A thin wrapper around + ``django.views.generic.list_detail.object_list`` which creates a + ``QuerySet`` containing instances of the given queryset or model + tagged with the given tag. + + In addition to the context variables set up by ``object_list``, a + ``tag`` context variable will contain the ``Tag`` instance for the + tag. + + If ``related_tags`` is ``True``, a ``related_tags`` context variable + will contain tags related to the given tag for the given model. + Additionally, if ``related_tag_counts`` is ``True``, each related + tag will have a ``count`` attribute indicating the number of items + which have it in addition to the given tag. + """ + if queryset_or_model is None: + try: + queryset_or_model = kwargs.pop('queryset_or_model') + except KeyError: + raise AttributeError(_('tagged_object_list must be called with a queryset or a model.')) + + if tag is None: + try: + tag = kwargs.pop('tag') + except KeyError: + raise AttributeError(_('tagged_object_list must be called with a tag.')) + + tag_instance = get_tag(tag) + if tag_instance is None: + raise Http404(_('No Tag found matching "%s".') % tag) + queryset = TaggedItem.objects.get_by_model(queryset_or_model, tag_instance) + if not kwargs.has_key('extra_context'): + kwargs['extra_context'] = {} + kwargs['extra_context']['tag'] = tag_instance + if related_tags: + kwargs['extra_context']['related_tags'] = \ + Tag.objects.related_for_model(tag_instance, queryset_or_model, + counts=related_tag_counts) + return object_list(request, queryset, **kwargs) |