0
# Tag Operations
1

2
Methods for adding, removing, querying, and managing tags on model instances. These operations are available through the TaggableManager and provide comprehensive functionality for tag manipulation and retrieval.
3

4
## Capabilities
5

6
### Adding Tags
7

8
Add one or more tags to a model instance, with support for both string tags and Tag objects.
9

10
```python { .api }
11
def add(*tags, through_defaults=None, tag_kwargs=None, **kwargs):
12
    """
13
    Add tags to the instance.
14
    
15
    Parameters:
16
    - *tags: Tag names (strings) or Tag objects to add
17
    - through_defaults (dict): Default values for through model fields
18
    - tag_kwargs (dict): Additional parameters for tag creation
19
    - **kwargs: Additional parameters passed to tag creation
20
    
21
    Returns:
22
    None
23
    """
24
```
25

26
```python
27
# Add string tags
28
article.tags.add("python", "django", "web development")
29

30
# Add Tag objects
31
python_tag = Tag.objects.get(name="python")
32
article.tags.add(python_tag)
33

34
# Mix strings and Tag objects
35
article.tags.add("javascript", python_tag, "tutorial")
36

37
# Add with through model defaults (for custom through models)
38
article.tags.add("featured", through_defaults={'priority': 5})
39

40
# Add with tag creation parameters
41
article.tags.add("Python", tag_kwargs={'slug': 'python-lang'})
42
```
43

44
### Removing Tags
45

46
Remove specific tags from a model instance.
47

48
```python { .api }
49
def remove(*tags):
50
    """
51
    Remove tags from the instance.
52
    
53
    Parameters:
54
    - *tags: Tag names (strings) to remove
55
    
56
    Returns:
57
    None
58
    """
59
```
60

61
```python
62
# Remove specific tags
63
article.tags.remove("outdated", "deprecated")
64

65
# Remove single tag
66
article.tags.remove("draft")
67
```
68

69
### Clearing Tags
70

71
Remove all tags from a model instance.
72

73
```python { .api }
74
def clear():
75
    """
76
    Remove all tags from the instance.
77
    
78
    Returns:
79
    None
80
    """
81
```
82

83
```python
84
# Remove all tags
85
article.tags.clear()
86
```
87

88
### Setting Tags
89

90
Replace all existing tags with a new set of tags.
91

92
```python { .api }
93
def set(tags, *, through_defaults=None, **kwargs):
94
    """
95
    Set the instance's tags to the given tags, replacing all existing tags.
96
    
97
    Parameters:
98
    - tags: List of tag names (strings) or Tag objects
99
    - through_defaults (dict): Default values for through model fields
100
    - clear (bool): Whether to clear existing tags first (default: False)
101
    - tag_kwargs (dict): Additional parameters for tag creation
102
    
103
    Returns:
104
    None
105
    """
106
```
107

108
```python
109
# Replace all tags with new set
110
article.tags.set(["python", "tutorial", "beginner"])
111

112
# Clear and set (explicit clear)
113
article.tags.set(["advanced", "expert"], clear=True)
114

115
# Set with through model defaults
116
article.tags.set(["featured"], through_defaults={'priority': 10})
117
```
118

119
### Querying Tags
120

121
Retrieve tags associated with an instance in various formats.
122

123
```python { .api }
124
def all():
125
    """
126
    Get all tags for this instance as a QuerySet.
127
    
128
    Returns:
129
    QuerySet: QuerySet of Tag objects
130
    """
131

132
def names():
133
    """
134
    Get tag names as a list of strings.
135
    
136
    Returns:
137
    list: List of tag names as strings
138
    """
139

140
def slugs():
141
    """
142
    Get tag slugs as a list of strings.
143
    
144
    Returns:
145
    list: List of tag slugs as strings
146
    """
147

148
def values_list(*fields, flat=False):
149
    """
150
    Get tag field values as a list.
151
    
152
    Parameters:
153
    - *fields: Field names to retrieve
154
    - flat (bool): If True and only one field, return flat list
155
    
156
    Returns:
157
    list: List of tuples or flat list if flat=True
158
    """
159

160
def get_queryset(extra_filters=None):
161
    """
162
    Get the base queryset for tags.
163
    
164
    Parameters:
165
    - extra_filters (dict): Additional filter conditions
166
    
167
    Returns:
168
    QuerySet: Filtered tag queryset
169
    """
170
```
171

172
```python
173
# Get all tags as QuerySet
174
all_tags = article.tags.all()
175
for tag in all_tags:
176
    print(tag.name, tag.slug)
177

178
# Get just tag names
179
tag_names = article.tags.names()
180
# Returns: ['python', 'django', 'tutorial']
181

182
# Get tag slugs
183
tag_slugs = article.tags.slugs()
184
# Returns: ['python', 'django', 'tutorial']
185

186
# Get specific field values
187
tag_ids = article.tags.values_list('id', flat=True)
188
# Returns: [1, 5, 12]
189
```
190

191
### Most Common Tags
192

193
Find the most frequently used tags, with optional filtering and minimum count requirements.
194

