Metadata-Version: 2.4
Name: word-comment
Version: 0.1.0
Summary: Add Word comments to matching text in .docx files.
Author: AI-Part-A
License-Expression: MIT
Project-URL: Homepage, https://github.com/AI-Part-A/word-comment
Project-URL: Repository, https://github.com/AI-Part-A/word-comment
Project-URL: Issues, https://github.com/AI-Part-A/word-comment/issues
Keywords: docx,word,comments,office,xml
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml>=5.0.0
Dynamic: license-file

# 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

```bash
python -m pip install word-comment
```

## Python API

```python
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

```bash
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:

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