Introduction

Features

  • Easy to install - simple requirements, simple syntax, lots of options

  • Based on ForeignKey and ManyToManyField, so it’s easy to query

  • Autocomplete support built in, if you want it

  • Supports multiple independent fields on a single model

  • Supports trees of nested tags, for detailed categorisation

  • Admin support for managing tags and tagged models

See <comparison> for a comparison with other tagging libraries.

Quickstart

Install with pip install django-tagulous, add tagulous to Django’s INSTALLED_APPS and define the serializers, then start adding tag fields to your model:

from django.db import models
from tagulous.models import SingleTagField, TagField

class Person(models.Model):
    name = models.CharField(max_length=255)
    title = SingleTagField(initial="Mr, Mrs, Miss, Ms")
    skills = TagField()

A SingleTagField is based on a ForeignKey, and a TagField is based on a ManyToManyField.

They have relationships to a TagModel, which is automatically created for you if you don’t specify one.

Assign strings to the fields to create new tags:

myperson = Person.objects.create(name='Bob', title='Mr', skills='run, hop')
# myperson.skills == 'run, hop'
myperson.skills = ['jump', 'kung fu']
myperson.save()
# myperson.skills == 'jump, "kung fu"'
runners = Person.objects.filter(skills='run')

Use them like a normal Django relationship in your queries:

qs = MyRelatedModel.objects.filter(
    person__skills__name__in=['run', 'jump'],
)

As well as this you also get:

  • tag field support in public forms and the admin site, including autocompletion

  • easy to build tag clouds

  • ability to nest tags in trees for more complex categorisation

Take a look at the Example Usage to see what else you can do, or read on through the documentation to see exactly how everything works.

Glossary

This documentation uses a few terms to explain the ways tags are stored and set:

Tagged model

A model which has been tagged using Model Fields.

Tag model

A model where the tag definition is stored. It must be a subclass of tagulous.models.TagModel, but will be auto-generated by a tag field if it is not explicitly set.

Tag

An instance of a tag model

Tag name

The unique name of a tag, eg "run". This is the value stored on the name attribute of a tag model.

Tag string

A tag string is a list of tag names stored in a single string, in tag format, eg "run, jump, hop". The format of this string is defined by the Tag String Parser.