From d65aa3c3c146b12548a54c894060bce9a8715ad2 Mon Sep 17 00:00:00 2001 From: Jonas Genannt Date: Sun, 15 Nov 2015 22:26:06 +0100 Subject: Imported Upstream version 0.4 --- docs/._overview.txt | Bin 188 -> 0 bytes docs/Makefile | 192 +++++++++++ docs/conf.py | 293 +++++++++++++++++ docs/index.rst | 886 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/overview.txt | 904 ---------------------------------------------------- 5 files changed, 1371 insertions(+), 904 deletions(-) delete mode 100644 docs/._overview.txt create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst delete mode 100644 docs/overview.txt (limited to 'docs') diff --git a/docs/._overview.txt b/docs/._overview.txt deleted file mode 100644 index c4db396..0000000 Binary files a/docs/._overview.txt and /dev/null differ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..0cddc85 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,192 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/django-tagging.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django-tagging.qhc" + +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/django-tagging" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/django-tagging" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..d2a7406 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,293 @@ +# -*- coding: utf-8 -*- +# +# django-tagging documentation build configuration file, created by +# sphinx-quickstart on Thu May 14 19:31:27 2015. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. +import os +import re +import sys + +from datetime import date +HERE = os.path.abspath(os.path.dirname(__file__)) + +sys.path.append(HERE) +sys.path.append(os.path.join(HERE, '..')) + +import tagging + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', +] + +intersphinx_mapping = { + 'django': ('http://readthedocs.org/docs/django/en/latest/', None), +} + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Django Tagging' +copyright = '%s, %s' % (date.today().year, tagging.__maintainer__) +author = tagging.__author__ + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The full version, including alpha/beta/rc tags. +release = tagging.__version__ +# The short X.Y version. +version = re.match(r'\d+\.\d+(?:\.\d+)?', release).group() + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'django-taggingdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'django-tagging.tex', u'django-tagging Documentation', + u'Fantomas42', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'django-tagging', u'django-tagging Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'django-tagging', u'django-tagging Documentation', + author, 'django-tagging', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..c73cbe4 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,886 @@ +============== +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:: + :local: + :depth: 3 + +Installation +============ + +Installing an official release +------------------------------ + +Official releases are made available from +https://pypi.python.org/pypi/django-tagging/ + +Source distribution +~~~~~~~~~~~~~~~~~~~ + +Download the a 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. + +More easily with :program:`pip`:: + + $ pip install django-tagging + +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, clone the git repository instead. The following +command will clone the development branch to ``django-tagging`` directory:: + + git clone git@github.com:Fantomas42/django-tagging.git + +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.4.dev0 + +When you want to update your copy of the Django Tagging source code, run +the command ``git pull`` from within the ``django-tagging`` 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 git, keep an eye on the `CHANGELOG`_ + before you update your copy of the source code. + +.. _`PYTHONPATH`: http://www.python.org/doc/2.5.2/tut/node8.html#SECTION008120000000000000000 +.. _`junction`: http://www.microsoft.com/technet/sysinternals/FileAndDisk/Junction.mspx +.. _`CHANGELOG`: https://github.com/Fantomas42/django-tagging/blob/develop/CHANGELOG.txt + +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 migrate``. + +The ``migrate`` 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.registry`` module and call its +``register`` function, like so:: + + from django.db import models + + from tagging.registry import register + + 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 + [, , ] + >>> del widget.tags + >>> widget.tags + [] + +``ModelTagManager`` +------------------- + +A manager for retrieving tags used by a particular model. + +Defines the following methods: + +* ``get_queryset()`` -- 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) + [, ] + +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.objects.add_tag(widget, 'tiles') + >>> Tag.objects.get_for_object(widget) + [, , ] + +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) + [, , , ] + +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) + [, ] + +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]) + [] + +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'])) + [] + >>> TaggedItem.objects.get_by_model(Widget, 'house thing') + [] + >>> TaggedItem.objects.get_by_model(Widget, ['house', 'thing']) + [] + +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.TaggedObjectList`` +---------------------------------- + +**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.ListView`` view, which takes a +model and a tag as its arguments (in addition to the other optional +arguments supported by ``ListView``), building the appropriate +``QuerySet`` for you instead of expecting one to be passed in. + +**Required arguments:** + + * ``tag``: The tag which objects of the given model must have in + order to be listed. + +**Optional arguments:** + +Please refer to the `ListView 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 `ListView documentation`_ for additional +template context variables which may be provided. + + * ``tag``: The ``Tag`` instance for the given tag. + +.. _`ListView documentation`: https://docs.djangoproject.com/en/1.8/ref/class-based-views/generic-display/#listview + +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 TaggedObjectList + + from shop.apps.products.models import Widget + + urlpatterns = patterns('', + url(r'^widgets/tag/(?P[^/]+(?u))/$', + TaggedObjectList.as_view(model=Widget, paginate_by=10, allow_empty=True), + 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 TaggedObjectList + + class TaggedPeopleFilteredList(TaggedObjectList): + queryset = People.objects.filter(country__code=country_code) + +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/docs/overview.txt b/docs/overview.txt deleted file mode 100644 index feb08c9..0000000 --- a/docs/overview.txt +++ /dev/null @@ -1,904 +0,0 @@ -============== -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 - [, , ] - >>> 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) - [, ] - -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.objects.add_tag(widget, 'tiles') - >>> Tag.objects.get_for_object(widget) - [, , ] - -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) - [, , , ] - -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) - [, ] - -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]) - [] - -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'])) - [] - >>> TaggedItem.objects.get_by_model(Widget, 'house thing') - [] - >>> TaggedItem.objects.get_by_model(Widget, ['house', 'thing']) - [] - -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[^/]+)/$', - 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 %} -- cgit v1.2.3