pax_global_header00006660000000000000000000000064136305073000014507gustar00rootroot0000000000000052 comment=d11932f33e1053cc6d18baa96c807a5b51d26bcd django-tagging-0.5.0/000077500000000000000000000000001363050730000143715ustar00rootroot00000000000000django-tagging-0.5.0/.coveragerc000066400000000000000000000002601363050730000165100ustar00rootroot00000000000000[run] source = tagging omit = tagging/tests/* tagging/migrations/* [report] sort = Miss show_missing = True exclude_lines = pragma: no cover django-tagging-0.5.0/.gitignore000066400000000000000000000000141363050730000163540ustar00rootroot00000000000000docs/_build django-tagging-0.5.0/.travis.yml000066400000000000000000000022011363050730000164750ustar00rootroot00000000000000language: python python: - 3.7 - 3.8 services: - postgresql - mysql env: - DJANGO=1.11 DATABASE_ENGINE=sqlite - DJANGO=1.11 DATABASE_ENGINE=postgres - DJANGO=1.11 DATABASE_ENGINE=mysql - DJANGO=2.2 DATABASE_ENGINE=sqlite - DJANGO=2.2 DATABASE_ENGINE=postgres - DJANGO=2.2 DATABASE_ENGINE=mysql - DJANGO=3.0 DATABASE_ENGINE=sqlite - DJANGO=3.0 DATABASE_ENGINE=postgres - DJANGO=3.0 DATABASE_ENGINE=mysql install: - pip install -U setuptools zc.buildout - buildout versions:django=$DJANGO - sh -c "if [ '$DATABASE_ENGINE' = 'postgres' ]; then pip install psycopg2; psql -c 'create database tagging;' -U postgres; fi" - sh -c "if [ '$DATABASE_ENGINE' = 'mysql' ]; then pip install mysqlclient; mysql -e 'create database tagging CHARACTER SET utf8 COLLATE utf8_general_ci;'; mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql; fi" before_script: - ./bin/flake8 tagging script: - ./bin/test-and-cover after_success: - ./bin/coveralls notifications: irc: - "irc.freenode.org#django-tagging" django-tagging-0.5.0/CHANGELOG.txt000066400000000000000000000135631363050730000164310ustar00rootroot00000000000000======================== Django Tagging Changelog ======================== Version 0.5.0, 6th March 2020: ------------------------------ * Drop support for Python 2. * Compatiblity fix for Django 2.2 and Django 3.0. Version 0.4.6, 14th October 2017: -------------------------------- * Fix IntegrityError while saving inconsistent tags * Update tag name length to use MAX_TAG_LENGTH setting Version 0.4.5, 6th September 2016: ---------------------------------- * Fix on the previous compatiblity fix. Version 0.4.4, 5th September 2016: ---------------------------------- * Compatiblity fix for Django 1.10 Version 0.4.3, 3rd May 2016: ---------------------------- * Add missing migration for ``on_delete`` Version 0.4.2, 2nd May 2016: ---------------------------- * Fix tag weight * Reduce warnings for recent versions of Django Version 0.4.1, 15th January 2016: --------------------------------- * Typo fixes * Support apps Version 0.4, 15th June 2015: ---------------------------- * Modernization of the package Version 0.3.6, 13th May 2015: ----------------------------- * Corrected initial migration Version 0.3.5, 13th May 2015: ----------------------------- * Added support for Django 1.8 * Using migrations to fix syncdb * Rename get_query_set to get_queryset * Import GenericForeignKey from the new location Version 0.3.4, 7th November 2014: --------------------------------- * Fix unicode errors in admin Version 0.3.3, 15th October 2014: --------------------------------- * Added support for Django 1.7 Version 0.3.2, 18th February 2014: ---------------------------------- * Added support for Django 1.4 and 1.5 * Added support for Python 2.6 to 3.3 * Added tox to test and coverage Version 0.3.1, 22nd January 2010: --------------------------------- * Fixed Django 1.2 support (did not add anything new) * Fixed #95 - tagging.register won't stomp on model attributes 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. django-tagging-0.5.0/LICENSE.txt000066400000000000000000000052031363050730000162140ustar00rootroot00000000000000Django Tagging -------------- Copyright (c) 2007-2015, Jonathan Buchanan, Julien Fache 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. django-tagging-0.5.0/MANIFEST.in000066400000000000000000000003131363050730000161240ustar00rootroot00000000000000include CHANGELOG.txt include LICENSE.txt include MANIFEST.in include README.rst include versions.cfg include buildout.cfg recursive-include docs * recursive-include tagging/tests *.txt prune docs/_builddjango-tagging-0.5.0/README.rst000066400000000000000000000013731363050730000160640ustar00rootroot00000000000000============== Django Tagging ============== |travis-develop| |coverage-develop| This is a generic tagging application for Django projects https://django-tagging.readthedocs.io/ Note that this application version requires Python 3.5 or later, and Django 1.11 or later. You can obtain Python from http://www.python.org/ and Django from http://www.djangoproject.com/. .. |travis-develop| image:: https://travis-ci.org/Fantomas42/django-tagging.png?branch=develop :alt: Build Status - develop branch :target: http://travis-ci.org/Fantomas42/django-tagging .. |coverage-develop| image:: https://coveralls.io/repos/Fantomas42/django-tagging/badge.png?branch=develop :alt: Coverage of the code :target: https://coveralls.io/r/Fantomas42/django-tagging django-tagging-0.5.0/buildout.cfg000066400000000000000000000030351363050730000167020ustar00rootroot00000000000000[buildout] extends = versions.cfg parts = test test-and-cover flake8 evolution coveralls develop = . eggs = django django-tagging show-picked-versions = true [test] recipe = pbp.recipe.noserunner eggs = nose nose-sfd nose-progressive ${buildout:eggs} defaults = --with-progressive --with-sfd environment = testenv [test-and-cover] recipe = pbp.recipe.noserunner eggs = nose nose-sfd coverage ${buildout:eggs} defaults = --with-coverage --cover-package=tagging --cover-erase --with-sfd environment = testenv [flake8] recipe = zc.recipe.egg eggs = flake8 [evolution] recipe = zc.recipe.egg eggs = buildout-versions-checker arguments = '-w --sorting alpha' scripts = check-buildout-updates=${:_buildout_section_name_} [coveralls] recipe = zc.recipe.egg eggs = python-coveralls [testenv] DJANGO_SETTINGS_MODULE = tagging.tests.settings django-tagging-0.5.0/docs/000077500000000000000000000000001363050730000153215ustar00rootroot00000000000000django-tagging-0.5.0/docs/Makefile000066400000000000000000000164211363050730000167650ustar00rootroot00000000000000# 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." django-tagging-0.5.0/docs/conf.py000066400000000000000000000221771363050730000166310ustar00rootroot00000000000000# -*- 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': ('https://django.readthedocs.io/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 django-tagging-0.5.0/docs/index.rst000066400000000000000000000674251363050730000172000ustar00rootroot00000000000000============== 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) 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_manager_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 %} django-tagging-0.5.0/setup.py000066400000000000000000000022661363050730000161110ustar00rootroot00000000000000""" Based entirely on Django's own ``setup.py``. """ from setuptools import find_packages from setuptools import setup import tagging setup( name='django-tagging', version=tagging.__version__, description='Generic tagging application for Django', long_description='\n'.join([open('README.rst').read(), open('CHANGELOG.txt').read()]), keywords='django, tag, tagging', author=tagging.__author__, author_email=tagging.__author_email__, maintainer=tagging.__maintainer__, maintainer_email=tagging.__maintainer_email__, url=tagging.__url__, license=tagging.__license__, packages=find_packages(), include_package_data=True, zip_safe=False, classifiers=[ 'Framework :: Django', 'Environment :: Web Environment', 'Operating System :: OS Independent', 'Development Status :: 5 - Production/Stable', 'Intended Audience :: Developers', 'License :: OSI Approved :: BSD License', 'Programming Language :: Python', 'Programming Language :: Python :: 3', 'Topic :: Utilities', 'Topic :: Software Development :: Libraries :: Python Modules'] ) django-tagging-0.5.0/tagging/000077500000000000000000000000001363050730000160115ustar00rootroot00000000000000django-tagging-0.5.0/tagging/__init__.py000066400000000000000000000005261363050730000201250ustar00rootroot00000000000000""" Django-tagging """ __version__ = '0.5.0' __license__ = 'BSD License' __author__ = 'Jonathan Buchanan' __author_email__ = 'jonathan.buchanan@gmail.com' __maintainer__ = 'Fantomas42' __maintainer_email__ = 'fantomas42@gmail.com' __url__ = 'https://github.com/Fantomas42/django-tagging' default_app_config = 'tagging.apps.TaggingConfig' django-tagging-0.5.0/tagging/admin.py000066400000000000000000000004651363050730000174600ustar00rootroot00000000000000""" Admin components for tagging. """ from django.contrib import admin from tagging.forms import TagAdminForm from tagging.models import Tag from tagging.models import TaggedItem class TagAdmin(admin.ModelAdmin): form = TagAdminForm admin.site.register(TaggedItem) admin.site.register(Tag, TagAdmin) django-tagging-0.5.0/tagging/apps.py000066400000000000000000000004241363050730000173260ustar00rootroot00000000000000""" Apps for tagging. """ from django.apps import AppConfig from django.utils.translation import gettext_lazy as _ class TaggingConfig(AppConfig): """ Config for Tagging application. """ name = 'tagging' label = 'tagging' verbose_name = _('Tagging') django-tagging-0.5.0/tagging/fields.py000066400000000000000000000075041363050730000176370ustar00rootroot00000000000000""" A custom Model Field for tagging. """ from django.db.models import signals from django.db.models.fields import CharField from django.utils.translation import gettext_lazy as _ from tagging import settings from tagging.forms import TagField as TagFormField 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. """ # The next instruction does nothing particular, # but needed to by-pass the deferred fields system # when saving an instance, which check the keys present # in instance.__dict__. # The issue is introducted in Django 1.10 instance.__dict__[self.attname] = tags setattr(instance, '_%s_cache' % self.attname, tags) def get_internal_type(self): return 'CharField' def formfield(self, **kwargs): defaults = {'form_class': TagFormField} defaults.update(kwargs) return super(TagField, self).formfield(**defaults) django-tagging-0.5.0/tagging/forms.py000066400000000000000000000020431363050730000175100ustar00rootroot00000000000000""" Form components for tagging. """ from django import forms from django.utils.translation import gettext 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 fields = ('name',) 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.')) 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) 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 django-tagging-0.5.0/tagging/generic.py000066400000000000000000000037361363050730000200100ustar00rootroot00000000000000""" Generic components for tagging. """ 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] django-tagging-0.5.0/tagging/managers.py000066400000000000000000000044131363050730000201620ustar00rootroot00000000000000""" Custom managers for tagging. """ from django.contrib.contenttypes.models import ContentType from django.db import models from tagging.models import Tag from tagging.models import TaggedItem class ModelTagManager(models.Manager): """ A manager for retrieving tags for a particular model. """ def get_queryset(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) django-tagging-0.5.0/tagging/migrations/000077500000000000000000000000001363050730000201655ustar00rootroot00000000000000django-tagging-0.5.0/tagging/migrations/0001_initial.py000066400000000000000000000034641363050730000226370ustar00rootroot00000000000000from django.db import migrations from django.db import models class Migration(migrations.Migration): dependencies = [ ('contenttypes', '0001_initial'), ] operations = [ migrations.CreateModel( name='Tag', fields=[ ('id', models.AutoField( verbose_name='ID', serialize=False, auto_created=True, primary_key=True)), ('name', models.CharField( unique=True, max_length=50, verbose_name='name', db_index=True)), ], options={ 'ordering': ('name',), 'verbose_name': 'tag', 'verbose_name_plural': 'tags', }, ), migrations.CreateModel( name='TaggedItem', fields=[ ('id', models.AutoField( verbose_name='ID', serialize=False, auto_created=True, primary_key=True)), ('object_id', models.PositiveIntegerField( verbose_name='object id', db_index=True)), ('content_type', models.ForeignKey( verbose_name='content type', on_delete=models.SET_NULL, to='contenttypes.ContentType')), ('tag', models.ForeignKey( related_name='items', verbose_name='tag', on_delete=models.SET_NULL, to='tagging.Tag')), ], options={ 'verbose_name': 'tagged item', 'verbose_name_plural': 'tagged items', }, ), migrations.AlterUniqueTogether( name='taggeditem', unique_together=set([('tag', 'content_type', 'object_id')]), ), ] django-tagging-0.5.0/tagging/migrations/0002_on_delete.py000066400000000000000000000015101363050730000231330ustar00rootroot00000000000000import django.db.models.deletion from django.db import migrations from django.db import models class Migration(migrations.Migration): dependencies = [ ('tagging', '0001_initial'), ] operations = [ migrations.AlterField( model_name='taggeditem', name='content_type', field=models.ForeignKey( on_delete=django.db.models.deletion.CASCADE, to='contenttypes.ContentType', verbose_name='content type'), ), migrations.AlterField( model_name='taggeditem', name='tag', field=models.ForeignKey( on_delete=django.db.models.deletion.CASCADE, related_name='items', to='tagging.Tag', verbose_name='tag'), ), ] django-tagging-0.5.0/tagging/migrations/0003_adapt_max_tag_length.py000066400000000000000000000007731363050730000253420ustar00rootroot00000000000000from django.conf import settings from django.db import migrations, models class Migration(migrations.Migration): dependencies = [ ('tagging', '0002_on_delete'), ] operations = [ migrations.AlterField( model_name='tag', name='name', field=models.CharField( unique=True, max_length=getattr(settings, 'MAX_TAG_LENGTH', 50), verbose_name='name', db_index=True), ), ] django-tagging-0.5.0/tagging/migrations/__init__.py000066400000000000000000000000401363050730000222700ustar00rootroot00000000000000""" Migrations for tagging. """ django-tagging-0.5.0/tagging/models.py000066400000000000000000000471171363050730000176600ustar00rootroot00000000000000""" Models and managers for tagging. """ from django.contrib.contenttypes.fields import GenericForeignKey from django.contrib.contenttypes.models import ContentType from django.db import connection from django.db import models from django.utils.encoding import smart_text from django.utils.translation import gettext_lazy as _ from tagging import settings from tagging.utils import LOGARITHMIC from tagging.utils import calculate_cloud from tagging.utils import get_queryset_and_model from tagging.utils import get_tag_list from tagging.utils import parse_tag_input 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.get_or_create( content_type_id=ctype.pk, object_id=obj.pk, tag=tag, ) 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``. """ compiler = queryset.query.get_compiler(using=queryset.db) where, params = compiler.compile(queryset.query.where) extra_joins = ' '.join(compiler.get_from_clause()[0][1:]) 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""" tagging_table = qn(self.model._meta.get_field( 'tag').remote_field.model._meta.db_table) 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': tagging_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=settings.MAX_TAG_LENGTH, unique=True, db_index=True) objects = TagManager() class Meta: ordering = ('name',) verbose_name = _('tag') verbose_name_plural = _('tags') def __str__(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', on_delete=models.CASCADE) content_type = models.ForeignKey( ContentType, verbose_name=_('content type'), on_delete=models.CASCADE) object_id = models.PositiveIntegerField( _('object id'), db_index=True) object = 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 __str__(self): return '%s [%s]' % (smart_text(self.object), smart_text(self.tag)) django-tagging-0.5.0/tagging/registry.py000066400000000000000000000027061363050730000202400ustar00rootroot00000000000000""" Registery for tagging. """ from tagging.managers import ModelTaggedItemManager from tagging.managers import TagDescriptor registry = [] class AlreadyRegistered(Exception): """ An attempt was made to register a model more than once. """ pass def register(model, tag_descriptor_attr='tags', tagged_item_manager_attr='tagged'): """ Sets the given model class up for working with tags. """ if model in registry: raise AlreadyRegistered( "The model '%s' has already been registered." % model._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) django-tagging-0.5.0/tagging/settings.py000066400000000000000000000007231363050730000202250ustar00rootroot00000000000000""" 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) django-tagging-0.5.0/tagging/templatetags/000077500000000000000000000000001363050730000205035ustar00rootroot00000000000000django-tagging-0.5.0/tagging/templatetags/__init__.py000066400000000000000000000000511363050730000226100ustar00rootroot00000000000000""" Templatetags module for tagging. """ django-tagging-0.5.0/tagging/templatetags/tagging_tags.py000066400000000000000000000223641363050730000235220ustar00rootroot00000000000000""" Templatetags for tagging. """ from django.apps.registry import apps from django.template import Library from django.template import Node from django.template import TemplateSyntaxError from django.template import Variable from django.utils.translation import gettext as _ from tagging.models import Tag from tagging.models import TaggedItem from tagging.utils import LINEAR from tagging.utils import 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 = apps.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 = apps.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 = apps.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) django-tagging-0.5.0/tagging/tests/000077500000000000000000000000001363050730000171535ustar00rootroot00000000000000django-tagging-0.5.0/tagging/tests/__init__.py000066400000000000000000000000331363050730000212600ustar00rootroot00000000000000""" Tests for tagging. """ django-tagging-0.5.0/tagging/tests/models.py000066400000000000000000000020561363050730000210130ustar00rootroot00000000000000from 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, on_delete=models.CASCADE) def __str__(self): return self.state class Meta: ordering = ['state'] class Link(models.Model): name = models.CharField(max_length=50) def __str__(self): return self.name class Meta: ordering = ['name'] class Article(models.Model): name = models.CharField(max_length=50) def __str__(self): return self.name class Meta: ordering = ['name'] class FormTest(models.Model): tags = TagField('Test', help_text='Test') class FormTestNull(models.Model): tags = TagField(null=True) class FormMultipleFieldTest(models.Model): tagging_field = TagField('Test', help_text='Test') name = models.CharField(max_length=50) django-tagging-0.5.0/tagging/tests/settings.py000066400000000000000000000016531363050730000213720ustar00rootroot00000000000000"""Tests settings""" import os SECRET_KEY = 'secret-key' DATABASES = { 'default': { 'NAME': 'tagging.db', 'ENGINE': 'django.db.backends.sqlite3' } } DATABASE_ENGINE = os.environ.get('DATABASE_ENGINE') if DATABASE_ENGINE == 'postgres': DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql_psycopg2', 'NAME': 'tagging', 'USER': 'postgres', 'HOST': 'localhost' } } elif DATABASE_ENGINE == 'mysql': DATABASES = { 'default': { 'ENGINE': 'django.db.backends.mysql', 'NAME': 'zinnia', 'USER': 'root', 'HOST': 'localhost', 'TEST': { 'COLLATION': 'utf8_general_ci' } } } INSTALLED_APPS = [ 'django.contrib.auth', 'django.contrib.sessions', 'django.contrib.contenttypes', 'tagging', 'tagging.tests', ] django-tagging-0.5.0/tagging/tests/tags.txt000066400000000000000000000025461363050730000206610ustar00rootroot00000000000000NewMedia 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 1django-tagging-0.5.0/tagging/tests/tests.py000066400000000000000000001473651363050730000207070ustar00rootroot00000000000000import os from django import forms from django.core.exceptions import ImproperlyConfigured from django.db.models import Q from django.test import TestCase from django.test.utils import override_settings from tagging import settings from tagging.forms import TagAdminForm from tagging.forms import TagField from tagging.models import Tag from tagging.models import TaggedItem from tagging.tests.models import Article from tagging.tests.models import FormMultipleFieldTest from tagging.tests.models import FormTest from tagging.tests.models import FormTestNull from tagging.tests.models import Link from tagging.tests.models import Parrot from tagging.tests.models import Perch from tagging.utils import LINEAR from tagging.utils import LOGARITHMIC from tagging.utils import _calculate_tag_weight from tagging.utils import calculate_cloud from tagging.utils import edit_string_for_tags from tagging.utils import get_tag from tagging.utils import get_tag_list from tagging.utils import parse_tag_input ############# # Utilities # ############# class TestParseTagInput(TestCase): def test_with_simple_space_delimited_tags(self): """ Test with simple space-delimited tags. """ self.assertEqual(parse_tag_input('one'), ['one']) self.assertEqual(parse_tag_input('one two'), ['one', 'two']) self.assertEqual(parse_tag_input('one one two two'), ['one', 'two']) self.assertEqual(parse_tag_input('one two three'), ['one', 'three', '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.assertEqual(parse_tag_input(',one'), ['one']) self.assertEqual(parse_tag_input(',one two'), ['one two']) self.assertEqual(parse_tag_input(',one two three'), ['one two three']) self.assertEqual(parse_tag_input('a-one, a-two and a-three'), ['a-one', '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.assertEqual(parse_tag_input('"one'), ['one']) self.assertEqual(parse_tag_input('"one two'), ['one', 'two']) self.assertEqual(parse_tag_input('"one two three'), ['one', 'three', 'two']) self.assertEqual(parse_tag_input('"one two"'), ['one two']) self.assertEqual(parse_tag_input('a-one "a-two and a-three"'), ['a-one', 'a-two and a-three']) def test_with_no_loose_commas(self): """ Test with no loose commas -- split on spaces. """ self.assertEqual(parse_tag_input('one two "thr,ee"'), ['one', 'thr,ee', 'two']) def test_with_loose_commas(self): """ Loose commas - split on commas """ self.assertEqual(parse_tag_input('"one", two three'), ['one', 'two three']) def test_tags_with_double_quotes_can_contain_commas(self): """ Double quotes can contain commas """ self.assertEqual(parse_tag_input('a-one "a-two, and a-three"'), ['a-one', 'a-two, and a-three']) self.assertEqual(parse_tag_input('"two", one, one, two, "one"'), ['one', 'two']) self.assertEqual(parse_tag_input('two", one'), ['one', 'two']) def test_with_naughty_input(self): """ Test with naughty input. """ # Bad users! Naughty users! self.assertEqual(parse_tag_input(None), []) self.assertEqual(parse_tag_input(''), []) self.assertEqual(parse_tag_input('"'), []) self.assertEqual(parse_tag_input('""'), []) self.assertEqual(parse_tag_input('"' * 7), []) self.assertEqual(parse_tag_input(',,,,,,'), []) self.assertEqual(parse_tag_input('",",",",",",","'), [',']) self.assertEqual(parse_tag_input('a-one "a-two" and "a-three'), ['a-one', 'a-three', 'a-two', 'and']) class TestNormalisedTagListInput(TestCase): def setUp(self): self.toast = Tag.objects.create(name='toast') self.cheese = Tag.objects.create(name='cheese') def test_single_tag_object_as_input(self): self.assertEqual(get_tag_list(self.cheese), [self.cheese]) def test_space_delimeted_string_as_input(self): ret = get_tag_list('cheese toast') self.assertEqual(len(ret), 2) self.assertTrue(self.cheese in ret) self.assertTrue(self.toast in ret) def test_comma_delimeted_string_as_input(self): ret = get_tag_list('cheese,toast') self.assertEqual(len(ret), 2) self.assertTrue(self.cheese in ret) self.assertTrue(self.toast in ret) def test_with_empty_list(self): self.assertEqual(get_tag_list([]), []) def test_list_of_two_strings(self): ret = get_tag_list(['cheese', 'toast']) self.assertEqual(len(ret), 2) self.assertTrue(self.cheese in ret) self.assertTrue(self.toast in ret) def test_list_of_tag_primary_keys(self): ret = get_tag_list([self.cheese.id, self.toast.id]) self.assertEqual(len(ret), 2) self.assertTrue(self.cheese in ret) self.assertTrue(self.toast in ret) def test_list_of_strings_with_strange_nontag_string(self): ret = get_tag_list(['cheese', 'toast', 'ŠĐĆŽćžšđ']) self.assertEqual(len(ret), 2) self.assertTrue(self.cheese in ret) self.assertTrue(self.toast in ret) def test_list_of_tag_instances(self): ret = get_tag_list([self.cheese, self.toast]) self.assertEqual(len(ret), 2) self.assertTrue(self.cheese in ret) self.assertTrue(self.toast in ret) def test_tuple_of_instances(self): ret = get_tag_list((self.cheese, self.toast)) self.assertEqual(len(ret), 2) self.assertTrue(self.cheese in ret) self.assertTrue(self.toast in ret) def test_with_tag_filter(self): ret = get_tag_list(Tag.objects.filter(name__in=['cheese', 'toast'])) self.assertEqual(len(ret), 2) self.assertTrue(self.cheese in ret) self.assertTrue(self.toast in ret) def test_with_invalid_input_mix_of_string_and_instance(self): try: get_tag_list(['cheese', self.toast]) except ValueError as ve: self.assertEqual( str(ve), 'If a list or tuple of tags is provided, they must all ' 'be tag names, Tag objects or Tag ids.') except Exception as 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 as ve: self.assertEqual(str(ve), 'The tag input given was invalid.') except Exception as e: print('--', 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.assertEqual(get_tag(self.cheese), self.cheese) def test_with_string(self): self.assertEqual(get_tag('cheese'), self.cheese) def test_with_primary_key(self): self.assertEqual(get_tag(self.cheese.id), self.cheese) def test_nonexistent_tag(self): self.assertEqual(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.assertEqual(sizes[1], 48) self.assertEqual(sizes[2], 30) self.assertEqual(sizes[3], 19) self.assertEqual(sizes[4], 15) self.assertEqual(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.assertEqual(sizes[1], 97) self.assertEqual(sizes[2], 12) self.assertEqual(sizes[3], 7) self.assertEqual(sizes[4], 2) self.assertEqual(sizes[5], 4) def test_invalid_distribution(self): try: calculate_cloud(self.tags, steps=5, distribution='cheese') except ValueError as ve: self.assertEqual( str(ve), 'Invalid distribution algorithm specified: cheese.') except Exception as 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_calculate_tag_weight(self): self.assertEqual( _calculate_tag_weight(10, 20, LINEAR), 10) self.assertEqual( _calculate_tag_weight(10, 20, LOGARITHMIC), 15.37243573680482) def test_calculate_tag_weight_invalid_size(self): self.assertEqual( _calculate_tag_weight(10, 10, LOGARITHMIC), 10.0) self.assertEqual( _calculate_tag_weight(26, 26, LOGARITHMIC), 26.0) ########### # 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.assertEqual(len(tags), 3) self.assertTrue(get_tag('foo') in tags) self.assertTrue(get_tag('bar') in tags) self.assertTrue(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.assertEqual(len(tags), 3) self.assertTrue(get_tag('bar') in tags) self.assertTrue(get_tag('baz') in tags) self.assertTrue(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.assertEqual(len(tags), 3) self.assertTrue(get_tag('bar') in tags) self.assertTrue(get_tag('baz') in tags) self.assertTrue(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.assertEqual(len(tags), 3) self.assertTrue(get_tag('bar') in tags) self.assertTrue(get_tag('baz') in tags) self.assertTrue(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.assertEqual(len(tags), 4) self.assertTrue(get_tag('zip') in tags) self.assertTrue(get_tag('bar') in tags) self.assertTrue(get_tag('baz') in tags) self.assertTrue(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.assertEqual(len(tags), 3) self.assertTrue(get_tag('bar') in tags) self.assertTrue(get_tag('baz') in tags) self.assertTrue(get_tag('foo') in tags) try: Tag.objects.add_tag(self.dead_parrot, ' ') except AttributeError as ae: self.assertEqual(str(ae), 'No tags were given: " ".') except Exception as 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.assertEqual(len(tags), 3) self.assertTrue(get_tag('bar') in tags) self.assertTrue(get_tag('baz') in tags) self.assertTrue(get_tag('foo') in tags) try: Tag.objects.add_tag(self.dead_parrot, 'one two') except AttributeError as ae: self.assertEqual(str(ae), 'Multiple tags were given: "one two".') except Exception as 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.assertEqual(len(tags), 3) self.assertTrue(get_tag('bar') in tags) self.assertTrue(get_tag('baz') in tags) self.assertTrue(get_tag('foo') in tags) Tag.objects.update_tags(self.dead_parrot, 'ŠĐĆŽćžšđ') tags = Tag.objects.get_for_object(self.dead_parrot) self.assertEqual(len(tags), 1) self.assertEqual(tags[0].name, 'ŠĐĆŽćžšđ') Tag.objects.update_tags(self.dead_parrot, '你好') tags = Tag.objects.get_for_object(self.dead_parrot) self.assertEqual(len(tags), 1) self.assertEqual(tags[0].name, '你好') def test_unicode_tagged_object(self): self.dead_parrot.state = "dëad" self.dead_parrot.save() Tag.objects.update_tags(self.dead_parrot, 'föo') items = TaggedItem.objects.all() self.assertEqual(len(items), 1) self.assertEqual(str(items[0]), "dëad [föo]") 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.assertEqual(len(tags), 3) self.assertTrue(get_tag('bar') in tags) self.assertTrue(get_tag('baz') in tags) self.assertTrue(get_tag('foo') in tags) Tag.objects.update_tags(self.dead_parrot, None) tags = Tag.objects.get_for_object(self.dead_parrot) self.assertEqual(len(tags), 0) class TestModelTagField(TestCase): """ Test the 'tags' field on models. """ def test_create_with_tags_specified(self): f1 = FormTest.objects.create(tags='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.assertTrue(None not in (test1_tag, test2_tag, test3_tag)) self.assertEqual(len(tags), 3) self.assertTrue(test1_tag in tags) self.assertTrue(test2_tag in tags) self.assertTrue(test3_tag in tags) def test_update_via_tags_field(self): f1 = FormTest.objects.create(tags='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.assertTrue(None not in (test1_tag, test2_tag, test3_tag)) self.assertEqual(len(tags), 3) self.assertTrue(test1_tag in tags) self.assertTrue(test2_tag in tags) self.assertTrue(test3_tag in tags) f1.tags = 'test4' f1.save() tags = Tag.objects.get_for_object(f1) test4_tag = get_tag('test4') self.assertEqual(len(tags), 1) self.assertEqual(tags[0], test4_tag) f1.tags = '' f1.save() tags = Tag.objects.get_for_object(f1) self.assertEqual(len(tags), 0) def disabledtest_update_via_tags(self): # TODO: make this test working by reverting # https://github.com/Fantomas42/django-tagging/commit/bbc7f25ea471dd903f39e08684d84ce59081bdef f1 = FormTest.objects.create(tags='one two three') Tag.objects.get(name='three').delete() t2 = Tag.objects.get(name='two') t2.name = 'new' t2.save() f1again = FormTest.objects.get(pk=f1.pk) self.assertFalse('three' in f1again.tags) self.assertFalse('two' in f1again.tags) self.assertTrue('new' in f1again.tags) def test_creation_without_specifying_tags(self): f1 = FormTest() self.assertEqual(f1.tags, '') def test_creation_with_nullable_tags_field(self): f1 = FormTestNull() self.assertEqual(f1.tags, '') def test_fix_update_tag_field_deferred(self): """ Bug introduced in Django 1.10 the TagField is considered "deferred" on Django 1.10 because instance.__dict__ is not populated by the TagField instance, so it's excluded when updating a model instance. Note: this does not append if you only have one TagField in your model... """ f1 = FormMultipleFieldTest.objects.create(tagging_field='one two') self.assertEqual(f1.tagging_field, 'one two') tags = Tag.objects.get_for_object(f1) self.assertEqual(len(tags), 2) test1_tag = get_tag('one') test2_tag = get_tag('two') self.assertTrue(test1_tag in tags) self.assertTrue(test2_tag in tags) f1.tagging_field = f1.tagging_field + ' three' f1.save() self.assertEqual(f1.tagging_field, 'one two three') tags = Tag.objects.get_for_object(f1) self.assertEqual(len(tags), 3) test3_tag = get_tag('three') self.assertTrue(test3_tag in tags) f1again = FormMultipleFieldTest.objects.get(pk=f1.pk) self.assertEqual(f1again.tagging_field, 'one two three') tags = Tag.objects.get_for_object(f1again) self.assertEqual(len(tags), 3) 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.assertEqual(len(tags), 3) foo_tag = get_tag('foo') bar_tag = get_tag('bar') ter_tag = get_tag('ter') self.assertTrue(foo_tag in tags) self.assertTrue(bar_tag in tags) self.assertTrue(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.assertEqual(len(tags), 3) self.assertTrue(bar_tag in tags) self.assertTrue(baz_tag in tags) self.assertTrue(foo_tag in tags) Tag.objects.add_tag(self.dead_parrot, 'FOO') tags = Tag.objects.get_for_object(self.dead_parrot) self.assertEqual(len(tags), 3) self.assertTrue(bar_tag in tags) self.assertTrue(baz_tag in tags) self.assertTrue(foo_tag in tags) Tag.objects.add_tag(self.dead_parrot, 'Zip') tags = Tag.objects.get_for_object(self.dead_parrot) self.assertEqual(len(tags), 4) zip_tag = get_tag('zip') self.assertTrue(bar_tag in tags) self.assertTrue(baz_tag in tags) self.assertTrue(foo_tag in tags) self.assertTrue(zip_tag in tags) f1 = FormTest.objects.create() f1.tags = 'TEST5' f1.save() tags = Tag.objects.get_for_object(f1) test5_tag = get_tag('test5') self.assertEqual(len(tags), 1) self.assertTrue(test5_tag in tags) self.assertEqual(f1.tags, 'test5') class TestTagUsageForModelBaseCase(TestCase): def test_tag_usage_for_model_empty(self): self.assertEqual(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.assertEqual(len(relevant_attribute_list), 4) self.assertTrue(('bar', 3) in relevant_attribute_list) self.assertTrue(('baz', 1) in relevant_attribute_list) self.assertTrue(('foo', 2) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 3) self.assertTrue(('bar', 3) in relevant_attribute_list) self.assertTrue(('foo', 2) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 2) self.assertTrue(('foo', 1) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 4) self.assertTrue(('bar', 2) in relevant_attribute_list) self.assertTrue(('baz', 1) in relevant_attribute_list) self.assertTrue(('foo', 1) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 4) self.assertTrue(('bar', 2) in relevant_attribute_list) self.assertTrue(('baz', 1) in relevant_attribute_list) self.assertTrue(('foo', 1) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 3) self.assertTrue(('bar', 1) in relevant_attribute_list) self.assertTrue(('foo', 2) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 1) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 4) self.assertTrue(('bar', False) in relevant_attribute_list) self.assertTrue(('baz', False) in relevant_attribute_list) self.assertTrue(('foo', False) in relevant_attribute_list) self.assertTrue(('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.assertEqual(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.assertEqual(len(relevant_attribute_list), 3) self.assertTrue(('baz', 1) in relevant_attribute_list) self.assertTrue(('foo', 1) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 1) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 3) self.assertTrue('baz' in relevant_attribute_list) self.assertTrue('foo' in relevant_attribute_list) self.assertTrue('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.assertEqual(len(relevant_attribute_list), 1) self.assertTrue(('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.assertEqual(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.assertEqual(len(relevant_attribute_list), 3) self.assertTrue(('baz', 1) in relevant_attribute_list) self.assertTrue(('foo', 1) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 1) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 3) self.assertTrue('baz' in relevant_attribute_list) self.assertTrue('foo' in relevant_attribute_list) self.assertTrue('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.assertEqual(len(relevant_attribute_list), 1) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 0) class TestTagCloudForModel(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_cloud_for_model(self): tag_cloud = Tag.objects.cloud_for_model(Parrot) relevant_attribute_list = [(tag.name, tag.count, tag.font_size) for tag in tag_cloud] self.assertEqual(len(relevant_attribute_list), 4) self.assertTrue(('bar', 3, 4) in relevant_attribute_list) self.assertTrue(('baz', 1, 1) in relevant_attribute_list) self.assertTrue(('foo', 2, 2) in relevant_attribute_list) self.assertTrue(('ter', 3, 4) in relevant_attribute_list) def test_tag_cloud_for_model_filters(self): tag_cloud = Tag.objects.cloud_for_model(Parrot, filters={'state': 'no more'}) relevant_attribute_list = [(tag.name, tag.count, tag.font_size) for tag in tag_cloud] self.assertEqual(len(relevant_attribute_list), 2) self.assertTrue(('foo', 1, 1) in relevant_attribute_list) self.assertTrue(('ter', 1, 1) in relevant_attribute_list) def test_tag_cloud_for_model_min_count(self): tag_cloud = Tag.objects.cloud_for_model(Parrot, min_count=2) relevant_attribute_list = [(tag.name, tag.count, tag.font_size) for tag in tag_cloud] self.assertEqual(len(relevant_attribute_list), 3) self.assertTrue(('bar', 3, 4) in relevant_attribute_list) self.assertTrue(('foo', 2, 1) in relevant_attribute_list) self.assertTrue(('ter', 3, 4) in relevant_attribute_list) 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.assertEqual(len(parrots), 2) self.assertTrue(self.no_more_parrot in parrots) self.assertTrue(self.pining_for_the_fjords_parrot in parrots) parrots = TaggedItem.objects.get_by_model(Parrot, self.bar) self.assertEqual(len(parrots), 3) self.assertTrue(self.late_parrot in parrots) self.assertTrue(self.passed_on_parrot in parrots) self.assertTrue(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.assertEqual(len(parrots), 0) parrots = TaggedItem.objects.get_by_model(Parrot, [self.foo, self.bar]) self.assertEqual(len(parrots), 1) self.assertTrue(self.pining_for_the_fjords_parrot in parrots) parrots = TaggedItem.objects.get_by_model(Parrot, [self.bar, self.ter]) self.assertEqual(len(parrots), 2) self.assertTrue(self.late_parrot in parrots) self.assertTrue(self.passed_on_parrot in parrots) # Issue 114 - Intersection with non-existant tags parrots = TaggedItem.objects.get_intersection_by_model(Parrot, []) self.assertEqual(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.assertEqual(len(parrots), 0) parrots = TaggedItem.objects.get_by_model( Parrot, Tag.objects.filter(name__in=['foo', 'bar'])) self.assertEqual(len(parrots), 1) self.assertTrue(self.pining_for_the_fjords_parrot in parrots) parrots = TaggedItem.objects.get_by_model( Parrot, Tag.objects.filter(name__in=['bar', 'ter'])) self.assertEqual(len(parrots), 2) self.assertTrue(self.late_parrot in parrots) self.assertTrue(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.assertEqual(len(parrots), 0) parrots = TaggedItem.objects.get_by_model(Parrot, 'foo bar') self.assertEqual(len(parrots), 1) self.assertTrue(self.pining_for_the_fjords_parrot in parrots) parrots = TaggedItem.objects.get_by_model(Parrot, 'bar ter') self.assertEqual(len(parrots), 2) self.assertTrue(self.late_parrot in parrots) self.assertTrue(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.assertEqual(len(parrots), 0) parrots = TaggedItem.objects.get_by_model(Parrot, ['foo', 'bar']) self.assertEqual(len(parrots), 1) self.assertTrue(self.pining_for_the_fjords_parrot in parrots) parrots = TaggedItem.objects.get_by_model(Parrot, ['bar', 'ter']) self.assertEqual(len(parrots), 2) self.assertTrue(self.late_parrot in parrots) self.assertTrue(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.assertEqual(len(parrots), 0) def test_get_union_by_model(self): parrots = TaggedItem.objects.get_union_by_model(Parrot, ['foo', 'ter']) self.assertEqual(len(parrots), 4) self.assertTrue(self.late_parrot in parrots) self.assertTrue(self.no_more_parrot in parrots) self.assertTrue(self.passed_on_parrot in parrots) self.assertTrue(self.pining_for_the_fjords_parrot in parrots) parrots = TaggedItem.objects.get_union_by_model(Parrot, ['bar', 'baz']) self.assertEqual(len(parrots), 3) self.assertTrue(self.late_parrot in parrots) self.assertTrue(self.passed_on_parrot in parrots) self.assertTrue(self.pining_for_the_fjords_parrot in parrots) # Issue 114 - Union with non-existant tags parrots = TaggedItem.objects.get_union_by_model(Parrot, []) self.assertEqual(len(parrots), 0) parrots = TaggedItem.objects.get_union_by_model(Parrot, ['albert']) self.assertEqual(len(parrots), 0) Tag.objects.create(name='titi') parrots = TaggedItem.objects.get_union_by_model(Parrot, ['titi']) self.assertEqual(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.assertEqual(len(related_objects), 2) self.assertTrue(self.l2 in related_objects) self.assertTrue(self.l3 in related_objects) related_objects = TaggedItem.objects.get_related(self.l4, Link) self.assertEqual(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://bit.ly/1AYNEsa # ask for no more than 1 result related_objects = TaggedItem.objects.get_related(self.l1, Link, num=1) self.assertEqual(len(related_objects), 1) self.assertTrue(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.assertEqual(len(related_objects), 1) self.assertTrue(self.l2 in related_objects) def test_get_related_objects_of_different_model(self): related_objects = TaggedItem.objects.get_related(self.a1, Link) self.assertEqual(len(related_objects), 3) self.assertTrue(self.l1 in related_objects) self.assertTrue(self.l2 in related_objects) self.assertTrue(self.l3 in related_objects) Tag.objects.update_tags(self.a1, 'tag6') related_objects = TaggedItem.objects.get_related(self.a1, Link) self.assertEqual(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.assertEqual(len(relevant_attribute_list), 2) self.assertTrue(('foo', 1) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 4) self.assertTrue(('bar', 2) in relevant_attribute_list) self.assertTrue(('baz', 1) in relevant_attribute_list) self.assertTrue(('foo', 1) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 4) self.assertTrue(('bar', 2) in relevant_attribute_list) self.assertTrue(('baz', 1) in relevant_attribute_list) self.assertTrue(('foo', 1) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 3) self.assertTrue(('bar', 1) in relevant_attribute_list) self.assertTrue(('foo', 2) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 1) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 4) self.assertTrue(('bar', False) in relevant_attribute_list) self.assertTrue(('baz', False) in relevant_attribute_list) self.assertTrue(('foo', False) in relevant_attribute_list) self.assertTrue(('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.assertEqual(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.assertEqual(len(relevant_attribute_list), 3) self.assertTrue(('bar', 2) in relevant_attribute_list) self.assertTrue(('foo', 1) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 1) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 3) self.assertTrue(('bar', False) in relevant_attribute_list) self.assertTrue(('foo', False) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 3) self.assertTrue(('bar', 2) in relevant_attribute_list) self.assertTrue(('foo', 2) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 1) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 2) self.assertTrue(('foo', 1) in relevant_attribute_list) self.assertTrue(('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.assertEqual(len(relevant_attribute_list), 2) self.assertTrue(('bar', 1) in relevant_attribute_list) self.assertTrue(('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 fields = forms.ALL_FIELDS form = TestForm() self.assertEqual(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.assertEqual(edit_string_for_tags([plain]), 'plain') self.assertEqual(edit_string_for_tags([spaces]), '"spa ces"') self.assertEqual(edit_string_for_tags([plain, spaces]), 'plain, spa ces') self.assertEqual(edit_string_for_tags([plain, spaces, comma]), 'plain, spa ces, "com,ma"') self.assertEqual(edit_string_for_tags([plain, comma]), 'plain "com,ma"') self.assertEqual(edit_string_for_tags([comma, spaces]), '"com,ma", spa ces') def test_tag_d_validation(self): t = TagField(required=False) self.assertEqual(t.clean(''), '') self.assertEqual(t.clean('foo'), 'foo') self.assertEqual(t.clean('foo bar baz'), 'foo bar baz') self.assertEqual(t.clean('foo,bar,baz'), 'foo,bar,baz') self.assertEqual(t.clean('foo, bar, baz'), 'foo, bar, baz') self.assertEqual( t.clean('foo qwertyuiopasdfghjklzxcvbnm' 'qwertyuiopasdfghjklzxcvb bar'), 'foo qwertyuiopasdfghjklzxcvbnmqwertyuiopasdfghjklzxcvb bar') self.assertRaises( forms.ValidationError, t.clean, 'foo qwertyuiopasdfghjklzxcvbnmqwertyuiopasdfghjklzxcvbn bar') def test_tag_get_from_model(self): FormTest.objects.create(tags='test3 test2 test1') FormTest.objects.create(tags='toto titi') self.assertEquals(FormTest.tags, 'test1 test2 test3 titi toto') ######### # Forms # ######### class TestTagAdminForm(TestCase): def test_clean_name(self): datas = {'name': 'tag'} form = TagAdminForm(datas) self.assertTrue(form.is_valid()) def test_clean_name_multi(self): datas = {'name': 'tag error'} form = TagAdminForm(datas) self.assertFalse(form.is_valid()) def test_clean_name_too_long(self): datas = {'name': 't' * (settings.MAX_TAG_LENGTH + 1)} form = TagAdminForm(datas) self.assertFalse(form.is_valid()) ######### # Views # ######### @override_settings( ROOT_URLCONF='tagging.tests.urls', TEMPLATES=[ { 'BACKEND': 'django.template.backends.django.DjangoTemplates', 'OPTIONS': { 'loaders': ('tagging.tests.utils.VoidLoader',) } } ] ) class TestTaggedObjectList(TestCase): def setUp(self): self.a1 = Article.objects.create(name='article 1') self.a2 = Article.objects.create(name='article 2') Tag.objects.update_tags(self.a1, 'static tag test') Tag.objects.update_tags(self.a2, 'static test') def get_view(self, url, queries=1, code=200, expected_items=1, friendly_context='article_list', template='tests/article_list.html'): with self.assertNumQueries(queries): response = self.client.get(url) self.assertEquals(response.status_code, code) if code == 200: self.assertTrue(isinstance(response.context['tag'], Tag)) self.assertEqual(len(response.context['object_list']), expected_items) self.assertEqual(response.context['object_list'], response.context[friendly_context]) self.assertTemplateUsed(response, template) return response def test_view_static(self): self.get_view('/static/', expected_items=2) def test_view_dynamic(self): self.get_view('/tag/', expected_items=1) def test_view_related(self): response = self.get_view('/static/related/', queries=2, expected_items=2) self.assertEquals(len(response.context['related_tags']), 2) def test_view_no_queryset_no_model(self): self.assertRaises(ImproperlyConfigured, self.get_view, '/no-query-no-model/') def test_view_no_tag(self): self.assertRaises(AttributeError, self.get_view, '/no-tag/') def test_view_404(self): self.get_view('/unavailable/', code=404) django-tagging-0.5.0/tagging/tests/urls.py000066400000000000000000000011571363050730000205160ustar00rootroot00000000000000"""Test urls for tagging.""" from django.conf.urls import url from tagging.tests.models import Article from tagging.views import TaggedObjectList class StaticTaggedObjectList(TaggedObjectList): tag = 'static' queryset = Article.objects.all() urlpatterns = [ url(r'^static/$', StaticTaggedObjectList.as_view()), url(r'^static/related/$', StaticTaggedObjectList.as_view( related_tags=True)), url(r'^no-tag/$', TaggedObjectList.as_view(model=Article)), url(r'^no-query-no-model/$', TaggedObjectList.as_view()), url(r'^(?P[^/]+(?u))/$', TaggedObjectList.as_view(model=Article)), ] django-tagging-0.5.0/tagging/tests/utils.py000066400000000000000000000011741363050730000206700ustar00rootroot00000000000000""" Tests utils for tagging. """ from django.template import Origin from django.template.loaders.base import Loader class VoidLoader(Loader): """ Template loader which is always returning an empty template. """ is_usable = True _accepts_engine_in_init = True def get_template_sources(self, template_name): yield Origin( name='voidloader', template_name=template_name, loader=self) def get_contents(self, origin): return '' def load_template_source(self, template_name, template_dirs=None): return ('', 'voidloader:%s' % template_name) django-tagging-0.5.0/tagging/utils.py000066400000000000000000000207321363050730000175270ustar00rootroot00000000000000""" Tagging utilities - from user tag input parsing to tag cloud calculation. """ import math from django.db.models.query import QuerySet from django.utils.encoding import force_str from django.utils.translation import gettext as _ # Font size distribution algorithms LOGARITHMIC, LINEAR = 1, 2 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_str(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 ',' not in input and '"' not in input: words = list(set(split_strip(input, ' '))) 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 = next(i) if c == '"': if buffer: to_be_split.append(''.join(buffer)) buffer = [] # Find the matching quote open_quote = True c = next(i) while c != '"': buffer.append(c) c = next(i) if buffer: word = ''.join(buffer).strip() if word: words.append(word) buffer = [] open_quote = False else: if not saw_loose_comma and c == ',': 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 ',' in buffer: saw_loose_comma = True to_be_split.append(''.join(buffer)) if to_be_split: if saw_loose_comma: delimiter = ',' else: delimiter = ' ' 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=','): """ Splits ``input`` on ``delimiter``, stripping each resulting string and returning a list of non-empty strings. """ 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 ',' in name: names.append('"%s"' % name) continue elif ' ' in name: if not use_commas: use_commas = True names.append(name) if use_commas: glue = ', ' else: glue = ' ' result = glue.join(names) # If we only had one name, and it had spaces, # we need to enclose it in quotes. # Otherwise, it's interpreted as two tags. if len(names) == 1 and use_commas: result = '"' + result + '"' return result 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, str): return Tag.objects.filter(name__in=parse_tag_input(tags)) elif isinstance(tags, (list, tuple)): if len(tags) == 0: return tags contents = set() for item in tags: if isinstance(item, str): contents.add('string') elif isinstance(item, Tag): contents.add('tag') elif isinstance(item, int): contents.add('int') if len(contents) == 1: if 'string' in contents: return Tag.objects.filter(name__in=[force_str(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, str): return Tag.objects.get(name=tag) elif isinstance(tag, int): return Tag.objects.get(id=tag) except Tag.DoesNotExist: pass return None 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. http://www.artweb-design.de/projects/mephisto-plugin-tag-cloud """ if distribution == LINEAR or max_weight == 1: return weight elif distribution == LOGARITHMIC: return min( math.log(weight) * max_weight / math.log(max_weight), 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 django-tagging-0.5.0/tagging/views.py000066400000000000000000000052771363050730000175330ustar00rootroot00000000000000""" Tagging related views. """ from django.core.exceptions import ImproperlyConfigured from django.http import Http404 from django.utils.translation import gettext as _ from django.views.generic.list import ListView from tagging.models import Tag from tagging.models import TaggedItem from tagging.utils import get_queryset_and_model from tagging.utils import get_tag class TaggedObjectList(ListView): """ A thin wrapper around ``django.views.generic.list.ListView`` 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. """ tag = None related_tags = False related_tag_counts = True def get_tag(self): if self.tag is None: try: self.tag = self.kwargs.pop('tag') except KeyError: raise AttributeError( _('TaggedObjectList must be called with a tag.')) tag_instance = get_tag(self.tag) if tag_instance is None: raise Http404(_('No Tag found matching "%s".') % self.tag) return tag_instance def get_queryset_or_model(self): if self.queryset is not None: return self.queryset elif self.model is not None: return self.model else: raise ImproperlyConfigured( "%(cls)s is missing a QuerySet. Define " "%(cls)s.model, %(cls)s.queryset, or override " "%(cls)s.get_queryset_or_model()." % { 'cls': self.__class__.__name__ } ) def get_queryset(self): self.queryset_or_model = self.get_queryset_or_model() self.tag_instance = self.get_tag() return TaggedItem.objects.get_by_model( self.queryset_or_model, self.tag_instance) def get_context_data(self, **kwargs): context = super(TaggedObjectList, self).get_context_data(**kwargs) context['tag'] = self.tag_instance if self.related_tags: queryset, model = get_queryset_and_model(self.queryset_or_model) context['related_tags'] = Tag.objects.related_for_model( self.tag_instance, model, counts=self.related_tag_counts) return context django-tagging-0.5.0/versions.cfg000066400000000000000000000021021363050730000167150ustar00rootroot00000000000000[versions] asgiref = 3.2.3 blessings = 1.7 buildout-versions-checker = 1.10.0 certifi = 2019.11.28 chardet = 3.0.4 configparser = 4.0.2 coverage = 5.0.3 django = 3.0.4 entrypoints = 0.3 enum34 = 1.1.9 flake8 = 3.7.9 futures = 3.3.0 idna = 2.9 mccabe = 0.6.1 nose = 1.3.7 nose-progressive = 1.5.2 nose-sfd = 0.4 packaging = 20.3 pbp.recipe.noserunner = 0.2.6 pycodestyle = 2.5.0 pyflakes = 2.1.1 pyparsing = 2.4.6 python-coveralls = 2.9.3 pytz = 2019.3 PyYAML = 5.3 requests = 2.23.0 six = 1.14.0 sqlparse = 0.3.1 urllib3 = 1.25.8 zc.recipe.egg = 2.0.7