word-comment 0.1.1

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

Install from PyPI:

python -m pip install word-comment

Install from GitHub source instead:

gh auth login
pip install git+https://github.com/AI-Part-A/word-comment.git

Google Colab Source Install

If you want to install from the private GitHub repository in Colab, store these secrets first:

• GITHUB_USER: your GitHub username
• GITHUB_TOKEN: a fine-grained personal access token with repository read access

from google.colab import userdata
import subprocess
import sys

github_user = userdata.get("GITHUB_USER")
github_token = userdata.get("GITHUB_TOKEN")

subprocess.run(
    [
        sys.executable,
        "-m",
        "pip",
        "install",
        f"git+https://{github_user}:{github_token}@github.com/AI-Part-A/word-comment.git",
    ],
    check=True,
)

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 is matched against the concatenated w:t text in the selected paragraph
• 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/*