paper-docx README

paper-docx

An import-compatible, agent-safe fork of python-docx for creating and editing Word documents without silent corruption.

paper-docx is an import-compatible hard fork of python-docx for creating and editing Microsoft Word (.docx) documents. It keeps the docx import name and upstream object model, and adds guarded inspection and editing APIs that refuse unsupported operations instead of guessing.

Installation

Use an activated virtual environment.

python -m pip uninstall -y python-docx paper-docx
python -m pip install paper-docx
python -m paper_docx_doctor

Both distributions provide the docx import package. Do not install python-docx and paper-docx in the same environment.

To return to python-docx, run the uninstall line above again, then python -m pip install python-docx.

Quick start

Create a Word redline from two document versions:

import docx
from docx.package import compare

original = docx.Document()
original.add_paragraph("Payment is due within thirty calendar days.")
original.save("original.docx")

revised = docx.Document()
revised.add_paragraph("Payment is due within thirty business days.")
revised.save("revised.docx")

result = compare("original.docx", "revised.docx", author="Reviewer")
result.document.save("redline.docx")
print(result.revision_count)  # 2

compare writes differences as tracked changes and refuses changes it cannot represent safely.

Documentation

Read the paper-docx documentation.

Contributing

Contributions are welcome. See CONTRIBUTING.md.

Acknowledgments

paper-docx builds on python-docx by Steve Canny and contributors. This fork preserves their API, license, and attribution.

Citation

If you reference paper-docx in research or writing:

@software{paper_docx,
  title   = {paper-docx: an agent-first structure editor for Word documents},
  author  = {{Paper Instruments, Inc.}},
  year    = {2026},
  url     = {https://github.com/paper-instruments/paper-docx}
}

Cite it as a fork of python-docx by Steve Canny and contributors.

License

MIT, inherited from python-docx. Original work © Steve Canny and the python-docx contributors; fork additions © Paper Instruments, Inc. See LICENSE.

131 ·GitHub

Paper-docx

这是什么？

paper-docx 是 python-docx 的一个对 AI 代理安全的分支，用于创建和编辑 Microsoft Word（.docx）文档，它的设计理念是拒绝不支持的操作，而不是悄悄损坏文件。

它和直接用 python-docx 有什么区别？

它是一个硬分支，保留了与 python-docx 相同的「docx」导入名和上游对象模型，但增加了受保护的检查与编辑 API，对无法安全执行的操作会直接拒绝，而不是靠猜。

如果我尝试一个 paper-docx 无法安全处理的操作会怎样？

它会拒绝该操作，而不是靠猜测或生成损坏的文件；例如，它的比较功能会把安全的差异写为修订（tracked changes），并拒绝无法可靠表达的编辑。

之后我能换回原来的 python-docx 吗？

可以——卸载 paper-docx，并在同一环境中运行 'python -m pip install python-docx' 即可恢复上游软件包。

快速上手示例实际做了什么？

它根据两个文档版本生成一份 Word 红线文档，把两者之间的差异写成修订（tracked changes）。

What are similar projects?

pypdf, OfficeCLI, pdfcraft, docling, LKY_OfficeTools, dsh-univer-office, Telethon, pdfplumber

Which topics is it in?

office-tools, documents, document-parsing, word, office, document, text-processing, python3, python-library, document-processing, sdk, ai-agent

Creator: paper-instruments
Size: 45.3 MB
Stars: 131
Updated: CommitSep 23 Releasev0.2.1Sep 23
Age: 3mo
Commits · 90 Days