docxnote 0.3.3

Lightweight DOCX comment engine based on text view API

Docxnote

Lightweight DOCX comment engine: add and read Word comments from plain paragraph text, with only an lxml dependency.

简体中文

---

Overview

docxnote automates Word comments (annotations) without manual run editing: you traverse Paragraph / Table / Cell, call paragraph.comment(...), and optionally read comments via paragraph.comments and doc.comments().

Repository: touken928/docxnote

---

Installation

pip install docxnote

With uv:

uv add docxnote

---

Quick start

from docxnote import DocxDocument, Paragraph, Table

# Load document
with open("document.docx", "rb") as f:
    # By default existing comments are stripped before writing new ones
    doc = DocxDocument.parse(f.read())

    # To preserve existing comments and append more:
    # doc = DocxDocument.parse(f.read(), keep_comments=True)

# Walk block-level content
for block in doc.blocks():
    if isinstance(block, Paragraph):
        if block.text:
            block.comment("Please review wording", end=5, author="reviewer")

    elif isinstance(block, Table):
        rows, cols = block.shape()
        for r in range(rows):
            for c in range(cols):
                cell = block[r, c]
                for inner in cell.blocks():
                    if isinstance(inner, Paragraph) and inner.text:
                        inner.comment("Needs review", end=3, author="reviewer")

# Write output
output = doc.render()
with open("output.docx", "wb") as f:
    f.write(output)

Table traversal accounts for Word tables whose rows omit leading or trailing grid columns. Comment ranges use Python slice semantics on paragraph.text, including negative and oversized endpoints; a reversed range is an empty anchor at its normalized start. See the API reference for details.

---

CLI

Installing docxnote adds a console script of the same name. Every read command supports --json, every write command takes an explicit output path, and they all share the library's addressable paths (p:0, t:0/r:1/c:2/p:0, p:0#3, ...).

docxnote list input.docx --text --json
docxnote show input.docx "t:0/r:1/c:2/p:0"
docxnote comments input.docx --json
docxnote annotate input.docx output.docx --path p:0 --text "please revise"
docxnote annotate input.docx output.docx --spec ops.json --keep-comments

Full reference: docs/CLI.md · docs/CLI_zh.md.

annotate rejects input/output aliases, including symlinks and hard links, and writes through a temporary sibling file before atomically replacing OUTPUT.

start / end always refer to character offsets inside paragraph.text using Python slice semantics ([start, end)). docxnote handles run splitting, including ranges that fall inside hyperlinks and other nested paragraph containers.

---

Documentation

Full Python API (methods, parameters, comments, paths, tables, and advanced patterns):

• docs/API.md — English
• docs/API_zh.md — 简体中文
• docs/CLI.md / docs/CLI_zh.md — CLI reference
• docs/README_zh.md — 简体中文 overview (same scope as README)

When keep_comments=True, existing comments are preserved and re-emitted with their existing comment XML metadata, while new comments are appended on top.

---

Tests

Test documents are generated with python-docx; no checked-in DOCX fixtures. See tests/README.md.

---

SKILL

npx skills add touken928/docxnote

Agent-oriented docs live under skills/docxnote.

---

License

Licensed under the Apache License, Version 2.0. See LICENSE in the repository root.