Features Overview — Aspose.Note FOSS for Python

Aspose.Note FOSS for Python (package aspose-note, version 26.3.2) provides a Python API for reading Microsoft OneNote .one section files and exporting them to PDF. All features listed below are verified against the repository source code, README, and example scripts.

Installation and Setup

Install from PyPI:

pip install aspose-note

For PDF export support (requires ReportLab):

pip install "aspose-note[pdf]"

Requirements: Python 3.10 or later. No Microsoft Office installation required.

Features and Capabilities

.one File Loading

Load Microsoft OneNote section files from a file path or any binary stream (file handle, io.BytesIO, HTTP response body, cloud storage stream).

• Document.FileFormat provides a best-effort indication of the OneNote file format version (OneNote2010, OneNoteOnline, or OneNote2007)
• Stream-based loading eliminates disk I/O for in-memory or network workflows
• LoadOptions.LoadHistory flag controls whether page history is included in the DOM

from aspose.note import Document

##From a file path
doc = Document("notebook.one")

##From a binary stream
with open("notebook.one", "rb") as f:
    doc = Document(f)

Document DOM Traversal

The full OneNote document is exposed as a tree of typed Python objects. Every node inherits from Node or CompositeNode:

• Document: root; exposes DisplayName, CreationTime, FileFormat
• Page: direct child of Document; exposes Title, Author, CreationTime, LastModifiedTime, Level
• Title: exposes TitleText, TitleDate, TitleTime (all RichText nodes)
• Outline: positional container with HorizontalOffset, VerticalOffset, MaxWidth, MaxHeight, MinWidth, ReservedWidth, IndentPosition
• OutlineElement: leaf container; exposes NumberList

Navigation methods on CompositeNode:

from aspose.note import Document, Page, Outline, OutlineElement, RichText

doc = Document("notebook.one")
for page in doc.GetChildNodes(Page):
    title_text = page.Title.TitleText.Text if page.Title and page.Title.TitleText else ""
    print(f"Page: {title_text}")
    for outline in page.GetChildNodes(Outline):
        for oe in outline.GetChildNodes(OutlineElement):
            for rt in oe.GetChildNodes(RichText):
                print(f"  {rt.Text}")

Rich Text Content Extraction

RichText nodes expose:

• Text: str: full plain-text string
• TextRuns: list[TextRun]: list of formatted segments
• Tags: list[NoteTag]: OneNote tags attached to this block
• Append(text, style=None): append a text run in-memory
• Replace(old_value, new_value): in-memory string substitution

Each TextRun carries:

TextStyle properties:

from aspose.note import Document, RichText

doc = Document("notebook.one")
for rt in doc.GetChildNodes(RichText):
    for run in rt.TextRuns:
        if run.Style.IsHyperlink:
            print(f"Hyperlink: {run.Text} -> {run.Style.HyperlinkAddress}")
        if run.Style.IsBold:
            print(f"Bold text: {run.Text}")

Image Extraction

Image nodes expose raw bytes and metadata for every embedded image:

from aspose.note import Document, Image

doc = Document("notebook.one")
for i, img in enumerate(doc.GetChildNodes(Image), start=1):
    filename = img.FileName or f"image_{i}.bin"
    with open(filename, "wb") as f:
        f.write(img.Bytes)
    print(f"Saved: {filename}  ({img.Width} x {img.Height} pts)")

Attached File Extraction

AttachedFile nodes expose embedded file attachments:

from aspose.note import Document, AttachedFile

doc = Document("notebook.one")
for i, af in enumerate(doc.GetChildNodes(AttachedFile), start=1):
    filename = af.FileName or f"attachment_{i}.bin"
    with open(filename, "wb") as f:
        f.write(af.Bytes)

Table Parsing

Table, TableRow, and TableCell expose the full table structure:

from aspose.note import Document, Table, TableRow, TableCell, RichText

doc = Document("notebook.one")
for table in doc.GetChildNodes(Table):
    print("Column widths:", [col.Width for col in table.Columns])
    for r, row in enumerate(table.GetChildNodes(TableRow), start=1):
        cells = row.GetChildNodes(TableCell)
        values = [
            " ".join(rt.Text for rt in cell.GetChildNodes(RichText)).strip()
            for cell in cells
        ]
        print(f"Row {r}:", values)