195
```python { .api }
196
def most_common(min_count=None, extra_filters=None):
197
    """
198
    Get tags ordered by usage frequency.
199
    
200
    Parameters:
201
    - min_count (int): Minimum number of times tag must be used
202
    - extra_filters (dict): Additional filters to apply
203
    
204
    Returns:
205
    QuerySet of tags annotated with 'num_times' field
206
    """
207
```
208

209
```python
210
# Get most common tags for this instance's model
211
common_tags = Article.tags.most_common()
212
for tag in common_tags:
213
    print(f"{tag.name}: {tag.num_times} times")
214

215
# Minimum usage count
216
popular_tags = Article.tags.most_common(min_count=5)
217

218
# With additional filtering
219
recent_common = Article.tags.most_common(
220
    extra_filters={'tagged_items__content_object__created_at__gte': last_month}
221
)
222
```
223

224
### Similar Objects
225

226
Find objects that share tags with the current instance.
227

228
```python { .api }
229
def similar_objects():
230
    """
231
    Find objects that share tags with this instance.
232
    
233
    Returns:
234
    List of objects with 'similar_tags' attribute indicating shared tag count
235
    """
236
```
237

238
```python
239
# Find articles with similar tags
240
similar_articles = article.tags.similar_objects()
241
for similar in similar_articles:
242
    print(f"{similar.title}: {similar.similar_tags} shared tags")
243
```
244

245
### Filtering and Querying
246

247
Query models based on their tags using Django's ORM.
248

249
```python
250
# Filter by exact tag name
251
python_articles = Article.objects.filter(tags__name="python")
252

253
# Filter by multiple tags (OR)
254
web_articles = Article.objects.filter(tags__name__in=["python", "javascript"])
255

256
# Filter by multiple tags (AND) - articles that have both tags
257
both_tags = Article.objects.filter(tags__name="python").filter(tags__name="django")
258

259
# Filter by tag slug
260
articles = Article.objects.filter(tags__slug="web-development")
261

262
# Exclude certain tags
263
non_tutorial = Article.objects.exclude(tags__name="tutorial")
264

265
# Count articles per tag
266
from django.db.models import Count
267
tag_counts = Tag.objects.annotate(
268
    article_count=Count('tagged_items')
269
).filter(article_count__gt=0)
270
```
271

272
### Bulk Operations
273

274
Efficient operations for working with multiple objects or large datasets.
275

276
```python
277
# Bulk add tags to multiple objects
278
articles = Article.objects.filter(category="programming")
279
for article in articles:
280
    article.tags.add("programming")
281
    
282
# Use bulk operations for better performance
283
from django.db import transaction
284
with transaction.atomic():
285
    for article in articles:
286
        article.tags.add("bulk-tagged")
287

288
# Get all tags for multiple objects
289
article_ids = [1, 2, 3, 4, 5]
290
all_tags = Tag.objects.filter(
291
    tagged_items__content_type=ContentType.objects.get_for_model(Article),
292
    tagged_items__object_id__in=article_ids
293
).distinct()
294
```
295

296
### Tag Statistics
297

298
Analyze tag usage patterns and statistics.
299

300
```python
301
# Count total tagged items for a tag
302
tag = Tag.objects.get(name="python")
303
usage_count = tag.tagged_items.count()
304

305
# Get tag usage over time
306
from django.db.models import Count
307
from django.utils import timezone
308
recent_tags = Tag.objects.filter(
309
    tagged_items__tagged_item_timestamp__gte=timezone.now() - timedelta(days=30)
310
).annotate(recent_usage=Count('tagged_items'))
311

312
# Find unused tags (orphaned tags)
313
unused_tags = Tag.objects.filter(tagged_items__isnull=True)
314

315
# Most active tags across all models
316
from django.contrib.contenttypes.models import ContentType
317
active_tags = Tag.objects.annotate(
318
    total_usage=Count('tagged_items')
319
).order_by('-total_usage')[:10]
320
```
321

322
## Advanced Usage Patterns
323

324
### Conditional Tag Operations
325

326
Perform tag operations based on conditions.
327

328
```python
329
# Add tags conditionally
330
if article.is_published:
331
    article.tags.add("published")
332
else:
333
    article.tags.add("draft")
334

335
# Remove tags based on content
336
if "outdated" in article.content.lower():
337
    article.tags.remove("current")
338
    article.tags.add("needs-update")
339
```
340

341
### Tag Hierarchies and Relationships
342

343
While django-taggit doesn't natively support hierarchical tags, you can implement patterns for related tags.
344

345
```python
346
# Tag categories through naming conventions
347
article.tags.add("lang:python", "framework:django", "level:beginner")
348

349
# Filter by tag categories
350
python_articles = Article.objects.filter(tags__name__startswith="lang:python")
351
beginner_articles = Article.objects.filter(tags__name__startswith="level:beginner")
352
```
353

354
### Performance Optimization
355

356
Best practices for efficient tag operations.
357

358
```python
359
# Use select_related and prefetch_related
360
articles = Article.objects.prefetch_related('tags').all()
361

362
# Batch tag operations
363
tags_to_add = ["python", "django", "tutorial"]
364
article.tags.add(*tags_to_add)  # Single operation instead of multiple
365

366
# Use exists() for checking tag presence
367
has_python_tag = article.tags.filter(name="python").exists()
368
```