Tagging and Categorization

In etchblok-test-api, tags provide a flexible way to organize bookmarks beyond fixed collections. The tagging system is built around the Tag model and the TagColor enumeration, allowing you to label, color-code, and track the popularity of different categories.

The Tag Model

A Tag is a lightweight label identified by a unique 8-character hex ID. Beyond its name, it stores visual metadata and a usage counter.

from app.models.tag import Tag, TagColor

# Create a basic tag
tag = Tag(name="Research", color=TagColor.BLUE, description="Academic papers and articles")

print(tag.id)           # e.g., 'a1b2c3d4'
print(tag.usage_count)  # 0

The Tag class (found in app/models/tag.py) uses a field factory to automatically generate a unique ID if one isn't provided during initialization.

Creating and Validating Tags

When you create or rename a tag, etchblok-test-api enforces several constraints to ensure data integrity and prevent conflicts with system-reserved keywords.

Validation Rules

The _validate_tag_name function in app/models/_validators.py enforces the following:

• Length: Names must be between 1 and 50 characters.
• Reserved Names: You cannot use names that conflict with system views: all, untagged, archived, or trash.
• Uniqueness: While the model doesn't enforce uniqueness itself, the BookmarkService and BookmarkRepository ensure tag names are unique per user (case-insensitive).

Renaming Tags

To change a tag's name, use the rename() method. This method performs basic validation (checking for empty strings or excessive length) before updating the attribute.

tag = Tag(name="Old Name")
try:
    tag.rename("New Project Name")
except ValueError as e:
    print(f"Validation failed: {e}")

Visual Customization with TagColor

To help distinguish tags in a UI, etchblok-test-api provides a set of preset colors via the TagColor enum.

Color	Value
TagColor.RED	"red"
TagColor.BLUE	"blue"
TagColor.GREEN	"green"
TagColor.YELLOW	"yellow"
TagColor.PURPLE	"purple"
TagColor.GRAY	"gray" (Default)

You can update a tag's color by assigning a new enum value:

tag.color = TagColor.PURPLE

Tracking Tag Usage

The Tag model tracks how many bookmarks are currently associated with it via the usage_count attribute. This is managed through two explicit methods:

• increment_usage(): Increases the count by 1.
• decrement_usage(): Decreases the count by 1, ensuring it never drops below 0.

tag.increment_usage() # returns 1
tag.increment_usage() # returns 2
tag.decrement_usage() # returns 1

In the BookmarkService, when a tag is deleted via delete_tag(tag_id), the service automatically iterates through all bookmarks containing that tag and removes the reference before deleting the tag itself from the repository.

Serialization and Sorting

JSON Serialization

The Tag class provides to_dict() and from_dict() methods for easy conversion to and from JSON-safe formats, which is used by the API routes in app/routes/tags.py.

# Convert to dict for API response
data = tag.to_dict()
# {
#   "id": "...",
#   "name": "Research",
#   "color": "blue",
#   "description": "...",
#   "usage_count": 1
# }

# Reconstruct from dict
new_tag = Tag.from_dict(data)

Alphabetical Sorting

The Tag class implements the __lt__ (less than) dunder method, which allows lists of tags to be sorted alphabetically by name (case-insensitive).

tags = [Tag(name="Zebra"), Tag(name="Apple")]
sorted_tags = sorted(tags) # [Tag(name='Apple', ...), Tag(name='Zebra', ...)]

This sorting logic is utilized in the GET /api/tags/ endpoint to provide a consistent, ordered list of labels to the user.