docx-comments 0.1.1

Complete Word document comment manipulation with threading and Word Online compatibility

docx-comments

Python module for complete Word document comment manipulation - adding, replying, and resolving comments with full Word Online compatibility.

Problem

python-docx can read Word comments but cannot properly create or reply to them:

• Creates comments.xml but no anchors in document.xml
• Missing commentsExtended.xml (threading)
• Missing commentsIds.xml (durable IDs)

Microsoft Graph API does NOT support Word comments (only Excel).

Solution

This module provides complete OOXML comment manipulation based on ECMA-376 / ISO/IEC 29500:

• Add anchored comments to specific text ranges
• Reply to existing comments (threaded)
• Mark comments as resolved
• Full Word Online compatibility

Installation

pip install docx-comments

Usage

from docx import Document
from docx_comments import CommentManager

doc = Document("document.docx")
mgr = CommentManager(doc)

# Add anchored comment to text range
comment_id = mgr.add_comment(
    paragraph=doc.paragraphs[0],
    start_run=0,
    end_run=2,
    text="Please review this section",
    author="Reviewer Name",
    initials="RN"
)

# Reply to existing comment
reply_id = mgr.reply_to_comment(
    parent_id=comment_id,
    text="Addressed in this revision",
    author="Author Name",
    initials="AN"
)

# Mark comment as resolved
mgr.resolve_comment(comment_id)

# List all comment threads
for thread in mgr.get_comment_threads():
    print(f"Root: {thread.root.text} by {thread.root.author}")
    for reply in thread.replies:
        print(f"  Reply: {reply.text} by {reply.author}")

doc.save("document_reviewed.docx")

OOXML Parts Handled

This module manages four XML parts:

1. comments.xml - Comment content and metadata
2. document.xml - Anchors (commentRangeStart/End, commentReference)
3. commentsExtended.xml - Threading (paraId, paraIdParent, done)
4. commentsIds.xml - Durable IDs for persistence

Requirements

• Python 3.9+
• python-docx >= 1.0.0
• lxml

References

OOXML Specification

• ECMA-376 - Office Open XML File Formats (free download)
• ISO/IEC 29500 - OOXML Format Family overview
• MS-DOCX Extensions - Microsoft's DOCX extensions documentation

Comment Elements

• commentRangeStart - Comment anchor range start element
• commentRangeEnd - Comment anchor range end element
• commentReference - Comment content reference mark
• Comments Overview - OOXML comments specification

Threading & Extended Parts

• CommentEx Class - Office 2013 comment threading (paraId, paraIdParent, done)
• commentsIds - Durable IDs specification (Office 2016+)

Related Libraries

• python-docx - Python library for Word documents (foundation for this module)
• Open XML SDK - Microsoft's .NET SDK for OOXML

Acknowledgements

This project was conceptualised by Ting Sun and implemented with the assistance of Claude Code (Anthropic's AI coding assistant) under his guidance. The collaboration involved iterative development of the OOXML comment handling logic, with Claude Code contributing to code implementation and Ting Sun providing architectural direction and domain expertise.

License

MIT