Django Tagulous

Tagulous is designed as a more feature-rich and performant alternative to django-taggit and django-tagging. Key differentiators include:

• Native Relations: Unlike the generic relations used by other libraries, Tagulous uses ManyToManyField for its TagField, making it a first-class citizen in Django with faster, simpler queries.
• Tag Model Flexibility: Supports independent or shared tag models, allowing multiple TagField instances on a single model to have distinct tag sets. It also supports custom tag models to store extra metadata.
• Configuration: Offers granular control over tag behavior, including case sensitivity, forced lowercase, maximum tag counts, and custom delimiters (e.g., space vs. comma).
• Autocomplete: Provides built-in autocomplete support via Select2 and AJAX views, with integrated Python/JavaScript parsers to ensure consistent tag string handling.
• Admin Integration: Tag fields are fully integrated into the Django admin, supporting list_display, filtering, and specialized tools for renaming or merging tags.
• Specialized Field Types: Includes SingleTagField (based on ForeignKey) for single-selection tagging and hierarchical tree support for sub-tags.

By setting tree=True on a TagField, you can use slashes (/) in tag names to denote parent-child relationships (e.g., food/eating).

Requirements:

1. The TagField must have tree=True.
2. The target tag model must subclass tagulous.models.TagTreeModel instead of TagModel.

Tree Operations:

• Root nodes: Filter where parent=None.
• Children: Use the .children.all() property on a tag instance.
• Descendants: Use the .get_descendants() method on a tag instance to get all nodes in the subtree.

import tagulous.models

class Person(models.Model):
    name = models.CharField(max_length=255)
    skills = tagulous.models.TagField(
        force_lowercase=True,
        max_count=5,
        tree=True,
    )

class Hobbies(tagulous.models.TagTreeModel):
    class TagMeta:
        initial = "food/eating, food/cooking, gaming/football"
        force_lowercase = True
        autocomplete_view = 'myapp.views.hobbies_autocomplete'

class Person(models.Model):
    name = models.CharField(max_length=255)
    hobbies = tagulous.models.TagField(to=Hobbies)

# Usage
person.hobbies = "food/eating/mexican, sport/football"
person.save()

# Querying
root_nodes = Hobbies.objects.filter(parent=None)
food_children = Hobbies.objects.get(name="food").children.all()
descendants = Hobbies.objects.get(name="food").get_descendants()

A tagged model is a Django model that contains tag fields. By default, Tagulous automatically enhances your models to support advanced tagging features.

Automatic Enhancement

If TAGULOUS_ENHANCE_MODELS = True (the default), Tagulous listens for the class_prepared signal. When a model with tag fields is constructed, Tagulous dynamically injects the following into your model's hierarchy:

• tagulous.models.TaggedModel as the base class.
• tagulous.models.TaggedManager as the base class for your manager.
• tagulous.models.TaggedQuerySet as the base class for your querysets.

When this happens, you may notice your manager and queryset classes are prefixed with CastTagged (e.g., CastTaggedMyModelManager), indicating they have been automatically cast to their tagged equivalents.

Core Abstractions

• tagulous.models.TaggedModel: The base class for tagged models. It enables passing TagField values as keywords in the model constructor.
• tagulous.models.TaggedManager: The base class for managers, ensuring querysets are subclasses of TaggedQuerySet.
• tagulous.models.TaggedQuerySet: The base class for querysets. It enables get(), filter(), and exclude() to accept tag strings, and create()/get_or_create() to accept both strings and TagField values. It also provides similarity searching.

Tags can be organized into hierarchical structures using Tag Trees. In a tree, tags have parents, children, and siblings.

Hierarchy Syntax

• Nesting: Use the forward slash (/) to denote hierarchy. For example, Animal/Mammal/Cat represents a Cat whose parent is Mammal and grandparent is Animal.
• Escaping Slashes: To include a literal forward slash in a tag name, escape it with a second slash. For example, Animal/Vegetable is written as Animal//Vegetable.

Implementation

To use tag trees, your tag model must subclass tagulous.models.TagTreeModel instead of the standard tagulous.models.TagModel. If you are using automatically-generated tag models, set the tree field option to True in your model definition.

# Example of setting the tree option for auto-generated models
# (Conceptual, as the specific syntax depends on how you define your model)
class MyModel(models.Model):
    tags = TagulousField(tree=True)

Django Tagulous works by intercepting model field definitions to provide advanced tagging capabilities:

• Field Initialization: Tag model fields (defined in tagulous/models/fields.py) use the contribute_to_class method to add descriptors (from tagulous/models/descriptors.py) to the model. These descriptors act as getters/setters that interface with managers in tagulous/models/managers.py.
• Tagged Models: For full support in constructors and querysets, models should use base classes from tagulous/models/tagged.py. This module includes a class_prepared signal listener that dynamically updates base classes for models containing tag fields.
• Configuration: Field arguments are stored in a TagOptions instance (tagulous/models/options.py). Initial tags can be loaded via tagulous/models/initial.py or the initial_tags management command.
• Forms & UI: When a ModelForm is created, the field's formfield method generates a tag form field (tagulous/forms.py) using TagOptions. This field utilizes tag widgets to render HTML.
• Utilities: Tag string parsing and joining are handled by tagulous/utils.py.
• Admin: The admin interface is enhanced in tagulous/admin.py through two mechanisms: registration (adding tag functionality to standard ModelAdmin) and tag model admin (for managing the tags themselves).