|
1 | 1 | # Python-Redlines: Docx Redlines (Tracked Changes) for the Python Ecosystem |
2 | 2 |
|
3 | | -## Project Goal - Democratizing DOCX Comparisons |
| 3 | +Generate tracked-change "redline" `.docx` documents from Python — compare two Word files |
| 4 | +and get back a third document showing every insertion, deletion, and (optionally) move as |
| 5 | +native Word tracked changes. |
4 | 6 |
|
5 | | -The main goal of this project is to address the significant gap in the open-source ecosystem around `.docx` document |
6 | | -comparison tools. Currently, the process of comparing and generating redline documents (documents that highlight |
7 | | -changes between versions) is complex and largely dominated by commercial software. These |
8 | | -tools, while effective, often come with cost barriers and limitations in terms of accessibility and integration |
9 | | -flexibility. |
| 7 | +Comparing `.docx` documents has long been dominated by commercial software, with cost |
| 8 | +barriers and little integration flexibility. Python-Redlines brings open-source `.docx` |
| 9 | +redlining to the Python ecosystem so legal hackers, hobbyists, and product teams can build |
| 10 | +on it freely: two documents in, one redline out. |
10 | 11 |
|
11 | | -`Python-redlines` aims to democratize the ability to run tracked change redlines for .docx, providing the |
12 | | -open-source community with a tool to create `.docx` redlines without the need for commercial software. This will let |
13 | | -more legal hackers and hobbyist innovators experiment and create tooling for enterprise and legal. |
| 12 | +## Quick Start |
| 13 | + |
| 14 | +The **default engine is [Docxodus](https://github.com/JSv4/Docxodus)** — a modernized, |
| 15 | +actively-maintained .NET 8 comparison engine (detailed below). Install it and you're |
| 16 | +running; the engine binary is prebuilt and embedded in the wheel, so there is **no .NET |
| 17 | +SDK to install and nothing to compile**: |
| 18 | + |
| 19 | +```commandline |
| 20 | +pip install python-redlines[docxodus] |
| 21 | +``` |
| 22 | + |
| 23 | +```python |
| 24 | +from python_redlines import DocxodusEngine |
| 25 | + |
| 26 | +with open("original.docx", "rb") as f: |
| 27 | + original = f.read() |
| 28 | +with open("modified.docx", "rb") as f: |
| 29 | + modified = f.read() |
| 30 | + |
| 31 | +engine = DocxodusEngine() |
| 32 | +redline_bytes, stdout, stderr = engine.run_redline("Reviewer", original, modified) |
| 33 | + |
| 34 | +with open("redline.docx", "wb") as f: |
| 35 | + f.write(redline_bytes) |
| 36 | +``` |
| 37 | + |
| 38 | +That's the whole thing. The rest of this README covers the second (legacy) engine, |
| 39 | +comparison settings, and how the packages are built and distributed. |
14 | 40 |
|
15 | 41 | ## Comparison Engines |
16 | 42 |
|
17 | | -Python-Redlines ships with **two comparison engines** — choose the one that best fits your needs: |
| 43 | +Python-Redlines provides **two comparison engines**. `DocxodusEngine` is the default and |
| 44 | +recommended choice; `XmlPowerToolsEngine` remains available as a legacy option. |
18 | 45 |
|
19 | | -### `DocxodusEngine` — Recommended |
| 46 | +### `DocxodusEngine` — Default (Recommended) |
20 | 47 |
|
21 | 48 | **[Docxodus](https://github.com/JSv4/Docxodus)** is a modernized .NET 8.0 fork of Open-XML-PowerTools with |
22 | 49 | significant improvements: |
@@ -76,29 +103,8 @@ extra to install. |
76 | 103 |
|
77 | 104 | ### Use the Library |
78 | 105 |
|
79 | | -If you just want to use the tool, jump into our [quickstart guide](docs/quickstart.md). |
80 | | - |
81 | | -### Quick Example |
82 | | - |
83 | | -```python |
84 | | -from python_redlines import DocxodusEngine |
85 | | - |
86 | | -# Load your documents as bytes |
87 | | -with open("original.docx", "rb") as f: |
88 | | - original = f.read() |
89 | | -with open("modified.docx", "rb") as f: |
90 | | - modified = f.read() |
91 | | - |
92 | | -# Generate a redline document |
93 | | -engine = DocxodusEngine() |
94 | | -redline_bytes, stdout, stderr = engine.run_redline("Reviewer", original, modified) |
95 | | - |
96 | | -# Save the result |
97 | | -with open("redline.docx", "wb") as f: |
98 | | - f.write(redline_bytes) |
99 | | - |
100 | | -print(stdout) # e.g. "Redline complete: 9 revision(s) found" |
101 | | -``` |
| 106 | +See the [Quick Start](#quick-start) above for a minimal example, or the |
| 107 | +[quickstart guide](docs/quickstart.md) for a step-by-step walkthrough. |
102 | 108 |
|
103 | 109 | ## Comparison Settings (DocxodusEngine only) |
104 | 110 |
|
|
0 commit comments