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.
@@ -0,0 +1,14 @@
1
+ .todos/
2
+ .venv/
3
+ .pytest_cache/
4
+ .ruff_cache/
5
+ __pycache__/
6
+ *.py[cod]
7
+ build/
8
+ dist/
9
+ *.egg-info/
10
+ [Bb]in/
11
+ obj/
12
+ private-packets/
13
+ private-commercial/
14
+ private-research/
@@ -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.