OneNote Tag Inspection

NoteTag appears on RichText, Image, AttachedFile, and Table nodes via their .Tags property. OutlineElement does not have a .Tags property. NoteTag properties:

Factory method: NoteTag.CreateYellowStar() creates a standard yellow-star tag node.

from aspose.note import Document, RichText

doc = Document("notebook.one")
for rt in doc.GetChildNodes(RichText):
    for tag in rt.Tags:
        print(f"Tag: {tag.Label} (icon={tag.Icon}, completed={tag.CompletedTime})")

Numbered List Support

OutlineElement.NumberList exposes:

from aspose.note import Document, OutlineElement

doc = Document("notebook.one")
for oe in doc.GetChildNodes(OutlineElement):
    nl = oe.NumberList
    if nl:
        print(f"format={nl.Format!r}")

DocumentVisitor Traversal

DocumentVisitor provides a visitor pattern for structured full-document traversal. Override any VisitXxxStart / VisitXxxEnd method to intercept specific node types:

• VisitDocumentStart(doc) / VisitDocumentEnd(doc)
• VisitPageStart(page) / VisitPageEnd(page)
• VisitTitleStart(title) / VisitTitleEnd(title)
• VisitOutlineStart(outline) / VisitOutlineEnd(outline)
• VisitOutlineElementStart(oe) / VisitOutlineElementEnd(oe)
• VisitRichTextStart(rt) / VisitRichTextEnd(rt)
• VisitImageStart(img) / VisitImageEnd(img)

from aspose.note import Document, DocumentVisitor, Page, RichText, Image

class MySummaryVisitor(DocumentVisitor):
    def __init__(self):
        self.pages, self.texts, self.images = 0, 0, 0

    def VisitPageStart(self, page: Page) -> None:
        self.pages += 1

    def VisitRichTextStart(self, rt: RichText) -> None:
        self.texts += 1

    def VisitImageStart(self, img: Image) -> None:
        self.images += 1

doc = Document("notebook.one")
v = MySummaryVisitor()
doc.Accept(v)
print(f"Pages={v.pages}  RichText={v.texts}  Images={v.images}")

PDF Export

Save a loaded document to PDF using Document.Save(). Supported via the optional ReportLab backend.

from aspose.note import Document, SaveFormat

doc = Document("notebook.one")
doc.Save("output.pdf", SaveFormat.Pdf)

PdfSaveOptions

import io
from aspose.note import Document, SaveFormat
from aspose.note.saving import PdfSaveOptions

doc = Document("notebook.one")

##Save to file
doc.Save("output.pdf", SaveFormat.Pdf)

##Save to in-memory stream
buf = io.BytesIO()
doc.Save(buf, PdfSaveOptions())
pdf_bytes = buf.getvalue()

Format and Enum Reference

SaveFormat

FileFormat

Document.FileFormat provides a best-effort indication of the OneNote file format version. The enum declares three values:

NodeType

NodeType.Document, NodeType.Page, NodeType.Outline, NodeType.OutlineElement, NodeType.RichText, NodeType.Image, NodeType.Table, NodeType.AttachedFile

HorizontalAlignment

HorizontalAlignment.Left, HorizontalAlignment.Center, HorizontalAlignment.Right

Current Limitations

Tips and Best Practices

• Check for None: Page.Title, Title.TitleText, OutlineElement.NumberList, and most metadata fields can be None. Always guard with if x is not None or if x before accessing properties.
• Use GetChildNodes(Type) for recursive search rather than manually iterating the tree. It searches the entire subtree.
• Iterate direct children with for child in node when you only need immediate children.
• Handle encoding on Windows: On Windows, sys.stdout may use a legacy code page. Add sys.stdout.reconfigure(encoding="utf-8", errors="replace") at startup when printing Unicode text.
• Install [pdf] extra: PDF export requires ReportLab. Run pip install "aspose-note[pdf]" before using SaveFormat.Pdf. Without ReportLab, saving to PDF raises an ImportError at runtime.