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.

122 ·GitHub

Paper-docx

What is this?

paper-docx is an agent-safe fork of python-docx for creating and editing Microsoft Word (.docx) documents, built to refuse unsupported operations instead of silently corrupting files.

How is this different from just using python-docx?

It is a hard fork that keeps the same 'docx' import name and upstream object model as python-docx, but adds guarded inspection and editing APIs that refuse operations they cannot safely perform instead of guessing.

What happens if I try an operation paper-docx can't safely handle?

It refuses the operation rather than guessing or producing a corrupted file; for example, its compare feature writes safe differences as tracked changes and refuses edits it cannot represent reliably.

Can I switch back to the original python-docx later?

Yes — uninstall paper-docx and run 'python -m pip install python-docx' in the same environment to restore the upstream package.

What does the quick start example actually do?

It creates a Word redline from two document versions, writing the differences between them as 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: 122
Updated: CommitSep 23 Releasev0.2.1Sep 23
Age: 3mo
Commits · 90 Days