Introducing Tagulous

Tagulous is a tagging library for Django which is based on ManyToManyField and ForeignKey relationships. I've been developing and using it internally for several years, and have recently tidied it up for release; it supports Django 1.4 to 1.9a, on Python 2.7 to 3.5.

It started with a simple enough idea - rather than use generic relations like other tagging libraries, use a subclass of ManyToManyField which supports assignment using tag strings, to allow things like this:

class Person(models.Model):
  name = models.CharField(max_length=255)
  skills = TagField()

person = Person.objects.create(name='Bob', skills='run, jump')
person.skills = 'run, "kung fu", jump'

And because the underlying relationship is a ManyToManyField, you can build queries exactly as you would expect:

runners = Person.objects.filter(skills='run')
user_skills = Pet.skills.tag_model.objects.filter(pet__owner=request.user)

In this example the related tag model is generated automatically (and accessible on field.tag_model), but you can create custom tag models and share them between fields if you prefer. See the usage examples for more examples of how you can use Tagulous.

The first version wasn't particularly complex, but as I started using it more it quickly became a more substantial project, with admin support, integrated autocomplete, support for hierarchical trees, and a ForeignKey version - a SingleTagField which essentially operates as a CharField with a list of choices which can be customised by users at runtime.

It has a comprehensive set of tests, and has been in use for several years on several projects, so I'm reasonably confident that it's stable and the API won't need to be changed significantly now. That said, I'm releasing it as a beta version until it's been out in the wild for a bit - so please give it a try, and let me know how you get on.

Tagulous is available on pypi and github, and this site hosts the documentation and a demo of the front-end.

Leave a comment