Skill Tracer
Skills › Scientific Agent Skills › pyzotero › tags.md

tags.md

94 lines · skills/pyzotero/references/tags.md at 5f2bc03

Open on GitHub
1# Tag Management
2

Tag Management

Raw lines 1 to 2
3## Retrieving Tags
4
5```python
6# All tags in the library
7tags = zot.everything(zot.tags())
8# Returns list of strings: ['climate change', 'machine learning', ...]
9
10# Tags for a specific item
11item_tags = zot.item_tags('ITEMKEY')
13# Tags in a specific collection
14col_tags = zot.collection_tags('COLKEY')
16# Filter tags by prefix (e.g. all tags starting with 'bio')
17filtered = zot.tags(q='bio', qmode='startsWith')
18```

Retrieving Tags

# All tags in the library
tags = zot.everything(zot.tags())
# Returns list of strings: ['climate change', 'machine learning', ...]

# Tags for a specific item
item_tags = zot.item_tags('ITEMKEY')

# Tags in a specific collection
col_tags = zot.collection_tags('COLKEY')

# Filter tags by prefix (e.g. all tags starting with 'bio')
filtered = zot.tags(q='bio', qmode='startsWith')
Raw lines 3 to 19
20## Adding Tags to Items
22```python
23# Add one or more tags to an item (retrieves item first)
24item = zot.item('ITEMKEY')
25success = zot.add_tags(item, 'tag1', 'tag2', 'tag3') # Boolean, not updated data
27# Add a list of tags
28tag_list = ['reviewed', 'high-priority', '2024']
29item = zot.item('ITEMKEY') # re-fetch after the earlier write
30success = zot.add_tags(item, *tag_list)
31```

Adding Tags to Items

# Add one or more tags to an item (retrieves item first)
item = zot.item('ITEMKEY')
success = zot.add_tags(item, 'tag1', 'tag2', 'tag3')  # Boolean, not updated data

# Add a list of tags
tag_list = ['reviewed', 'high-priority', '2024']
item = zot.item('ITEMKEY')  # re-fetch after the earlier write
success = zot.add_tags(item, *tag_list)
Raw lines 20 to 32
33## Deleting Tags
35```python
36# Delete specific tags from the library
37zot.delete_tags('old-tag', 'unused-tag')
39# Delete a list of tags
40tags_to_remove = ['deprecated', 'temp']
41zot.delete_tags(*tags_to_remove)
42```

Deleting Tags

# Delete specific tags from the library
zot.delete_tags('old-tag', 'unused-tag')

# Delete a list of tags
tags_to_remove = ['deprecated', 'temp']
zot.delete_tags(*tags_to_remove)
Raw lines 33 to 43
44## Searching Items by Tag
46```python
47# Items with a single tag
48items = zot.items(tag='machine learning')
50# Items with multiple tags (AND logic)
51items = zot.items(tag=['climate', 'adaptation'])
53# Items with any of these tags (OR logic)
54items = zot.items(tag='climate || sea level')
56# Items NOT having a tag
57items = zot.items(tag='-retracted')
58```

Searching Items by Tag

# Items with a single tag
items = zot.items(tag='machine learning')

# Items with multiple tags (AND logic)
items = zot.items(tag=['climate', 'adaptation'])

# Items with any of these tags (OR logic)
items = zot.items(tag='climate || sea level')

# Items NOT having a tag
items = zot.items(tag='-retracted')
Raw lines 44 to 59
60## Batch Tag Operations
62```python
63# Add a tag to all items in a collection
64items = zot.everything(zot.collection_items('COLKEY'))
65for item in items:
66 zot.add_tags(item, 'collection-reviewed')
68# Find all items with a specific tag and retag them
69old_tag_items = zot.everything(zot.items(tag='old-name'))
70for item in old_tag_items:
71 # Add new tag
72 item['data']['tags'].append({'tag': 'new-name'})
73 # Remove old tag
74 item['data']['tags'] = [t for t in item['data']['tags'] if t['tag'] != 'old-name']
75# Capture per-object status rather than update_items()'s coarse Boolean.
76for start in range(0, len(old_tag_items), 50):
77 result = zot.create_items([i['data'] for i in old_tag_items[start:start + 50]])
78 if result.get('failed'):
79 raise RuntimeError(result['failed'])
80```

Batch Tag Operations

# Add a tag to all items in a collection
items = zot.everything(zot.collection_items('COLKEY'))
for item in items:
    zot.add_tags(item, 'collection-reviewed')

# Find all items with a specific tag and retag them
old_tag_items = zot.everything(zot.items(tag='old-name'))
for item in old_tag_items:
    # Add new tag
    item['data']['tags'].append({'tag': 'new-name'})
    # Remove old tag
    item['data']['tags'] = [t for t in item['data']['tags'] if t['tag'] != 'old-name']
# Capture per-object status rather than update_items()'s coarse Boolean.
for start in range(0, len(old_tag_items), 50):
    result = zot.create_items([i['data'] for i in old_tag_items[start:start + 50]])
    if result.get('failed'):
        raise RuntimeError(result['failed'])
Raw lines 60 to 81
82## Tag Types
84Zotero has two tag types stored in `tag['type']`:
85- `0` — User-added tags (default)
86- `1` — Automatically imported tags (from bibliographic databases)
88```python
89item = zot.item('ITEMKEY')
90for tag in item['data']['tags']:
91 print(tag['tag'], tag.get('type', 0))
92```
94Tag deletion removes the named tags throughout the library (up to 50 per call); it does not delete the items. `tags()` returns strings and discards API tag metadata. Use each item's `data.tags` to inspect tag types.

Tag Types

Zotero has two tag types stored in tag['type']:

  • 0 — User-added tags (default)
  • 1 — Automatically imported tags (from bibliographic databases)
item = zot.item('ITEMKEY')
for tag in item['data']['tags']:
    print(tag['tag'], tag.get('type', 0))

Tag deletion removes the named tags throughout the library (up to 50 per call); it does not delete the items. tags() returns strings and discards API tag metadata. Use each item's data.tags to inspect tag types.

Raw lines 82 to 94