Merge branch 'suggest'

AUTHORS.txt

@@ -7,3 +7,4 @@ fakeempire <adam@fakeempire.com>
 Ben Firshman <ben@firshman.co.uk>
 Alex Gaynor <alex.gaynor@gmail.com>
 Rob Hudson <rob@cogit8.org>
+Frank Wiles

README.txt

@@ -3,19 +3,19 @@ django-taggit
 
 ``django-taggit`` a simpler approach to tagging with Django.  Add it to your
 ``INSTALLED_APPS` then just add a TaggableManager to your model and go:
-    
+
     from django.db import models
-    
+
     from taggit.managers import TaggableManager
-    
+
     class Food(models.Model):
         # ... fields here
-        
+
         tags = TaggableManager()
-    
+
 
 Then you can use the API like so:
-    
+
     >>> apple = Food.objects.create(name="apple")
     >>> apple.tags.add("red", "green", "delicious")
     >>> apple.tags.all()
@@ -27,3 +27,5 @@ Then you can use the API like so:
 
 
 Tags will show up for you automatically in forms and the admin.
+
+``django-taggit`` requires Django 1.1 or greater.

taggit/contrib/suggest/README.txt

+taggit.contrib.suggest
+======================
+
+This add on module allows you to easily associate keywords and regular
+expressions with a Tag object. This is useful to help keep your database
+getting filled up with several similar tags that really represent the same
+thing.
+
+For example, if your site is a humor site you might want to collapse all of
+#fun, #funny, #funnies, #hilarious, #rofl, and #lol into one tag #funny.  The
+``suggest_tags()`` function in ``taggit.contrib.suggest.utils`` will give you a
+list of tags that seem appropriate for the text content given to it.
+
+Unlike the rest of ``django-taggit``, ``suggest`` requires Django 1.2.
+
+Usage
+=====
+
+Put ``'taggit.contrib.suggest'`` into ``INSTALLED_APPS`` and run a syncdb to
+create the necessary models.  This will add ``Keywords`` and
+``Regular Expression`` inlines to the default ``django-taggit`` admin.  Once
+you've populated those based on your site you can do a simple:
+
+.. sourcecode:: python
+
+    from taggit.contrib.suggest.utils import suggest_tags
+
+    tags = suggest_tags(content='Some textual content...')
+
+
+TODO
+====
+
+* In a later version I hope to a simple way to help determine keywords for you
+  automatically, by learning from your past tags and content.

taggit/contrib/suggest/admin.py

+from django.contrib import admin
+
+from taggit.admin import TaggedItemInline
+from taggit.contrib.suggest.models import TagKeyword, TagRegex
+from taggit.models import Tag
+
+
+class TagKeywordInline(admin.StackedInline):
+    model = TagKeyword
+
+
+class TagRegxInline(admin.StackedInline):
+    model = TagRegex
+
+
+class TagSuggestAdmin(admin.ModelAdmin):
+    inlines = [
+        TaggedItemInline,
+        TagKeywordInline,
+        TagRegxInline,
+    ]
+
+
+admin.site.unregister(Tag)
+admin.site.register(Tag, TagSuggestAdmin)

taggit/contrib/suggest/models.py

+import re
+
+from django.core.exceptions import ValidationError
+from django.db import models
+
+from taggit.models import Tag
+
+try:
+    import Stemmer
+except ImportError:
+    Stemmer = None
+
+
+class TagKeyword(models.Model):
+    """ Model to associate simple keywords to a Tag """
+    tag = models.ForeignKey(Tag, related_name='keywords')
+    keyword = models.CharField(max_length=30)
+    stem = models.CharField(max_length=30)
+
+    def __unicode__(self):
+        return "Keyword '%s' for Tag '%s'" % (self.keyword, self.tag.name)
+
+    def save(self, *args, **kwargs):
+        """ Stem the keyword on save if they have PyStemmer """
+        language = kwargs.pop('stemmer-language', 'english')
+        if not self.pk and not self.stem and Stemmer:
+            stemmer = Stemmer.Stemmer(language)
+            self.stem = stemmer.stemWord(self.keyword)
+        super(TagKeyword, self).save(*args, **kwargs)
+
+
+def validate_regex(value):
+    """ Make sure we have a valid regular expression """
+    try:
+        re.compile(value)
+    except Exception:
+        raise ValidationError('Please enter a valid regular expression')
+
+
+class TagRegex(models.Model):
+    """ Model to associate regular expressions with a Tag """
+    tag = models.ForeignKey(Tag, related_name='regexes')
+    name = models.CharField(max_length=30)
+    regex = models.CharField(
+        max_length=250,
+         validators=[validate_regex],
+         help_text=('Enter a valid Regular Expression. To make it '
+            'case-insensitive include "(?i)" in your expression.')
+     )
+
+    def __unicode__(self):
+        return self.name
+
+    def save(self, *args, **kwargs):
+        """ Make sure to validate """
+        self.full_clean()
+        super(TagRegex,self).save(*args, **kwargs)

taggit/contrib/suggest/tests/__init__.py

+from taggit.contrib.suggest.tests.tests import SuggestCase

taggit/contrib/suggest/tests/settings.py

+DATABASE_ENGINE = 'sqlite3'
+
+INSTALLED_APPS = [
+    'django.contrib.contenttypes',
+    'taggit',
+    'taggit.tests',
+    'taggit.contrib.suggest',
+]

taggit/contrib/suggest/tests/tests.py

+from django.core.exceptions import ValidationError
+from django.test import TestCase
+
+from taggit.contrib.suggest.models import TagKeyword, TagRegex
+from taggit.contrib.suggest.utils import suggest_tags
+from taggit.models import Tag
+
+
+class SuggestCase(TestCase):
+    def test_simple_suggest(self):
+        ku_tag = Tag.objects.create(name='ku')
+        ku_keyword1 = TagKeyword.objects.create(
+            tag=ku_tag,
+            keyword='kansas university'
+        )
+
+        suggested_tags = suggest_tags('I used to be a student at kansas university')
+        self.assertTrue(ku_tag in suggested_tags)
+
+    def test_regex_suggest(self):
+        ku_tag = Tag.objects.create(name='ku')
+        TagRegex.objects.create(
+            tag=ku_tag,
+            name='Find University of Kansas',
+            regex='University\s+of\s+Kansas'
+        )
+
+        suggested_tags = suggest_tags('I was once a student at the University of Kansas')
+
+        self.assertTrue(ku_tag in suggested_tags)
+
+    def test_bad_regex(self):
+        ku_tag = Tag.objects.create(name='ku')
+        ku_keyword1 = TagKeyword.objects.create(
+            tag=ku_tag,
+            keyword='kansas university'
+        )
+        new_regex = TagRegex(
+            tag=ku_tag,
+            name='Find University of Kansas',
+            regex='University\s+of(\s+Kansas'
+        )
+        self.assertRaises(ValidationError, new_regex.save)
+
+        suggested_tags = suggest_tags('I was once a student at the University '
+            'of Kansas. Also known as kansas university by the way.')
+
+        self.assertTrue(ku_tag in suggested_tags)

taggit/contrib/suggest/utils.py

+import re
+
+from django.conf import settings
+
+from taggit.contrib.suggest.models import TagKeyword, TagRegex
+from taggit.models import Tag
+
+
+def _suggest_keywords(content):
+    """ Suggest by keywords """
+    suggested_keywords = set()
+    keywords = TagKeyword.objects.all()
+
+    for k in keywords:
+        # Use the stem if available, otherwise use the whole keyword
+        if k.stem:
+            if k.stem in content:
+                suggested_keywords.add(k.tag_id)
+        elif k.keyword in content:
+            suggested_keywords.add(k.tag_id)
+
+    return suggested_keywords
+
+def _suggest_regexes(content):
+    """ Suggest by regular expressions """
+    # Grab all regular expressions and compile them
+    suggested_regexes = set()
+    regex_keywords = TagRegex.objects.all()
+
+    # Look for our regular expressions in the content
+    for r in regex_keywords:
+        if re.search(r.regex, content):
+            suggested_regexes.add(r.tag_id)
+
+    return suggested_regexes
+
+def suggest_tags(content):
+    """ Suggest tags based on text content """
+    suggested_keywords = _suggest_keywords(content)
+    suggested_regexes  = _suggest_regexes(content)
+    suggested_tag_ids  = suggested_keywords | suggested_regexes
+
+    return Tag.objects.filter(id__in=suggested_tag_ids)