wolfdocx 0.1.0__tar.gz → 0.1.2__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.
Files changed (107) hide show
  1. wolfdocx-0.1.2/CHANGELOG.md +60 -0
  2. wolfdocx-0.1.2/PKG-INFO +617 -0
  3. wolfdocx-0.1.2/PROVENANCE.md +78 -0
  4. wolfdocx-0.1.2/README.md +583 -0
  5. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/pyproject.toml +8 -8
  6. wolfdocx-0.1.2/src/wolfdocx/__init__.py +955 -0
  7. wolfdocx-0.1.2/src/wolfdocx/_comment_extensions.py +185 -0
  8. wolfdocx-0.1.2/src/wolfdocx/_defaults.py +57 -0
  9. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/_inspection_cache.py +5 -3
  10. wolfdocx-0.1.2/src/wolfdocx/_optional.py +53 -0
  11. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/_version.py +1 -1
  12. wolfdocx-0.1.2/src/wolfdocx/assembly.py +8245 -0
  13. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/authoring.py +4 -8
  14. wolfdocx-0.1.2/src/wolfdocx/builder.py +3363 -0
  15. wolfdocx-0.1.2/src/wolfdocx/comments.py +2359 -0
  16. wolfdocx-0.1.2/src/wolfdocx/contracts.py +561 -0
  17. wolfdocx-0.1.2/src/wolfdocx/document.py +461 -0
  18. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/errors.py +5 -2
  19. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/find_replace.py +199 -59
  20. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/formatting.py +112 -16
  21. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/inspect.py +202 -17
  22. wolfdocx-0.1.2/src/wolfdocx/load_options.py +2013 -0
  23. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/model.py +156 -11
  24. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/numbering_authoring.py +42 -121
  25. wolfdocx-0.1.2/src/wolfdocx/ooxml_order.py +61 -0
  26. wolfdocx-0.1.2/src/wolfdocx/output.py +1468 -0
  27. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/page_setup.py +179 -119
  28. wolfdocx-0.1.2/src/wolfdocx/paragraph_format_effective.py +431 -0
  29. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/properties.py +3 -3
  30. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/protection.py +193 -27
  31. wolfdocx-0.1.2/src/wolfdocx/render_warnings.py +252 -0
  32. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/reporting.py +2 -4
  33. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/review.py +53 -34
  34. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/section_break.py +29 -0
  35. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/__init__.py +2 -0
  36. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/_bridge.py +32 -0
  37. wolfdocx-0.1.2/src/wolfdocx/session_ops/pictures.py +87 -0
  38. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/rich_objects.py +1883 -47
  39. wolfdocx-0.1.2/src/wolfdocx/style_resolution.py +1244 -0
  40. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/styles_authoring.py +26 -24
  41. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_cell_properties.py +138 -13
  42. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_column.py +65 -34
  43. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_delete.py +1 -2
  44. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_merge.py +255 -93
  45. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_properties.py +120 -14
  46. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_row_properties.py +102 -16
  47. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_structure.py +3 -6
  48. wolfdocx-0.1.2/src/wolfdocx/web_extensions.py +850 -0
  49. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/docx_fixtures.py +2 -4
  50. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_section_break.py +1 -1
  51. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_inspect.py +23 -12
  52. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_table_column.py +3 -2
  53. wolfdocx-0.1.0/CHANGELOG.md +0 -21
  54. wolfdocx-0.1.0/PKG-INFO +0 -127
  55. wolfdocx-0.1.0/PROVENANCE.md +0 -8
  56. wolfdocx-0.1.0/README.md +0 -93
  57. wolfdocx-0.1.0/src/wolfdocx/__init__.py +0 -25
  58. wolfdocx-0.1.0/src/wolfdocx/assembly.py +0 -463
  59. wolfdocx-0.1.0/src/wolfdocx/document.py +0 -215
  60. wolfdocx-0.1.0/src/wolfdocx/output.py +0 -13
  61. wolfdocx-0.1.0/src/wolfdocx/render_warnings.py +0 -106
  62. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/.gitignore +0 -0
  63. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/LICENSE +0 -0
  64. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/SECURITY.md +0 -0
  65. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/_cache_root.py +0 -0
  66. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/_comment_threads.py +0 -0
  67. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/admission.py +0 -0
  68. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/canonical.py +0 -0
  69. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/content.py +0 -0
  70. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/package.py +0 -0
  71. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/package_profile.py +0 -0
  72. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/paragraph_authoring.py +0 -0
  73. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/regions.py +0 -0
  74. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/run_text.py +0 -0
  75. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/lists.py +0 -0
  76. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/paragraphs.py +0 -0
  77. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/run_edits.py +0 -0
  78. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/runs.py +0 -0
  79. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/sections.py +0 -0
  80. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/styling.py +0 -0
  81. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/tables.py +0 -0
  82. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_insert.py +0 -0
  83. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/text_effects.py +0 -0
  84. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/__init__.py +0 -0
  85. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/conftest.py +0 -0
  86. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_cells.py +0 -0
  87. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_page_setup.py +0 -0
  88. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_regions.py +0 -0
  89. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_spans.py +0 -0
  90. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_table_cell_properties.py +0 -0
  91. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_table_insert.py +0 -0
  92. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_table_merge.py +0 -0
  93. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_table_properties.py +0 -0
  94. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_table_row_properties.py +0 -0
  95. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_table_structure.py +0 -0
  96. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_document_session.py +0 -0
  97. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_document_session_paragraphs.py +0 -0
  98. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_find_replace.py +0 -0
  99. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_find_replace_no_match.py +0 -0
  100. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_find_replace_portfolio_edits.py +0 -0
  101. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_node_visitor.py +0 -0
  102. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_package_graph.py +0 -0
  103. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_package_open_tolerance.py +0 -0
  104. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_package_profile.py +0 -0
  105. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_paragraph_authoring.py +0 -0
  106. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_run_text_edit.py +0 -0
  107. {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_table_delete.py +0 -0
@@ -0,0 +1,60 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file. The format is
4
+ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
5
+ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [0.1.2] - 2026-11-18
8
+
9
+ ### Changed
10
+
11
+ - The package is regenerated from one source commit. Every module is an unmodified
12
+ copy of that commit's file, and `PROVENANCE.md` names the commit and lists the
13
+ SHA-256 of each module.
14
+ - The distribution version is read from `wolfdocx/_version.py`, so the installed
15
+ version and `wolfdocx.__version__` always agree.
16
+ - Requesting a capability this package does not ship, such as PDF output through
17
+ `SaveOptions.create("pdf")`, raises `ModuleNotFoundError` with the message
18
+ `commercial_feature_unavailable`.
19
+
20
+ ### Added
21
+
22
+ - The modules the regenerated core imports: load options, contract records,
23
+ effective paragraph formatting, style resolution, OOXML child ordering, web
24
+ extension part preservation, picture session edits, and the optional-feature
25
+ loader.
26
+ - `wolfdocx.builder.DocumentBuilder` for new documents with paragraphs, runs, tables
27
+ and sections, and `wolfdocx.comments` for comment threads, so the `wolfdocx-docx`
28
+ import alias runs on this package alone. Builder pictures, shapes, hyperlinks,
29
+ document settings and fields raise
30
+ `ModuleNotFoundError("commercial_feature_unavailable")`.
31
+
32
+ ## [0.1.1] - 2026-11-09
33
+
34
+ Documentation and package metadata only. The library code is unchanged from 0.1.0.
35
+
36
+ ### Changed
37
+
38
+ - README rewritten with a runnable example for each operation, a python-docx
39
+ comparison, the list of tasks the MIT package does not cover, and links to the
40
+ guides at [wolfdocx.com/docs](https://wolfdocx.com/docs).
41
+ - Package description and keywords no longer suggest that WolfDocx creates
42
+ documents from scratch; it reads and edits existing `.docx` files.
43
+
44
+ ## [0.1.0] - 2026-10-29
45
+
46
+ ### Added
47
+
48
+ - First public release under the MIT license.
49
+ - `Document` session for opening an existing `.docx`, with in-memory edits
50
+ published only by `save`.
51
+ - Node navigation through `Document.node` for reading stories, paragraphs, runs,
52
+ and tables.
53
+ - Edits: `set_run_text`, `find_replace`, `append_paragraph`, and related session
54
+ operations.
55
+ - Verified, no-clobber saves that copy every untouched package part byte-for-byte
56
+ and report changed and raw-copied parts.
57
+
58
+ [0.1.2]: https://github.com/wolfiesch/wolfdocx-oss/releases/tag/v0.1.2
59
+ [0.1.1]: https://github.com/wolfiesch/wolfdocx-oss/releases/tag/v0.1.1
60
+ [0.1.0]: https://github.com/wolfiesch/wolfdocx-oss/releases/tag/v0.1.0
@@ -0,0 +1,617 @@
1
+ Metadata-Version: 2.5
2
+ Name: wolfdocx
3
+ Version: 0.1.2
4
+ Summary: Read and edit existing Word .docx files in Python. A python-docx alternative that edits documents in place and keeps every untouched part byte-for-byte identical. Pure Python, MIT licensed.
5
+ Project-URL: Homepage, https://wolfdocx.com
6
+ Project-URL: Repository, https://github.com/wolfiesch/wolfdocx-oss
7
+ Project-URL: Issues, https://github.com/wolfiesch/wolfdocx-oss/issues
8
+ Project-URL: Changelog, https://github.com/wolfiesch/wolfdocx-oss/blob/main/CHANGELOG.md
9
+ Author: Wolfgang Schoenberger
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: document,docx,edit-docx,office,office-automation,openxml,python-docx,python-docx-alternative,reporting,word
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Office/Business :: Office Suites
24
+ Classifier: Topic :: Software Development :: Libraries
25
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
26
+ Classifier: Topic :: Text Processing
27
+ Requires-Python: >=3.11
28
+ Provides-Extra: dev
29
+ Requires-Dist: build>=1.2; extra == 'dev'
30
+ Requires-Dist: pytest>=8.3; extra == 'dev'
31
+ Requires-Dist: ruff==0.17.3; extra == 'dev'
32
+ Requires-Dist: twine>=6.1; extra == 'dev'
33
+ Description-Content-Type: text/markdown
34
+
35
+ # WolfDocx
36
+
37
+ **Edit existing Word `.docx` files from Python and keep every part you did not touch byte-for-byte identical. A pure-Python, MIT-licensed python-docx alternative for documents that already exist.**
38
+
39
+ WolfDocx opens a `.docx`, reads its paragraphs, runs, and tables, applies edits in
40
+ memory, and saves a new file. Each edit rewrites only the parts it changes; every
41
+ other part of the package is copied from the source unchanged. An edit that cannot be
42
+ applied safely is refused with a code and leaves the document as it was.
43
+ `wolfdocx.builder.DocumentBuilder` writes a new document with paragraphs, runs,
44
+ tables, and sections. WolfDocx does not render pages or convert to PDF.
45
+
46
+ [![PyPI](https://img.shields.io/pypi/v/wolfdocx)](https://pypi.org/project/wolfdocx/)
47
+ [![Python versions](https://img.shields.io/pypi/pyversions/wolfdocx)](https://pypi.org/project/wolfdocx/)
48
+ [![CI](https://github.com/wolfiesch/wolfdocx-oss/actions/workflows/ci.yml/badge.svg)](https://github.com/wolfiesch/wolfdocx-oss/actions/workflows/ci.yml)
49
+ [![License: MIT](https://img.shields.io/pypi/l/wolfdocx)](https://github.com/wolfiesch/wolfdocx-oss/blob/main/LICENSE)
50
+
51
+ [Quickstart](https://github.com/wolfiesch/wolfdocx-oss#quickstart) ·
52
+ [Usage](https://github.com/wolfiesch/wolfdocx-oss#usage) ·
53
+ [Coming from python-docx](https://github.com/wolfiesch/wolfdocx-oss#coming-from-python-docx) ·
54
+ [Community and Commercial](https://github.com/wolfiesch/wolfdocx-oss#what-the-mit-package-does-not-include) ·
55
+ [Docs](https://wolfdocx.com/docs) ·
56
+ [Changelog](https://github.com/wolfiesch/wolfdocx-oss/blob/main/CHANGELOG.md) ·
57
+ [Issues](https://github.com/wolfiesch/wolfdocx-oss/issues) ·
58
+ [wolfdocx.com](https://wolfdocx.com/)
59
+
60
+ ```bash
61
+ pip install wolfdocx
62
+ ```
63
+
64
+ Replace a phrase that Word split across two runs, update a table cell, and save a
65
+ new file:
66
+
67
+ ```python
68
+ from wolfdocx import Document
69
+
70
+ with Document("contract.docx") as doc:
71
+ doc.find_replace(r"ACME Corp\.", "Acme Corporation") # matches across runs
72
+ doc.set_cell_text(table=1, row=2, cell=2, text="$7,500")
73
+ report = doc.save("contract-final.docx")
74
+
75
+ print(report.status, report.changed_parts, report.raw_copied_parts)
76
+ ```
77
+
78
+ ```text
79
+ published ('word/document.xml',) 16
80
+ ```
81
+
82
+ Only `word/document.xml` was rewritten. The other 16 parts of the package, including
83
+ styles, numbering, settings, theme, fonts, and relationships, were copied from the
84
+ source with their original compressed bytes. In `contract.docx`, "ACME" is a bold run
85
+ and " Corp." a plain one; the replacement takes the run formatting of the first
86
+ matched character that has any, so "Acme Corporation" comes out bold.
87
+
88
+ ## Why WolfDocx
89
+
90
+ Use WolfDocx when a script has to change a document someone else maintains, such as a
91
+ contract, a report, or a template, and the rest of that file must stay exactly as it
92
+ was.
93
+
94
+ - **Edits stay local.** Each edit rewrites only the parts it needs, usually
95
+ `word/document.xml`. Run properties, attributes, and neighboring markup stay where
96
+ they were.
97
+ - **Untouched parts are copied, not re-serialized.** On save, every part you did not
98
+ change keeps its compressed bytes and ZIP entry metadata. Opening a document and
99
+ saving it without edits produces a byte-identical file.
100
+ - **Refusals instead of guesses.** An edit that cannot be applied safely (a stale
101
+ `expected_old_text`, a missing target, an unsupported structure, a pattern with no
102
+ match) returns `status == "refused"` and a `code`, and the document is unchanged.
103
+ `set_run_text` raises `RunTextEditError` instead.
104
+ - **No-clobber, verified saves.** `save` stages the output, checks it, and only then
105
+ publishes it. It never replaces an existing file.
106
+ - **Pure Python, no runtime dependencies.** The standard library is enough for
107
+ everything except XPath selection, which needs `lxml`. No Word or LibreOffice
108
+ install is needed.
109
+
110
+ ## Capabilities
111
+
112
+ All edits are methods on `Document` and are held in memory until `save`.
113
+
114
+ | Area | API |
115
+ | --- | --- |
116
+ | Open and save | `Document(path_or_stream)`, `Document.from_bytes(data, path=...)`, `save(path_or_stream)`, `close()` |
117
+ | Read | `node`, `stories`, `get_story(StoryType...)`, `Node.paragraphs`, `runs`, `tables`, `get_child_nodes(NodeType..., deep=True)`, `to_string("txt")`, `accept(DocumentVisitor)` |
118
+ | Text | `find_replace` (regex, across runs and paragraphs), `set_run_text`, `Node.text = ...` on a run, `insert_run`, `delete_run` |
119
+ | Paragraphs | `append_paragraph`, `insert_paragraph`, `delete_paragraph`, `split_paragraph` |
120
+ | Formatting | `format_text` (bold, italic, underline, strike, color, size, character style), `format_paragraph` (style, alignment, spacing, indent, keep with next, borders, tabs) |
121
+ | Tables | `set_cell_text`, `insert_table`, `delete_table`, `insert_table_row`, `delete_table_row`, `insert_table_column`, `delete_table_column`, `merge_table_cells`, `split_table_cells` |
122
+ | Lists | `apply_list`, `remove_list`, `restart_list`, `insert_list_item` (with a numbering definition the document already has) |
123
+ | Sections | `set_page_setup` (page size, orientation, margins, columns), `insert_section_break`, `delete_section_break`, `edit_header_footer` |
124
+ | Definitions | `styles`, `lists`, `background` as editable copies you assign back |
125
+ | Approved-value edits | `wolfdocx.reporting`: discover editable cells and paragraphs, then apply edits bound to the source file's SHA-256 |
126
+ | New documents | `wolfdocx.builder.DocumentBuilder`: `write_paragraph`, `append_run`, `insert_table`, `add_table`, `add_section`, `save` |
127
+ | Comments | `wolfdocx.comments`: `discover_comment_targets`, then `author_comment` to insert, update, or delete a comment bound to the source text |
128
+
129
+ ## Quickstart
130
+
131
+ Requirements: Python 3.11 or newer. WolfDocx has no runtime dependencies, and Word
132
+ and LibreOffice are not needed.
133
+
134
+ ```bash
135
+ pip install wolfdocx
136
+ ```
137
+
138
+ The examples in this README use `contract.docx`, a small document with four body
139
+ paragraphs and one table. Print its paragraphs and table rows:
140
+
141
+ ```python
142
+ from wolfdocx import Document, NodeType, StoryType
143
+
144
+ with Document("contract.docx") as doc:
145
+ body = doc.get_story(StoryType.BODY)
146
+
147
+ for paragraph in body.paragraphs:
148
+ print(paragraph.to_string("txt").rstrip("\n"))
149
+
150
+ for table in body.tables:
151
+ for row in table.get_child_nodes(NodeType.ROW):
152
+ print([cell.to_string("txt").strip() for cell in row.get_child_nodes(NodeType.CELL)])
153
+ ```
154
+
155
+ ```text
156
+ Services Agreement
157
+ This agreement is between ACME Corp. and the Client.
158
+ Status: Draft
159
+ Payment is due within 30 days.
160
+ ['Item', 'Amount']
161
+ ['Setup fee', '$0']
162
+ ['Monthly fee', '$1,200']
163
+ ```
164
+
165
+ `Document` accepts a path or an open, seekable binary stream. Use it as a context
166
+ manager, or call `close()`, to release the source snapshot. `doc.node` and the story
167
+ nodes are snapshots: read them again after an edit to see the updated tree.
168
+
169
+ ## Usage
170
+
171
+ ### How targets are addressed
172
+
173
+ Read this before the edit methods, because two conventions are in use:
174
+
175
+ - `set_run_text(paragraph, run, ...)` takes **zero-based** indices that count only the
176
+ direct paragraphs of the body and the direct runs of that paragraph. Paragraphs
177
+ inside tables do not count.
178
+ - Every other edit method takes **1-based** numbers. `paragraph` counts every
179
+ paragraph of the part in document order, including paragraphs inside table cells,
180
+ and `table`, `row`, `cell`, and `column` count from 1.
181
+
182
+ In `contract.docx`, the last body paragraph ("Payment is due...") is paragraph 3 for
183
+ `set_run_text` and paragraph 10 for the other methods, because the six table cells
184
+ each hold one paragraph.
185
+
186
+ ### Replace text and keep run formatting
187
+
188
+ `find_replace` runs a Python regular expression over the text of one part
189
+ (`word/document.xml` by default), so a phrase Word split across several runs still
190
+ matches. The replacement takes the run formatting of the first matched character that
191
+ has any.
192
+ The replacement can be a string or a function of the match.
193
+
194
+ ```python
195
+ from wolfdocx import Document
196
+
197
+ with Document("contract.docx") as doc:
198
+ report = doc.find_replace(
199
+ r"acme corp\.",
200
+ "Acme Corporation",
201
+ options={"ignore_case": True, "max_replacements": 1},
202
+ )
203
+ print(report.status, report.match_count, report.replacement_count)
204
+
205
+ report = doc.find_replace(r"\$([\d,]+)", lambda m: f"USD {m.group(1)}")
206
+ print(report.status, report.replacement_count)
207
+
208
+ report = doc.find_replace("Net 60", "Net 30")
209
+ print(report.status, report.code)
210
+
211
+ print(doc.save("contract-replaced.docx").status)
212
+ ```
213
+
214
+ ```text
215
+ applied 1 1
216
+ applied 2
217
+ refused find_replace_no_match
218
+ published
219
+ ```
220
+
221
+ Pass `part="word/header1.xml"` (or any other part name from `doc.part_names`) to
222
+ search a header, footer, or other story. Matches inside tracked revisions and field
223
+ instructions are refused with `find_replace_protected_text`.
224
+
225
+ To change the text of one run and keep its run properties, use `set_run_text`. The
226
+ optional `expected_old_text` guard refuses the edit if the run no longer holds the
227
+ text you expect:
228
+
229
+ ```python
230
+ from wolfdocx import Document
231
+ from wolfdocx.run_text import RunTextEditError
232
+
233
+ with Document("contract.docx") as doc:
234
+ # Zero-based: body paragraph 1, run 1 is the bold "ACME" run.
235
+ doc.set_run_text(1, 1, "Acme", expected_old_text="ACME")
236
+
237
+ try:
238
+ doc.set_run_text(2, 0, "Status: Final", expected_old_text="Status: Signed")
239
+ except RunTextEditError as error:
240
+ print("refused:", error.code)
241
+
242
+ body = doc.node.children[0] # read the snapshot again after the edit
243
+ print(body.paragraphs[1].to_string("txt").rstrip("\n"))
244
+ print(doc.save("contract-renamed.docx").status)
245
+ ```
246
+
247
+ ```text
248
+ refused: run_text_guard_mismatch
249
+ This agreement is between Acme Corp. and the Client.
250
+ published
251
+ ```
252
+
253
+ The saved run is still `<w:r><w:rPr><w:b /></w:rPr><w:t>Acme</w:t></w:r>`.
254
+ Assigning `run.text` on a run node from the tree does the same thing, in the style of
255
+ python-docx:
256
+
257
+ ```python
258
+ from wolfdocx import Document, NodeType
259
+
260
+ with Document("contract.docx") as doc:
261
+ body = doc.node.children[0]
262
+ for run in body.get_child_nodes(NodeType.RUN, deep=True):
263
+ if "ACME" in run.text:
264
+ run.text = run.text.replace("ACME", "Acme")
265
+
266
+ report = doc.save("contract-runs.docx")
267
+ print(report.status, report.changed_parts)
268
+ ```
269
+
270
+ ```text
271
+ published ('word/document.xml',)
272
+ ```
273
+
274
+ ### Update table cells and rows
275
+
276
+ ```python
277
+ from wolfdocx import Document, NodeType
278
+
279
+ with Document("contract.docx") as doc:
280
+ # Tables, rows, and cells are 1-based.
281
+ print(doc.set_cell_text(table=1, row=2, cell=2, text="$7,500", expected_old_text="$0").status)
282
+ print(doc.set_cell_text(table=1, row=3, cell=2, text="$900", expected_old_text="$1,000").code)
283
+
284
+ print(doc.insert_table_row(1, 3, cell_texts=["Support", "$300"]).status)
285
+ print(doc.delete_table_row(1, 2).status)
286
+
287
+ table = doc.node.children[0].tables[0]
288
+ for row in table.get_child_nodes(NodeType.ROW):
289
+ print([cell.to_string("txt").strip() for cell in row.get_child_nodes(NodeType.CELL)])
290
+
291
+ print(doc.save("contract-table.docx").status)
292
+ ```
293
+
294
+ ```text
295
+ applied
296
+ expected_old_text_mismatch
297
+ applied
298
+ applied
299
+ ['Item', 'Amount']
300
+ ['Monthly fee', '$1,200']
301
+ ['Support', '$300']
302
+ published
303
+ ```
304
+
305
+ `insert_table_row` clones the structure of the row it is inserted next to.
306
+ `insert_table(paragraph, rows, grid_widths)` adds a new table after (or before) a
307
+ paragraph, with column widths in twentieths of a point:
308
+
309
+ ```python
310
+ doc.insert_table(10, [["Milestone", "Date"], ["Kickoff", "2026-12-01"]], [4320, 4320], repeat_header=True)
311
+ ```
312
+
313
+ A `style` passed to `insert_table` must be a table style the document defines and
314
+ WolfDocx supports; otherwise the edit is refused (for example
315
+ `table_properties_style_unsupported`). `merge_table_cells` refuses a merge that would
316
+ drop text from the merged cells.
317
+
318
+ ### Add paragraphs, format text, and change the page
319
+
320
+ ```python
321
+ from wolfdocx import Document
322
+
323
+ with Document("contract.docx") as doc:
324
+ doc.format_text(1, 0, 8, color="C00000") # characters 0-8 of "Services Agreement"
325
+ doc.format_paragraph(1, alignment="center")
326
+ doc.insert_paragraph(3, "Effective date: 1 December 2026") # after "Status: Draft"
327
+ doc.append_paragraph("Signed electronically.", style="Heading2")
328
+ doc.edit_header_footer("footer", "create", paragraphs=[{"text": "Confidential"}])
329
+ doc.set_page_setup(orientation="landscape")
330
+
331
+ report = doc.save("contract-extended.docx")
332
+ print(report.status)
333
+ print(report.changed_parts)
334
+ print(report.added_parts)
335
+ ```
336
+
337
+ ```text
338
+ published
339
+ ('[Content_Types].xml', 'word/_rels/document.xml.rels', 'word/document.xml')
340
+ ('word/footer1.xml',)
341
+ ```
342
+
343
+ `style` takes a style ID that already exists in the document (`Heading2` here); an
344
+ unknown style is refused with `paragraph_style_missing`. `alignment` accepts Word's
345
+ `ST_Jc` values such as `left`, `center`, `right`, and `both`, and python-docx
346
+ `WD_PARAGRAPH_ALIGNMENT` names or members.
347
+
348
+ ### Apply approved values bound to a reviewed file
349
+
350
+ `wolfdocx.reporting` is a request-based API for pipelines that may change only
351
+ values someone approved. `discover_report_targets` lists each editable table cell
352
+ and paragraph with its current text and a structure fingerprint, plus the SHA-256 of
353
+ the source. `author_report` applies all edits or none, and writes the destination
354
+ only when every edit verifies.
355
+
356
+ ```python
357
+ from wolfdocx.reporting import author_report, discover_report_targets, parse_report_request
358
+
359
+ found = discover_report_targets("contract.docx")
360
+ cells = {t["expected_old_text"]: t for t in found["targets"] if t["kind"] == "cell"}
361
+ texts = {t["expected_old_text"]: t for t in found["targets"] if t["kind"] == "text"}
362
+
363
+ report = author_report(parse_report_request({
364
+ "source": "contract.docx",
365
+ "destination": "contract-approved.docx",
366
+ "source_sha256": found["source_sha256"],
367
+ "edits": [
368
+ {**cells["$0"], "text": "$7,500"},
369
+ {**texts["Status: Draft"], "expected_old_text": "Draft", "text": "Final"},
370
+ ],
371
+ }))
372
+ print(report.status, report.code, report.unselected_parts_preserved)
373
+ ```
374
+
375
+ ```text
376
+ published None True
377
+ ```
378
+
379
+ If the source changed after discovery the request is refused with
380
+ `source_hash_mismatch`; if one edit's `expected_old_text` no longer matches, the
381
+ whole request is refused with `expected_old_text_mismatch`. In both cases no
382
+ destination file is written. Walkthroughs:
383
+ [replace text in a Word document](https://wolfdocx.com/replace-text-docx-python) and
384
+ [update table cells](https://wolfdocx.com/update-docx-table-python).
385
+
386
+ ### Save safely and verify what changed
387
+
388
+ ```python
389
+ import io
390
+ import zipfile
391
+
392
+ from wolfdocx import Document
393
+
394
+ with zipfile.ZipFile("contract.docx") as before, zipfile.ZipFile("contract-final.docx") as after:
395
+ changed = [n for n in before.namelist() if before.read(n) != after.read(n)]
396
+ print(len(before.namelist()), "parts, changed:", changed)
397
+
398
+ with Document("contract.docx") as doc:
399
+ doc.find_replace("Draft", "Final")
400
+ refused = doc.save("contract-final.docx") # this file already exists
401
+ print(refused.status, refused.code)
402
+
403
+ buffer = io.BytesIO()
404
+ print(doc.save(buffer).status)
405
+
406
+ with Document.from_bytes(buffer.getvalue(), path="in-memory.docx") as copy:
407
+ print(copy.node.children[0].paragraphs[2].to_string("txt").rstrip("\n"))
408
+ ```
409
+
410
+ ```text
411
+ 17 parts, changed: ['word/document.xml']
412
+ refused document_destination_exists
413
+ published
414
+ Status: Final
415
+ ```
416
+
417
+ The save report lists `changed_parts`, `added_parts`, `removed_parts`,
418
+ `raw_copied_parts`, `destination_sha256`, and the `edits` applied, and
419
+ `report.to_dict()` returns them as a dictionary. A stream destination must be
420
+ seekable and empty. Saving a macro-enabled document under a `.docx` name is refused
421
+ with `document_destination_extension_mismatch`.
422
+
423
+ ### Walk the document tree
424
+
425
+ `Document.accept` visits stories, paragraphs, runs, tables, rows, cells, fields,
426
+ bookmarks, comments, shapes, and other nodes in document order. Override the
427
+ `visit_<type>_start` and `visit_<type>_end` methods you need:
428
+
429
+ ```python
430
+ from wolfdocx import Document, DocumentVisitor, VisitorAction
431
+
432
+
433
+ class Counter(DocumentVisitor):
434
+ def __init__(self):
435
+ self.paragraphs = 0
436
+ self.tables = 0
437
+
438
+ def visit_paragraph_start(self, node):
439
+ self.paragraphs += 1
440
+ return VisitorAction.CONTINUE
441
+
442
+ def visit_table_start(self, node):
443
+ self.tables += 1
444
+ return VisitorAction.SKIP_CHILDREN # do not count paragraphs inside tables
445
+
446
+
447
+ with Document("contract.docx") as doc:
448
+ counter = Counter()
449
+ doc.accept(counter)
450
+ print(counter.paragraphs, counter.tables)
451
+ ```
452
+
453
+ ```text
454
+ 4 1
455
+ ```
456
+
457
+ `Node.select_nodes(xpath)` runs XPath 1.0 queries over the tree. It is the one
458
+ feature that needs a third-party package: install `lxml` to use it.
459
+
460
+ ## Coming from python-docx
461
+
462
+ WolfDocx is not a drop-in replacement for python-docx. Its API is built around an
463
+ editing session and explicit targets. Common python-docx calls map like this:
464
+
465
+ | python-docx | WolfDocx |
466
+ | --- | --- |
467
+ | `Document("in.docx")` | `Document("in.docx")`, preferably as a context manager |
468
+ | `Document()` (new document from the default template) | `DocumentBuilder()` from `wolfdocx.builder`, for paragraphs, runs, tables, and sections |
469
+ | `doc.paragraphs`, `paragraph.text` | `doc.get_story(StoryType.BODY).paragraphs`, `paragraph.to_string("txt")` |
470
+ | `doc.tables`, `table.rows`, `row.cells`, `cell.text` | `body.tables`, `table.get_child_nodes(NodeType.ROW)`, `row.get_child_nodes(NodeType.CELL)`, `cell.to_string("txt")` |
471
+ | `run.text = "..."` | `run.text = "..."` on a run node, or `doc.set_run_text(paragraph, run, "...")` |
472
+ | `cell.text = "..."` | `doc.set_cell_text(table=1, row=2, cell=2, text="...")` |
473
+ | `doc.add_paragraph(text, style)` | `doc.append_paragraph(text, style=...)` or `doc.insert_paragraph(n, text)` |
474
+ | `doc.add_table(rows, cols)` | `doc.insert_table(paragraph, rows, grid_widths)` |
475
+ | `paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER` | `doc.format_paragraph(n, alignment="center")` |
476
+ | `section.orientation = WD_ORIENT.LANDSCAPE` | `doc.set_page_setup(orientation="landscape")` |
477
+ | `doc.save("out.docx")` | `doc.save("out.docx")`, which refuses to replace an existing file |
478
+
479
+ Differences to plan for:
480
+
481
+ - Edits go through `Document` methods and return a report. Check `report.passed` or
482
+ `report.status` instead of assuming the edit landed.
483
+ - `doc.node` and the nodes under it are snapshots. Read them again after an edit
484
+ method.
485
+ - Paragraph numbers are 1-based and include paragraphs in table cells, except in
486
+ `set_run_text` (see [How targets are addressed](https://github.com/wolfiesch/wolfdocx-oss#how-targets-are-addressed)).
487
+ - python-docx has no built-in find and replace; `find_replace` handles phrases split
488
+ across runs.
489
+ - For python-docx call names, `pip install wolfdocx-docx` adds
490
+ `import wolfdocx_docx as docx`, a subset of the python-docx API that runs on this
491
+ package. Keep python-docx for new documents that need pictures, shapes,
492
+ hyperlinks, or fields. A
493
+ [comparison](https://wolfdocx.com/python-docx-alternative) and a
494
+ [migration checklist](https://wolfdocx.com/python-docx-migration) for the
495
+ Commercial API are on wolfdocx.com.
496
+
497
+ ## What the MIT package does not include
498
+
499
+ This repository is WolfDocx Community, the MIT-licensed read and edit core published
500
+ on PyPI. It does not:
501
+
502
+ - add pictures, shapes, hyperlinks, fields, or document settings to a document
503
+ built with `DocumentBuilder`;
504
+ - lay out pages, render, or convert to PDF or images;
505
+ - refresh fields or rebuild a table of contents;
506
+ - run mail merge over `MERGEFIELD` templates or repeat template table rows per record;
507
+ - merge several documents into one;
508
+ - open legacy binary `.doc` files (refused with `document_format_unsupported`).
509
+
510
+ Requesting one of these from this package, for example `SaveOptions.create("pdf")`
511
+ or `DocumentBuilder.append_image`, raises `ModuleNotFoundError` with the message
512
+ `commercial_feature_unavailable`. Reading, editing, and saving `.docx` never need
513
+ them.
514
+
515
+ WolfDocx Commercial, an organization-scoped subscription installed from an
516
+ authenticated package index, and Wolf Runtime, licensed under a written Order, cover
517
+ the tasks in this table. Guides and access are on [wolfdocx.com](https://wolfdocx.com/):
518
+
519
+ | Task | Guide | Edition |
520
+ | --- | --- | --- |
521
+ | Fill a Word template table with rows | [fill-word-template-python](https://wolfdocx.com/fill-word-template-python) | Commercial |
522
+ | Mail merge with `MERGEFIELD` templates | [mail-merge-docx-python](https://wolfdocx.com/mail-merge-docx-python) | Commercial |
523
+ | Merge `.docx` files and keep numbering and styles | [merge-docx-python](https://wolfdocx.com/merge-docx-python) | Commercial |
524
+ | Update a table of contents without Word | [update-toc-docx-python](https://wolfdocx.com/update-toc-docx-python) | Commercial |
525
+ | Convert `.docx` to PDF without Word or LibreOffice | [convert-docx-to-pdf-python](https://wolfdocx.com/convert-docx-to-pdf-python) | [Wolf Runtime](https://wolfsdk.com/runtime) |
526
+ | WolfDocx Commercial Python API and CLI reference | [api-reference](https://wolfdocx.com/api-reference) | Commercial |
527
+
528
+ Commercial source and releases are maintained separately and are not part of this
529
+ repository.
530
+
531
+ ## Compatibility
532
+
533
+ | | |
534
+ | --- | --- |
535
+ | Python | 3.11 or newer (`requires-python = ">=3.11"`). CI runs 3.11, 3.12, and 3.13 on Ubuntu. |
536
+ | Platforms | Pure-Python wheel (`py3-none-any`). No compiled extensions. |
537
+ | Dependencies | None at runtime. `lxml` only for `Node.select_nodes`. |
538
+ | Input | `.docx` packages in Transitional or Strict Open XML. Legacy binary `.doc` is refused. |
539
+ | Output | A new file or an empty seekable stream. Existing files are never replaced. |
540
+ | Office apps | Not required. WolfDocx does not call Word or LibreOffice. |
541
+
542
+ ## Documentation and support
543
+
544
+ - Guides live at [wolfdocx.com/docs](https://wolfdocx.com/docs): getting started,
545
+ [reading content](https://wolfdocx.com/docs/reading-content),
546
+ [editing text and tables](https://wolfdocx.com/docs/editing-text-and-tables), and
547
+ [reports and refusals](https://wolfdocx.com/docs/reports-and-cli).
548
+ - API documentation lives in the docstrings of `src/wolfdocx`; start with
549
+ [`document.py`](https://github.com/wolfiesch/wolfdocx-oss/blob/main/src/wolfdocx/document.py),
550
+ [`session_ops/`](https://github.com/wolfiesch/wolfdocx-oss/tree/main/src/wolfdocx/session_ops),
551
+ and [`model.py`](https://github.com/wolfiesch/wolfdocx-oss/blob/main/src/wolfdocx/model.py).
552
+ - The [tests](https://github.com/wolfiesch/wolfdocx-oss/tree/main/tests) show each
553
+ operation on small fixtures, including the refusal codes.
554
+ - Bugs and questions: [GitHub issues](https://github.com/wolfiesch/wolfdocx-oss/issues).
555
+ Include the wolfdocx and Python versions, and a minimal `.docx` when you can share
556
+ one.
557
+ - Security reports: privately, as described in
558
+ [SECURITY.md](https://github.com/wolfiesch/wolfdocx-oss/blob/main/SECURITY.md).
559
+ - Commercial evaluation, pricing, and support: [wolfdocx.com](https://wolfdocx.com/).
560
+
561
+ ## Status and versioning
562
+
563
+ WolfDocx 0.1.0, released 2026-10-29, was the first public release. 0.1.1 updated the
564
+ documentation and package metadata. 0.1.2 adds `wolfdocx.builder` and
565
+ `wolfdocx.comments` and is the first release regenerated from one source commit. The PyPI
566
+ classifier is `Development Status :: 4 - Beta`. The project follows
567
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html), under which a 0.x minor
568
+ release may change the public API; pin a version in production. Changes are recorded
569
+ in the [changelog](https://github.com/wolfiesch/wolfdocx-oss/blob/main/CHANGELOG.md).
570
+ The `src/wolfdocx` package is regenerated from the author's source repository at a
571
+ single commit, and every module is copied from that commit unchanged;
572
+ [PROVENANCE.md](https://github.com/wolfiesch/wolfdocx-oss/blob/main/PROVENANCE.md)
573
+ names the commit and lists the SHA-256 of each module.
574
+
575
+ ## Security
576
+
577
+ Report vulnerabilities privately through
578
+ [GitHub Security Advisories](https://github.com/wolfiesch/wolfdocx-oss/security/advisories/new),
579
+ not in a public issue. The 0.1.x line receives security fixes. See
580
+ [SECURITY.md](https://github.com/wolfiesch/wolfdocx-oss/blob/main/SECURITY.md).
581
+
582
+ When opening a package, WolfDocx enforces limits on archive size, entry count, entry
583
+ size, total uncompressed size, compression ratio, XML part size, element count, and
584
+ nesting depth, and refuses XML that declares a DTD or entities. The defaults are in
585
+ `PackageLimits`; pass `Document(path, limits=PackageLimits(...))` to change them.
586
+ WolfDocx makes no network requests and starts no processes.
587
+
588
+ Some operations keep an inspection cache, a SQLite database under
589
+ `WOLFDOCX_CACHE_DIR` or the platform user cache directory. Its stored values can
590
+ include facts derived from document parts, including part text. Set
591
+ `WOLFDOCX_INSPECTION_CACHE=off` to disable it.
592
+
593
+ ## Related libraries
594
+
595
+ The same MIT-licensed family covers the other Office formats:
596
+
597
+ - [WolfXL](https://pypi.org/project/wolfxl/): read, write, and edit Excel
598
+ `.xlsx` and `.xlsm` workbooks, an openpyxl alternative (`pip install wolfxl`).
599
+ - [WolfPPT](https://github.com/wolfiesch/wolfppt-oss): edit PowerPoint `.pptx`
600
+ decks, a python-pptx alternative (`pip install wolfppt`).
601
+
602
+ ## Contributing
603
+
604
+ ```bash
605
+ python -m pip install -e ".[dev]"
606
+ ruff check .
607
+ python -m pytest
608
+ ```
609
+
610
+ Open an [issue](https://github.com/wolfiesch/wolfdocx-oss/issues) before a large
611
+ change. CI runs the same lint and test commands on every push and pull request.
612
+ Changes to `src/wolfdocx` are ported to the source repository and arrive in the
613
+ next regenerated release.
614
+
615
+ ## License
616
+
617
+ MIT. See [LICENSE](https://github.com/wolfiesch/wolfdocx-oss/blob/main/LICENSE).