wolfdocx-docx 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- wolfdocx_docx-0.1.0/.gitignore +14 -0
- wolfdocx_docx-0.1.0/LICENSE +21 -0
- wolfdocx_docx-0.1.0/PKG-INFO +295 -0
- wolfdocx_docx-0.1.0/README.md +272 -0
- wolfdocx_docx-0.1.0/THIRD_PARTY_NOTICES.txt +26 -0
- wolfdocx_docx-0.1.0/pyproject.toml +65 -0
- wolfdocx_docx-0.1.0/src/wolfdocx_docx/__init__.py +25 -0
- wolfdocx_docx-0.1.0/src/wolfdocx_docx/agent.py +292 -0
- wolfdocx_docx-0.1.0/src/wolfdocx_docx/document.py +223 -0
- wolfdocx_docx-0.1.0/src/wolfdocx_docx/shared.py +143 -0
- wolfdocx_docx-0.1.0/src/wolfdocx_docx/table.py +274 -0
- wolfdocx_docx-0.1.0/src/wolfdocx_docx/text.py +388 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Wolfgang Schoenberger
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: wolfdocx-docx
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Opt-in python-docx import alias over the MIT WolfDocx engine for agent-style edits: tracked changes, comments and stable addresses
|
|
5
|
+
Author: Wolfgang Schoenberger
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
License-File: THIRD_PARTY_NOTICES.txt
|
|
9
|
+
Keywords: comments,docx,openxml,python-docx,tracked-changes,word
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Office/Business :: Office Suites
|
|
19
|
+
Classifier: Topic :: Text Processing :: Markup :: XML
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Requires-Dist: wolfdocx>0.1.1
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
|
|
24
|
+
# WolfDocx python-docx import alias
|
|
25
|
+
|
|
26
|
+
Use `import wolfdocx_docx as docx` for the documented python-docx API subset over
|
|
27
|
+
WolfDocx's native document builder and verified session saves. Install this
|
|
28
|
+
separate, opt-in distribution alongside WolfDocx. The `docx` namespace remains
|
|
29
|
+
available to python-docx; no upstream runtime dependency or import replacement is
|
|
30
|
+
required.
|
|
31
|
+
|
|
32
|
+
## Install and use
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
pip install wolfdocx-docx
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The MIT `wolfdocx` engine is the only runtime dependency. Capabilities that
|
|
39
|
+
engine does not ship raise `ModuleNotFoundError("commercial_feature_unavailable")`.
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
import wolfdocx_docx as docx
|
|
43
|
+
from wolfdocx_docx.shared import Inches, RGBColor
|
|
44
|
+
|
|
45
|
+
report = docx.Document()
|
|
46
|
+
report.add_heading("Operating review", level=1)
|
|
47
|
+
paragraph = report.add_paragraph("Status: ")
|
|
48
|
+
paragraph.add_run("approved").bold = True
|
|
49
|
+
cell = report.add_table(rows=1, cols=2).cell(0, 0)
|
|
50
|
+
cell.text = "Owner"
|
|
51
|
+
report.save("review.docx")
|
|
52
|
+
|
|
53
|
+
opened = docx.Document("review.docx")
|
|
54
|
+
opened.paragraphs[0].text = "Updated operating review"
|
|
55
|
+
opened.tables[0].cell(0, 1).text = "Finance"
|
|
56
|
+
opened.save("review.docx")
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Supported API
|
|
60
|
+
|
|
61
|
+
| Surface | Supported operations |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
| Document | `Document()`, open a path or seekable binary stream; `paragraphs`, `tables`, `add_paragraph`, `add_heading` levels 0–9, `add_table`, `save` to a path or seekable binary stream |
|
|
64
|
+
| Paragraph | `text`, `runs`, `add_run(text, style)`, `clear()`, `alignment` |
|
|
65
|
+
| Run | `text`, tri-state `bold` and `italic`; boolean/`None` underline writes and existing OOXML underline-value reads |
|
|
66
|
+
| Table | `cell(row_idx, col_idx)`, live `rows` sequence (iteration, indexing and slicing), `add_row()`; zero-sized tables |
|
|
67
|
+
| Row | `cells`, including repeated grid positions for merged cells |
|
|
68
|
+
| Cell | `text`, `paragraphs`, `tables`, `grid_span`, `add_paragraph`, nested `add_table` |
|
|
69
|
+
| Shared values | `Length`, `Inches`, `Cm`, `Mm`, `Pt`, `Twips`, `Emu`, `RGBColor` |
|
|
70
|
+
|
|
71
|
+
Use zero-based table coordinates. Text assignments translate tabs and line breaks
|
|
72
|
+
as python-docx does. Preserve run formatting when assigning run text; preserve
|
|
73
|
+
paragraph properties and clear run formatting when assigning paragraph text.
|
|
74
|
+
Assign `docx.WD_ALIGN_PARAGRAPH.CENTER` (or the other native alignment constants)
|
|
75
|
+
to `paragraph.alignment`; assign `None` to inherit alignment from its style.
|
|
76
|
+
|
|
77
|
+
Resolve style names and IDs against an opened package's styles. For missing names
|
|
78
|
+
in new documents, create native minimal style definitions. The python-docx bundled
|
|
79
|
+
template and its formatting are outside this coverage. Style objects, pictures,
|
|
80
|
+
sections, headers and footers, core properties, the upstream comments API, full font APIs, OXML/OPC
|
|
81
|
+
internals, and all unlisted APIs are outside this coverage.
|
|
82
|
+
|
|
83
|
+
Save through the native verified session path before publication. For a path,
|
|
84
|
+
replace the destination atomically after staging; follow an existing symbolic link
|
|
85
|
+
to its target and retain existing file permissions. Return `None`, as python-docx
|
|
86
|
+
does. Preserve unchanged package members, including opaque parts. Native validation
|
|
87
|
+
refusals raise `wolfdocx.model.NodeEditError`. Native `wolfdocx.Document.save` retains
|
|
88
|
+
its separate no-clobber contract.
|
|
89
|
+
|
|
90
|
+
## Upstream coverage
|
|
91
|
+
|
|
92
|
+
Pin python-docx `v1.2.0` at commit
|
|
93
|
+
`e45454602b53e8e572b179ccf1c91093ec9f4ed7`. The MIT license and source-file digests are
|
|
94
|
+
recorded in [`upstream/pin.json`](upstream/pin.json); ship the derived shared-type
|
|
95
|
+
notice in [`THIRD_PARTY_NOTICES.txt`](THIRD_PARTY_NOTICES.txt).
|
|
96
|
+
[`upstream/expected.json`](upstream/expected.json) freezes the digest of `pin.json`, pins
|
|
97
|
+
upstream `tests/test_document.py`, `tests/test_table.py`,
|
|
98
|
+
`tests/text/test_paragraph.py` and `tests/text/test_run.py` by sha256 and git blob, and records the admitted
|
|
99
|
+
node IDs, every excluded node with its reason, and exclusion rules for every other
|
|
100
|
+
upstream test module and feature file. The admitted set was frozen before
|
|
101
|
+
implementation; changing it requires central approval.
|
|
102
|
+
|
|
103
|
+
Five unmodified upstream test modules run through the import alias. Every module
|
|
104
|
+
remains partially exercised; none is fully qualified:
|
|
105
|
+
|
|
106
|
+
| Upstream module | Passing cases | Excluded cases | Status |
|
|
107
|
+
| --- | --- | --- | --- |
|
|
108
|
+
| `tests/test_shared.py` | 18 of 21 | 3 `ElementProxy` cases | partial |
|
|
109
|
+
| `tests/test_document.py` | 8 of 32 | 24, each with its own reason | partial |
|
|
110
|
+
| `tests/test_table.py` | 24 of 150 | 126, each with its own reason | partial |
|
|
111
|
+
| `tests/text/test_paragraph.py` | 13 of 59 | 46, each with its own reason | partial |
|
|
112
|
+
| `tests/text/test_run.py` | 10 of 79 | 69, each with its own reason | partial |
|
|
113
|
+
|
|
114
|
+
The other 54 upstream test modules and 67 feature files remain excluded by rule.
|
|
115
|
+
Before the table and text admissions, the gate exercised 2 of 59 test modules and
|
|
116
|
+
passed 26 of 53 collected nodes, excluding 27 nodes and 124 other modules or feature
|
|
117
|
+
files. With both admissions, it exercises 5 of 59 modules and passes 73 of 341
|
|
118
|
+
collected nodes, excluding 268 nodes and 121 other modules or feature files. The
|
|
119
|
+
newly inventoried table and text modules account for the larger excluded-node
|
|
120
|
+
denominator; no formerly admitted node was removed. Never treat excluded cases as
|
|
121
|
+
passing.
|
|
122
|
+
|
|
123
|
+
The table cases cover grid-coordinate cell access, row enumeration, cell grid-span
|
|
124
|
+
and text reads (including tabs, breaks and multiple paragraphs), paragraph access,
|
|
125
|
+
and row-sequence iteration, indexing, bounds and owning-table access. The native
|
|
126
|
+
XML constructors import supplied XML into fresh native stories. For foreign lxml
|
|
127
|
+
input, serialize with lxml's C serializer to avoid invoking polymorphic upstream
|
|
128
|
+
text accessors. No upstream document, table or cell engine runs. The two native
|
|
129
|
+
XML child-list views used by the unchanged cell-access test do not qualify the
|
|
130
|
+
full upstream OXML object model or original input-element identity.
|
|
131
|
+
|
|
132
|
+
A separate focused edit/save/reopen scenario in
|
|
133
|
+
[`tests/test_ltg_docx_alias_upstream_table_20261111.py`](tests/test_ltg_docx_alias_upstream_table_20261111.py)
|
|
134
|
+
compares the same table-edit script against the pinned python-docx checkout in an
|
|
135
|
+
isolated process. It covers `add_row`, horizontal and vertical merged-cell
|
|
136
|
+
addressing, live row sequences and slices, cell replacement, paragraph append and
|
|
137
|
+
direct run-text edits. Preserve all direct run properties for run-text edits,
|
|
138
|
+
including unlisted font properties. Whole-cell text replacement intentionally
|
|
139
|
+
clears content and direct run formatting, as in python-docx. Structural merge,
|
|
140
|
+
row deletion and column mutation remain unsupported; no paragraph-deletion
|
|
141
|
+
fallback stands in for those operations. Check neighboring content, other tables,
|
|
142
|
+
non-table paragraphs and unchanged package members separately.
|
|
143
|
+
|
|
144
|
+
The 23 admitted text cases were frozen before implementation: paragraph text
|
|
145
|
+
reads (including hyperlinks, tabs and breaks), paragraph text replacement,
|
|
146
|
+
paragraph alignment reads, run text reads, and run bold/italic tri-state reads.
|
|
147
|
+
The bodies and pinned source files are unchanged. Other setters that assert
|
|
148
|
+
private upstream `_p.xml`/`_r.xml` serialization remain excluded, alongside style,
|
|
149
|
+
font, hyperlink-object, rendered-page-break and unimplemented authoring APIs.
|
|
150
|
+
Every excluded node and file has its own recorded reason.
|
|
151
|
+
|
|
152
|
+
Separate [save/reopen qualification](tests/test_ltg_docx_alias_upstream_text_20261111.py)
|
|
153
|
+
compares mixed-run edits, paragraph replacement, `add_run`, bold/italic and
|
|
154
|
+
alignment with python-docx loaded from the exact pinned source checkout. It checks
|
|
155
|
+
line breaks, retained paragraph styles, cleared run formatting after paragraph
|
|
156
|
+
replacement, untouched neighboring XML and byte-identical unrelated package parts.
|
|
157
|
+
Use the native lower-level Paragraph/Run XML constructors for detached text trees;
|
|
158
|
+
upstream OXML identity, serialization helpers and parent/part graphs remain outside
|
|
159
|
+
the public alias contract. Native input nodes retain their builder ownership.
|
|
160
|
+
|
|
161
|
+
The eight Document cases are upstream unit tests built on mocks:
|
|
162
|
+
|
|
163
|
+
- `add_heading` for levels 0, 1, 2 and 9 chooses the `Title` or `Heading N` style and
|
|
164
|
+
delegates to `add_paragraph`.
|
|
165
|
+
- `add_heading` rejects levels -1 and 10 with python-docx's message.
|
|
166
|
+
- `add_paragraph` passes `("", None)`, `("", "Heading 1")` and `("foo\rbar", "Body Text")`
|
|
167
|
+
to the document body and returns its result.
|
|
168
|
+
|
|
169
|
+
Each case calls the native `wolfdocx_docx.document.Document`. Its collaborators are
|
|
170
|
+
mocks specified from pinned upstream classes: the patched `add_paragraph` method, the
|
|
171
|
+
`_body` property, and the body, paragraph and document-part objects. These cases
|
|
172
|
+
prove method contracts, not saved content. Saved content is covered separately by the
|
|
173
|
+
native save/reopen tests in
|
|
174
|
+
[`tests/test_ltg_docx_alias_upstream_document_20261111.py`](tests/test_ltg_docx_alias_upstream_document_20261111.py).
|
|
175
|
+
They check requested content, text order, table dimensions, path and stream saves,
|
|
176
|
+
and unchanged unrelated package members.
|
|
177
|
+
|
|
178
|
+
The alias replaces `docx.shared`, `docx.document`, `docx.table`,
|
|
179
|
+
`docx.text.paragraph` and `docx.text.run` only while the upstream test modules are
|
|
180
|
+
imported. Every symbol under test resolves to its native `wolfdocx_docx` module
|
|
181
|
+
(`shared`, `document`, `table` or `text`). `ElementProxy`, the private `_Body`,
|
|
182
|
+
`_Column` and `_Columns` are pinned upstream fixture-only symbols: `_Body` serves
|
|
183
|
+
only as a mock specification and as the subject of excluded cases; `_Column` and
|
|
184
|
+
`_Columns` occur only in excluded column cases. Upstream fixtures, the lxml element
|
|
185
|
+
builder and mock
|
|
186
|
+
specifications, load from the pinned checkout during verification only.
|
|
187
|
+
The fixtures call the lower-level `Document(element, part)` constructor; it imports
|
|
188
|
+
the element into a fresh native builder and does not use the part. The following are
|
|
189
|
+
not qualified:
|
|
190
|
+
|
|
191
|
+
- private internals: the body object, the OPC part graph, `_block_width`, and the
|
|
192
|
+
constructor's upstream object-graph contract
|
|
193
|
+
- drop-in compatibility with python-docx
|
|
194
|
+
|
|
195
|
+
For each admitted case, the verifier traces setup, call and teardown. It fails if
|
|
196
|
+
native code calls upstream python-docx code, if a call runs no native code, or if the
|
|
197
|
+
test module or declared `document`/`table` fixture holds an object that is not native. Collection must
|
|
198
|
+
import no further upstream module while the alias is active.
|
|
199
|
+
|
|
200
|
+
The retained [verification receipt](upstream/verification.json) records the passing
|
|
201
|
+
and excluded node IDs, per-module and total denominators, per-case runtime
|
|
202
|
+
provenance, and the complete file exclusion inventory. It also records source,
|
|
203
|
+
environment and pinned-input identities, plus SHA-256 digests of the native
|
|
204
|
+
implementation files.
|
|
205
|
+
|
|
206
|
+
Separate consumer-facing tests cover Document, paragraph, run and table behavior in
|
|
207
|
+
[`tests/test_document.py`](tests/test_document.py), using independent package readers
|
|
208
|
+
and python-docx as a test-only output oracle.
|
|
209
|
+
|
|
210
|
+
From this package directory, in a POSIX shell:
|
|
211
|
+
|
|
212
|
+
```sh
|
|
213
|
+
uv run python tools/verify_upstream.py fetch
|
|
214
|
+
uv run --with lxml --with typing_extensions --with pyparsing python tools/verify_upstream.py verify \
|
|
215
|
+
--report "$HOME/.cache/wolfdocx-docx/upstream/verify-report.json" \
|
|
216
|
+
--portable-report upstream/verification.json
|
|
217
|
+
uv run pytest tests/test_shared.py tests/test_document.py \
|
|
218
|
+
tests/test_ltg_docx_alias_upstream_document_20261111.py \
|
|
219
|
+
tests/test_ltg_docx_alias_upstream_table_20261111.py \
|
|
220
|
+
tests/test_ltg_docx_alias_upstream_text_20261111.py
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Only `fetch` uses the network; `verify` runs offline against a clean external cache.
|
|
224
|
+
Choose the cache with `--cache-dir`. `--report` writes the raw receipt with local
|
|
225
|
+
paths; keep it outside the repository. `--portable-report` writes the same receipt
|
|
226
|
+
with repository-relative and `external-upstream-cache` paths for retention.
|
|
227
|
+
|
|
228
|
+
## WolfDocx agent-edit extensions
|
|
229
|
+
|
|
230
|
+
Use `document.wolf` for the following WolfDocx-only APIs. These are extensions,
|
|
231
|
+
not python-docx behavior. In particular, python-docx has no tracked-edit review,
|
|
232
|
+
thread reply/resolution, or persistent paragraph/run/table address API. Its own
|
|
233
|
+
comment API is not implemented by this alias; use the range API below instead.
|
|
234
|
+
|
|
235
|
+
```python
|
|
236
|
+
import wolfdocx_docx as docx
|
|
237
|
+
|
|
238
|
+
document = docx.Document("review.docx")
|
|
239
|
+
paragraph = document.wolf.identify(document.paragraphs[0])
|
|
240
|
+
run = document.wolf.identify(document.paragraphs[1].runs[0])
|
|
241
|
+
table = document.wolf.identify(document.tables[0])
|
|
242
|
+
metadata = {"author": "Editor", "date": "2026-11-09T12:00:00Z"}
|
|
243
|
+
# Replace a character range with native tracked deletion and insertion records.
|
|
244
|
+
document.wolf.track(paragraph, 0, 4, "Revised", **metadata)
|
|
245
|
+
document.save("tracked.docx")
|
|
246
|
+
|
|
247
|
+
reopened = docx.Document("tracked.docx")
|
|
248
|
+
for revision in reopened.wolf.revisions():
|
|
249
|
+
reopened.wolf.accept(revision) # or reject(revision)
|
|
250
|
+
comment = reopened.wolf.add_comment(paragraph, 0, 7, "Review wording", **metadata)
|
|
251
|
+
reopened.wolf.reply(comment, "Confirmed", **metadata)
|
|
252
|
+
reopened.wolf.resolve_comment(comment)
|
|
253
|
+
reopened.save("reviewed.docx")
|
|
254
|
+
|
|
255
|
+
final = docx.Document("reviewed.docx")
|
|
256
|
+
assert final.wolf.resolve(comment)["resolved"]
|
|
257
|
+
final.wolf.resolve(run).bold = True
|
|
258
|
+
final.wolf.resolve(table).cell(0, 0).text = "Address reused"
|
|
259
|
+
assert final.wolf.identify(final.wolf.resolve(paragraph)) == paragraph
|
|
260
|
+
final.save("reviewed.docx")
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
| API | Contract |
|
|
264
|
+
| --- | --- |
|
|
265
|
+
| `identify(object)` / `resolve(identifier)` | Persist and reuse identities for alias paragraphs, runs, tables, and listed comments, including after save/reopen. Refuse foreign/stale proxies, absent IDs, and ambiguous IDs. |
|
|
266
|
+
| `track(paragraph_id, start, end, text, author=..., date=...)` | Native tracked replacement in a main-story paragraph (including table cells); a zero-width range inserts, empty replacement text deletes. Return current revision records. |
|
|
267
|
+
| `revisions()` / `accept(record)` / `reject(record)` | List native main-story revisions and eligibility; decide exactly one discovered revision. Refuse stale or unsupported records through native review validation. |
|
|
268
|
+
| `add_comment(paragraph_id, start, end, text, author=..., date=..., initials=None)` | Anchor a new comment to a character range; return its `comment:N` address. |
|
|
269
|
+
| `comments()` / `reply(comment_id, text, author=..., date=..., initials=None)` | List comment records and anchors, parent IDs, and resolution state; return the address of a new reply. |
|
|
270
|
+
| `resolve_comment(comment_id, resolved=True)` | Resolve the native thread; pass `False` to reopen it. |
|
|
271
|
+
|
|
272
|
+
Offsets are zero-based native visible-text character offsets, with an exclusive
|
|
273
|
+
end. Supply a timezone-bearing ISO timestamp. Unsupported native contexts are
|
|
274
|
+
refused with `NodeEditError`; no formatting or annotation fallback is substituted.
|
|
275
|
+
Paragraph text and runs retain python-docx semantics: text inside tracked wrappers
|
|
276
|
+
is excluded until the review decision makes it direct paragraph content.
|
|
277
|
+
|
|
278
|
+
Review/comment mutations replace the in-memory snapshot. Re-resolve identifiers
|
|
279
|
+
afterwards; old proxies are stale. Identifiers on paragraphs, runs, and tables are
|
|
280
|
+
stored as ignorable namespaced XML attributes only when requested, not inferred
|
|
281
|
+
from ordinal positions or text. If a range operation splits an addressed run,
|
|
282
|
+
retain the identity on its first surviving fragment. An entirely removed object
|
|
283
|
+
has no live address. Comment IDs come from native package comment identities.
|
|
284
|
+
The preservation contract applies to this alias, not arbitrary third-party tools
|
|
285
|
+
that discard unknown XML attributes or renumber comments.
|
|
286
|
+
|
|
287
|
+
Focused [agent workflow tests](tests/test_agent.py) exercise insertion/deletion
|
|
288
|
+
accept and reject, anchored reply/resolve threads, and reuse of all four address
|
|
289
|
+
types after save/reopen, with unrelated content and opaque members unchanged.
|
|
290
|
+
These extension tests are separate from the pinned upstream-suite coverage.
|
|
291
|
+
|
|
292
|
+
## Speed
|
|
293
|
+
|
|
294
|
+
This package makes no speed claim and runs no speed benchmarks. Retained
|
|
295
|
+
checkpoint-1 native timings remain historical.
|
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
# WolfDocx python-docx import alias
|
|
2
|
+
|
|
3
|
+
Use `import wolfdocx_docx as docx` for the documented python-docx API subset over
|
|
4
|
+
WolfDocx's native document builder and verified session saves. Install this
|
|
5
|
+
separate, opt-in distribution alongside WolfDocx. The `docx` namespace remains
|
|
6
|
+
available to python-docx; no upstream runtime dependency or import replacement is
|
|
7
|
+
required.
|
|
8
|
+
|
|
9
|
+
## Install and use
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
pip install wolfdocx-docx
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The MIT `wolfdocx` engine is the only runtime dependency. Capabilities that
|
|
16
|
+
engine does not ship raise `ModuleNotFoundError("commercial_feature_unavailable")`.
|
|
17
|
+
|
|
18
|
+
```python
|
|
19
|
+
import wolfdocx_docx as docx
|
|
20
|
+
from wolfdocx_docx.shared import Inches, RGBColor
|
|
21
|
+
|
|
22
|
+
report = docx.Document()
|
|
23
|
+
report.add_heading("Operating review", level=1)
|
|
24
|
+
paragraph = report.add_paragraph("Status: ")
|
|
25
|
+
paragraph.add_run("approved").bold = True
|
|
26
|
+
cell = report.add_table(rows=1, cols=2).cell(0, 0)
|
|
27
|
+
cell.text = "Owner"
|
|
28
|
+
report.save("review.docx")
|
|
29
|
+
|
|
30
|
+
opened = docx.Document("review.docx")
|
|
31
|
+
opened.paragraphs[0].text = "Updated operating review"
|
|
32
|
+
opened.tables[0].cell(0, 1).text = "Finance"
|
|
33
|
+
opened.save("review.docx")
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Supported API
|
|
37
|
+
|
|
38
|
+
| Surface | Supported operations |
|
|
39
|
+
| --- | --- |
|
|
40
|
+
| Document | `Document()`, open a path or seekable binary stream; `paragraphs`, `tables`, `add_paragraph`, `add_heading` levels 0–9, `add_table`, `save` to a path or seekable binary stream |
|
|
41
|
+
| Paragraph | `text`, `runs`, `add_run(text, style)`, `clear()`, `alignment` |
|
|
42
|
+
| Run | `text`, tri-state `bold` and `italic`; boolean/`None` underline writes and existing OOXML underline-value reads |
|
|
43
|
+
| Table | `cell(row_idx, col_idx)`, live `rows` sequence (iteration, indexing and slicing), `add_row()`; zero-sized tables |
|
|
44
|
+
| Row | `cells`, including repeated grid positions for merged cells |
|
|
45
|
+
| Cell | `text`, `paragraphs`, `tables`, `grid_span`, `add_paragraph`, nested `add_table` |
|
|
46
|
+
| Shared values | `Length`, `Inches`, `Cm`, `Mm`, `Pt`, `Twips`, `Emu`, `RGBColor` |
|
|
47
|
+
|
|
48
|
+
Use zero-based table coordinates. Text assignments translate tabs and line breaks
|
|
49
|
+
as python-docx does. Preserve run formatting when assigning run text; preserve
|
|
50
|
+
paragraph properties and clear run formatting when assigning paragraph text.
|
|
51
|
+
Assign `docx.WD_ALIGN_PARAGRAPH.CENTER` (or the other native alignment constants)
|
|
52
|
+
to `paragraph.alignment`; assign `None` to inherit alignment from its style.
|
|
53
|
+
|
|
54
|
+
Resolve style names and IDs against an opened package's styles. For missing names
|
|
55
|
+
in new documents, create native minimal style definitions. The python-docx bundled
|
|
56
|
+
template and its formatting are outside this coverage. Style objects, pictures,
|
|
57
|
+
sections, headers and footers, core properties, the upstream comments API, full font APIs, OXML/OPC
|
|
58
|
+
internals, and all unlisted APIs are outside this coverage.
|
|
59
|
+
|
|
60
|
+
Save through the native verified session path before publication. For a path,
|
|
61
|
+
replace the destination atomically after staging; follow an existing symbolic link
|
|
62
|
+
to its target and retain existing file permissions. Return `None`, as python-docx
|
|
63
|
+
does. Preserve unchanged package members, including opaque parts. Native validation
|
|
64
|
+
refusals raise `wolfdocx.model.NodeEditError`. Native `wolfdocx.Document.save` retains
|
|
65
|
+
its separate no-clobber contract.
|
|
66
|
+
|
|
67
|
+
## Upstream coverage
|
|
68
|
+
|
|
69
|
+
Pin python-docx `v1.2.0` at commit
|
|
70
|
+
`e45454602b53e8e572b179ccf1c91093ec9f4ed7`. The MIT license and source-file digests are
|
|
71
|
+
recorded in [`upstream/pin.json`](upstream/pin.json); ship the derived shared-type
|
|
72
|
+
notice in [`THIRD_PARTY_NOTICES.txt`](THIRD_PARTY_NOTICES.txt).
|
|
73
|
+
[`upstream/expected.json`](upstream/expected.json) freezes the digest of `pin.json`, pins
|
|
74
|
+
upstream `tests/test_document.py`, `tests/test_table.py`,
|
|
75
|
+
`tests/text/test_paragraph.py` and `tests/text/test_run.py` by sha256 and git blob, and records the admitted
|
|
76
|
+
node IDs, every excluded node with its reason, and exclusion rules for every other
|
|
77
|
+
upstream test module and feature file. The admitted set was frozen before
|
|
78
|
+
implementation; changing it requires central approval.
|
|
79
|
+
|
|
80
|
+
Five unmodified upstream test modules run through the import alias. Every module
|
|
81
|
+
remains partially exercised; none is fully qualified:
|
|
82
|
+
|
|
83
|
+
| Upstream module | Passing cases | Excluded cases | Status |
|
|
84
|
+
| --- | --- | --- | --- |
|
|
85
|
+
| `tests/test_shared.py` | 18 of 21 | 3 `ElementProxy` cases | partial |
|
|
86
|
+
| `tests/test_document.py` | 8 of 32 | 24, each with its own reason | partial |
|
|
87
|
+
| `tests/test_table.py` | 24 of 150 | 126, each with its own reason | partial |
|
|
88
|
+
| `tests/text/test_paragraph.py` | 13 of 59 | 46, each with its own reason | partial |
|
|
89
|
+
| `tests/text/test_run.py` | 10 of 79 | 69, each with its own reason | partial |
|
|
90
|
+
|
|
91
|
+
The other 54 upstream test modules and 67 feature files remain excluded by rule.
|
|
92
|
+
Before the table and text admissions, the gate exercised 2 of 59 test modules and
|
|
93
|
+
passed 26 of 53 collected nodes, excluding 27 nodes and 124 other modules or feature
|
|
94
|
+
files. With both admissions, it exercises 5 of 59 modules and passes 73 of 341
|
|
95
|
+
collected nodes, excluding 268 nodes and 121 other modules or feature files. The
|
|
96
|
+
newly inventoried table and text modules account for the larger excluded-node
|
|
97
|
+
denominator; no formerly admitted node was removed. Never treat excluded cases as
|
|
98
|
+
passing.
|
|
99
|
+
|
|
100
|
+
The table cases cover grid-coordinate cell access, row enumeration, cell grid-span
|
|
101
|
+
and text reads (including tabs, breaks and multiple paragraphs), paragraph access,
|
|
102
|
+
and row-sequence iteration, indexing, bounds and owning-table access. The native
|
|
103
|
+
XML constructors import supplied XML into fresh native stories. For foreign lxml
|
|
104
|
+
input, serialize with lxml's C serializer to avoid invoking polymorphic upstream
|
|
105
|
+
text accessors. No upstream document, table or cell engine runs. The two native
|
|
106
|
+
XML child-list views used by the unchanged cell-access test do not qualify the
|
|
107
|
+
full upstream OXML object model or original input-element identity.
|
|
108
|
+
|
|
109
|
+
A separate focused edit/save/reopen scenario in
|
|
110
|
+
[`tests/test_ltg_docx_alias_upstream_table_20261111.py`](tests/test_ltg_docx_alias_upstream_table_20261111.py)
|
|
111
|
+
compares the same table-edit script against the pinned python-docx checkout in an
|
|
112
|
+
isolated process. It covers `add_row`, horizontal and vertical merged-cell
|
|
113
|
+
addressing, live row sequences and slices, cell replacement, paragraph append and
|
|
114
|
+
direct run-text edits. Preserve all direct run properties for run-text edits,
|
|
115
|
+
including unlisted font properties. Whole-cell text replacement intentionally
|
|
116
|
+
clears content and direct run formatting, as in python-docx. Structural merge,
|
|
117
|
+
row deletion and column mutation remain unsupported; no paragraph-deletion
|
|
118
|
+
fallback stands in for those operations. Check neighboring content, other tables,
|
|
119
|
+
non-table paragraphs and unchanged package members separately.
|
|
120
|
+
|
|
121
|
+
The 23 admitted text cases were frozen before implementation: paragraph text
|
|
122
|
+
reads (including hyperlinks, tabs and breaks), paragraph text replacement,
|
|
123
|
+
paragraph alignment reads, run text reads, and run bold/italic tri-state reads.
|
|
124
|
+
The bodies and pinned source files are unchanged. Other setters that assert
|
|
125
|
+
private upstream `_p.xml`/`_r.xml` serialization remain excluded, alongside style,
|
|
126
|
+
font, hyperlink-object, rendered-page-break and unimplemented authoring APIs.
|
|
127
|
+
Every excluded node and file has its own recorded reason.
|
|
128
|
+
|
|
129
|
+
Separate [save/reopen qualification](tests/test_ltg_docx_alias_upstream_text_20261111.py)
|
|
130
|
+
compares mixed-run edits, paragraph replacement, `add_run`, bold/italic and
|
|
131
|
+
alignment with python-docx loaded from the exact pinned source checkout. It checks
|
|
132
|
+
line breaks, retained paragraph styles, cleared run formatting after paragraph
|
|
133
|
+
replacement, untouched neighboring XML and byte-identical unrelated package parts.
|
|
134
|
+
Use the native lower-level Paragraph/Run XML constructors for detached text trees;
|
|
135
|
+
upstream OXML identity, serialization helpers and parent/part graphs remain outside
|
|
136
|
+
the public alias contract. Native input nodes retain their builder ownership.
|
|
137
|
+
|
|
138
|
+
The eight Document cases are upstream unit tests built on mocks:
|
|
139
|
+
|
|
140
|
+
- `add_heading` for levels 0, 1, 2 and 9 chooses the `Title` or `Heading N` style and
|
|
141
|
+
delegates to `add_paragraph`.
|
|
142
|
+
- `add_heading` rejects levels -1 and 10 with python-docx's message.
|
|
143
|
+
- `add_paragraph` passes `("", None)`, `("", "Heading 1")` and `("foo\rbar", "Body Text")`
|
|
144
|
+
to the document body and returns its result.
|
|
145
|
+
|
|
146
|
+
Each case calls the native `wolfdocx_docx.document.Document`. Its collaborators are
|
|
147
|
+
mocks specified from pinned upstream classes: the patched `add_paragraph` method, the
|
|
148
|
+
`_body` property, and the body, paragraph and document-part objects. These cases
|
|
149
|
+
prove method contracts, not saved content. Saved content is covered separately by the
|
|
150
|
+
native save/reopen tests in
|
|
151
|
+
[`tests/test_ltg_docx_alias_upstream_document_20261111.py`](tests/test_ltg_docx_alias_upstream_document_20261111.py).
|
|
152
|
+
They check requested content, text order, table dimensions, path and stream saves,
|
|
153
|
+
and unchanged unrelated package members.
|
|
154
|
+
|
|
155
|
+
The alias replaces `docx.shared`, `docx.document`, `docx.table`,
|
|
156
|
+
`docx.text.paragraph` and `docx.text.run` only while the upstream test modules are
|
|
157
|
+
imported. Every symbol under test resolves to its native `wolfdocx_docx` module
|
|
158
|
+
(`shared`, `document`, `table` or `text`). `ElementProxy`, the private `_Body`,
|
|
159
|
+
`_Column` and `_Columns` are pinned upstream fixture-only symbols: `_Body` serves
|
|
160
|
+
only as a mock specification and as the subject of excluded cases; `_Column` and
|
|
161
|
+
`_Columns` occur only in excluded column cases. Upstream fixtures, the lxml element
|
|
162
|
+
builder and mock
|
|
163
|
+
specifications, load from the pinned checkout during verification only.
|
|
164
|
+
The fixtures call the lower-level `Document(element, part)` constructor; it imports
|
|
165
|
+
the element into a fresh native builder and does not use the part. The following are
|
|
166
|
+
not qualified:
|
|
167
|
+
|
|
168
|
+
- private internals: the body object, the OPC part graph, `_block_width`, and the
|
|
169
|
+
constructor's upstream object-graph contract
|
|
170
|
+
- drop-in compatibility with python-docx
|
|
171
|
+
|
|
172
|
+
For each admitted case, the verifier traces setup, call and teardown. It fails if
|
|
173
|
+
native code calls upstream python-docx code, if a call runs no native code, or if the
|
|
174
|
+
test module or declared `document`/`table` fixture holds an object that is not native. Collection must
|
|
175
|
+
import no further upstream module while the alias is active.
|
|
176
|
+
|
|
177
|
+
The retained [verification receipt](upstream/verification.json) records the passing
|
|
178
|
+
and excluded node IDs, per-module and total denominators, per-case runtime
|
|
179
|
+
provenance, and the complete file exclusion inventory. It also records source,
|
|
180
|
+
environment and pinned-input identities, plus SHA-256 digests of the native
|
|
181
|
+
implementation files.
|
|
182
|
+
|
|
183
|
+
Separate consumer-facing tests cover Document, paragraph, run and table behavior in
|
|
184
|
+
[`tests/test_document.py`](tests/test_document.py), using independent package readers
|
|
185
|
+
and python-docx as a test-only output oracle.
|
|
186
|
+
|
|
187
|
+
From this package directory, in a POSIX shell:
|
|
188
|
+
|
|
189
|
+
```sh
|
|
190
|
+
uv run python tools/verify_upstream.py fetch
|
|
191
|
+
uv run --with lxml --with typing_extensions --with pyparsing python tools/verify_upstream.py verify \
|
|
192
|
+
--report "$HOME/.cache/wolfdocx-docx/upstream/verify-report.json" \
|
|
193
|
+
--portable-report upstream/verification.json
|
|
194
|
+
uv run pytest tests/test_shared.py tests/test_document.py \
|
|
195
|
+
tests/test_ltg_docx_alias_upstream_document_20261111.py \
|
|
196
|
+
tests/test_ltg_docx_alias_upstream_table_20261111.py \
|
|
197
|
+
tests/test_ltg_docx_alias_upstream_text_20261111.py
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Only `fetch` uses the network; `verify` runs offline against a clean external cache.
|
|
201
|
+
Choose the cache with `--cache-dir`. `--report` writes the raw receipt with local
|
|
202
|
+
paths; keep it outside the repository. `--portable-report` writes the same receipt
|
|
203
|
+
with repository-relative and `external-upstream-cache` paths for retention.
|
|
204
|
+
|
|
205
|
+
## WolfDocx agent-edit extensions
|
|
206
|
+
|
|
207
|
+
Use `document.wolf` for the following WolfDocx-only APIs. These are extensions,
|
|
208
|
+
not python-docx behavior. In particular, python-docx has no tracked-edit review,
|
|
209
|
+
thread reply/resolution, or persistent paragraph/run/table address API. Its own
|
|
210
|
+
comment API is not implemented by this alias; use the range API below instead.
|
|
211
|
+
|
|
212
|
+
```python
|
|
213
|
+
import wolfdocx_docx as docx
|
|
214
|
+
|
|
215
|
+
document = docx.Document("review.docx")
|
|
216
|
+
paragraph = document.wolf.identify(document.paragraphs[0])
|
|
217
|
+
run = document.wolf.identify(document.paragraphs[1].runs[0])
|
|
218
|
+
table = document.wolf.identify(document.tables[0])
|
|
219
|
+
metadata = {"author": "Editor", "date": "2026-11-09T12:00:00Z"}
|
|
220
|
+
# Replace a character range with native tracked deletion and insertion records.
|
|
221
|
+
document.wolf.track(paragraph, 0, 4, "Revised", **metadata)
|
|
222
|
+
document.save("tracked.docx")
|
|
223
|
+
|
|
224
|
+
reopened = docx.Document("tracked.docx")
|
|
225
|
+
for revision in reopened.wolf.revisions():
|
|
226
|
+
reopened.wolf.accept(revision) # or reject(revision)
|
|
227
|
+
comment = reopened.wolf.add_comment(paragraph, 0, 7, "Review wording", **metadata)
|
|
228
|
+
reopened.wolf.reply(comment, "Confirmed", **metadata)
|
|
229
|
+
reopened.wolf.resolve_comment(comment)
|
|
230
|
+
reopened.save("reviewed.docx")
|
|
231
|
+
|
|
232
|
+
final = docx.Document("reviewed.docx")
|
|
233
|
+
assert final.wolf.resolve(comment)["resolved"]
|
|
234
|
+
final.wolf.resolve(run).bold = True
|
|
235
|
+
final.wolf.resolve(table).cell(0, 0).text = "Address reused"
|
|
236
|
+
assert final.wolf.identify(final.wolf.resolve(paragraph)) == paragraph
|
|
237
|
+
final.save("reviewed.docx")
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
| API | Contract |
|
|
241
|
+
| --- | --- |
|
|
242
|
+
| `identify(object)` / `resolve(identifier)` | Persist and reuse identities for alias paragraphs, runs, tables, and listed comments, including after save/reopen. Refuse foreign/stale proxies, absent IDs, and ambiguous IDs. |
|
|
243
|
+
| `track(paragraph_id, start, end, text, author=..., date=...)` | Native tracked replacement in a main-story paragraph (including table cells); a zero-width range inserts, empty replacement text deletes. Return current revision records. |
|
|
244
|
+
| `revisions()` / `accept(record)` / `reject(record)` | List native main-story revisions and eligibility; decide exactly one discovered revision. Refuse stale or unsupported records through native review validation. |
|
|
245
|
+
| `add_comment(paragraph_id, start, end, text, author=..., date=..., initials=None)` | Anchor a new comment to a character range; return its `comment:N` address. |
|
|
246
|
+
| `comments()` / `reply(comment_id, text, author=..., date=..., initials=None)` | List comment records and anchors, parent IDs, and resolution state; return the address of a new reply. |
|
|
247
|
+
| `resolve_comment(comment_id, resolved=True)` | Resolve the native thread; pass `False` to reopen it. |
|
|
248
|
+
|
|
249
|
+
Offsets are zero-based native visible-text character offsets, with an exclusive
|
|
250
|
+
end. Supply a timezone-bearing ISO timestamp. Unsupported native contexts are
|
|
251
|
+
refused with `NodeEditError`; no formatting or annotation fallback is substituted.
|
|
252
|
+
Paragraph text and runs retain python-docx semantics: text inside tracked wrappers
|
|
253
|
+
is excluded until the review decision makes it direct paragraph content.
|
|
254
|
+
|
|
255
|
+
Review/comment mutations replace the in-memory snapshot. Re-resolve identifiers
|
|
256
|
+
afterwards; old proxies are stale. Identifiers on paragraphs, runs, and tables are
|
|
257
|
+
stored as ignorable namespaced XML attributes only when requested, not inferred
|
|
258
|
+
from ordinal positions or text. If a range operation splits an addressed run,
|
|
259
|
+
retain the identity on its first surviving fragment. An entirely removed object
|
|
260
|
+
has no live address. Comment IDs come from native package comment identities.
|
|
261
|
+
The preservation contract applies to this alias, not arbitrary third-party tools
|
|
262
|
+
that discard unknown XML attributes or renumber comments.
|
|
263
|
+
|
|
264
|
+
Focused [agent workflow tests](tests/test_agent.py) exercise insertion/deletion
|
|
265
|
+
accept and reject, anchored reply/resolve threads, and reuse of all four address
|
|
266
|
+
types after save/reopen, with unrelated content and opaque members unchanged.
|
|
267
|
+
These extension tests are separate from the pinned upstream-suite coverage.
|
|
268
|
+
|
|
269
|
+
## Speed
|
|
270
|
+
|
|
271
|
+
This package makes no speed claim and runs no speed benchmarks. Retained
|
|
272
|
+
checkpoint-1 native timings remain historical.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
python-docx v1.2.0
|
|
2
|
+
Source: https://github.com/python-openxml/python-docx
|
|
3
|
+
Commit: e45454602b53e8e572b179ccf1c91093ec9f4ed7
|
|
4
|
+
|
|
5
|
+
Portions of wolfdocx_docx/shared.py are derived from docx/shared.py.
|
|
6
|
+
|
|
7
|
+
The MIT License (MIT)
|
|
8
|
+
Copyright (c) 2013 Steve Canny, https://github.com/scanny
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in
|
|
18
|
+
all copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
26
|
+
THE SOFTWARE.
|