How to Inspect OneNote Tags in Python

OneNote lets users annotate content with colored tags: stars, checkboxes, important flags, and custom labels. Aspose.Note FOSS for Python exposes these annotations as NoteTag objects on RichText, Image, AttachedFile, and Table nodes via their .Tags property. This guide shows how to read them.

Step-by-Step Guide

Step 1: Install Aspose.Note FOSS for Python

Install the Aspose.Note FOSS package from PyPI using the pip command below:

pip install aspose-note

Step 2: Load the .one File

Load a OneNote .one file into a Document instance, then print the page count to confirm it loaded:

from aspose.note import Document

doc = Document("TaggedNotes.one")
print(f"Pages: {len(list(doc))}")

Step 3: Find Tags on RichText Nodes

Most tags are attached to text blocks — retrieve all RichText nodes with GetChildNodes() and iterate the .Tags property on each:

from aspose.note import Document, RichText

doc = Document("TaggedNotes.one")
for rt in doc.GetChildNodes(RichText):
    for tag in rt.Tags:
        print(f"[RichText] Label={tag.Label!r}  Icon={tag.Icon}  text={rt.Text.strip()!r}")

Step 4: Find Tags on Images

Use GetChildNodes(Image) to iterate all image nodes and read the .Tags property on each:

from aspose.note import Document, Image

doc = Document("TaggedNotes.one")
for img in doc.GetChildNodes(Image):
    for tag in img.Tags:
        print(f"[Image] Label={tag.Label!r}  filename={img.FileName!r}")

Step 5: Find Tags on Tables

Use GetChildNodes(Table) to iterate all table nodes and read the .Tags property on each:

from aspose.note import Document, Table

doc = Document("TaggedNotes.one")
for table in doc.GetChildNodes(Table):
    for tag in table.Tags:
        print(f"[Table] Label={tag.Label!r}  widths={[col.Width for col in table.Columns]}")

Step 6: Collect All Tags Across the Document

Iterate all three node types in a single pass and accumulate tagged items into a list for reporting:

from aspose.note import Document, RichText, Image, Table

doc = Document("TaggedNotes.one")
all_tags = []

for rt in doc.GetChildNodes(RichText):
    for tag in rt.Tags:
        all_tags.append({"type": "RichText", "Label": tag.Label,
                         "CompletedTime": tag.CompletedTime, "text": rt.Text.strip()})
for img in doc.GetChildNodes(Image):
    for tag in img.Tags:
        all_tags.append({"type": "Image", "Label": tag.Label,
                         "CompletedTime": tag.CompletedTime, "file": img.FileName})
for table in doc.GetChildNodes(Table):
    for tag in table.Tags:
        all_tags.append({"type": "Table", "Label": tag.Label,
                         "CompletedTime": tag.CompletedTime})

print(f"Total tagged items: {len(all_tags)}")
for item in all_tags:
    print(item)

NoteTag Property Reference

Property	Type	Description
`Icon`	`int \| None`	Numeric tag shape identifier (star, checkbox, arrow, etc.)
`Label`	`str \| None`	Human-readable label string (e.g. `"Important"`, `"To Do"`)
`FontColor`	`int \| None`	Text color as ARGB integer
`Highlight`	`int \| None`	Highlight color as ARGB integer
`CreationTime`	`datetime \| None`	When the tag was created
`CompletedTime`	`datetime \| None`	When the tag was completed (`None` if not completed)
`Status`	`TagStatus`	`TagStatus.Completed` if completed, else `TagStatus.Open`

Filter Completed vs Pending Tags

Tags that have been checked off (like “To Do” checkboxes) have a non-None CompletedTime field:

from aspose.note import Document, RichText

doc = Document("TaggedNotes.one")
pending, done = [], []

for rt in doc.GetChildNodes(RichText):
    for tag in rt.Tags:
        item = {"Label": tag.Label, "text": rt.Text.strip()}
        if tag.CompletedTime is None:
            pending.append(item)
        else:
            done.append(item)

print(f"Pending: {len(pending)}  Done: {len(done)}")
for p in pending:
    print(f"  [ ] {p['Label']}: {p['text']!r}")
for d in done:
    print(f"  [x] {d['Label']}: {d['text']!r}")

Create a NoteTag (In-Memory)

The factory method NoteTag.CreateYellowStar() creates a tag node you can attach to new content in-memory:

from aspose.note import NoteTag

tag = NoteTag.CreateYellowStar()
print(f"Created tag: Icon={tag.Icon}  Label={tag.Label!r}")

In-memory creation is useful for API compatibility. Since writing back to .one is not supported, created tags cannot be persisted to file.

Common Issues

No tags found (document returns empty Tags lists): Not all .one files contain tags. Verify the source document has tags visible in Microsoft OneNote before troubleshooting the code.

tag.Label is an empty string: Some tag shapes do not have a text label in the file metadata. Use tag.Icon to identify the tag type programmatically.

Related Resources: