word-comment 0.1.0

Add Word comments to matching text in .docx files.

word-comment

word-comment adds a Microsoft Word comment to matching text in a .docx file.

It targets a specific paragraph by w14:paraId, finds the first matching occurrence of target_text inside that paragraph, and inserts a standard Word comment range plus comment metadata.

Installation

python -m pip install word-comment

Python API

from word_comment import add_comment

result = add_comment(
    input_path="input.docx",
    output_path="output.docx",
    para_id="7BD69366",
    target_text="keyword",
    comment_text="comment body",
    author="Auto_Bot",
)

print(result.success)
print(result.inserted_count)
print(result.reason)

CLI

word-comment input.docx output.docx 7BD69366 "keyword" "comment body" --author Auto_Bot

Behavior

• Searches for the paragraph whose w14:paraId matches para_id
• Finds the first occurrence of target_text in that paragraph
• Inserts a Word comment range and a commentReference
• Creates word/comments.xml when it does not already exist
• Adds the required relationship and content-type entries when needed
• Copies the input file unchanged when the paragraph or target text is not found

Return Value

add_comment(...) returns AddCommentResult with:

• success: bool
• inserted_count: int
• para_id: str
• output_path: Path
• reason: str | None

Possible reason values:

• paragraph_not_found
• target_text_not_found

Limitations

• The target paragraph must already have a w14:paraId
• target_text must exist entirely within a single w:t node
• Only the first match in the selected paragraph is annotated
• The implementation modifies word/document.xml and word/comments.xml

Development Release Check

Build artifacts locally:

python -m build
python -m twine check dist/*