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.
- wolfdocx-0.1.2/CHANGELOG.md +60 -0
- wolfdocx-0.1.2/PKG-INFO +617 -0
- wolfdocx-0.1.2/PROVENANCE.md +78 -0
- wolfdocx-0.1.2/README.md +583 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/pyproject.toml +8 -8
- wolfdocx-0.1.2/src/wolfdocx/__init__.py +955 -0
- wolfdocx-0.1.2/src/wolfdocx/_comment_extensions.py +185 -0
- wolfdocx-0.1.2/src/wolfdocx/_defaults.py +57 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/_inspection_cache.py +5 -3
- wolfdocx-0.1.2/src/wolfdocx/_optional.py +53 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/_version.py +1 -1
- wolfdocx-0.1.2/src/wolfdocx/assembly.py +8245 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/authoring.py +4 -8
- wolfdocx-0.1.2/src/wolfdocx/builder.py +3363 -0
- wolfdocx-0.1.2/src/wolfdocx/comments.py +2359 -0
- wolfdocx-0.1.2/src/wolfdocx/contracts.py +561 -0
- wolfdocx-0.1.2/src/wolfdocx/document.py +461 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/errors.py +5 -2
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/find_replace.py +199 -59
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/formatting.py +112 -16
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/inspect.py +202 -17
- wolfdocx-0.1.2/src/wolfdocx/load_options.py +2013 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/model.py +156 -11
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/numbering_authoring.py +42 -121
- wolfdocx-0.1.2/src/wolfdocx/ooxml_order.py +61 -0
- wolfdocx-0.1.2/src/wolfdocx/output.py +1468 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/page_setup.py +179 -119
- wolfdocx-0.1.2/src/wolfdocx/paragraph_format_effective.py +431 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/properties.py +3 -3
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/protection.py +193 -27
- wolfdocx-0.1.2/src/wolfdocx/render_warnings.py +252 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/reporting.py +2 -4
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/review.py +53 -34
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/section_break.py +29 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/__init__.py +2 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/_bridge.py +32 -0
- wolfdocx-0.1.2/src/wolfdocx/session_ops/pictures.py +87 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/rich_objects.py +1883 -47
- wolfdocx-0.1.2/src/wolfdocx/style_resolution.py +1244 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/styles_authoring.py +26 -24
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_cell_properties.py +138 -13
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_column.py +65 -34
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_delete.py +1 -2
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_merge.py +255 -93
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_properties.py +120 -14
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_row_properties.py +102 -16
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_structure.py +3 -6
- wolfdocx-0.1.2/src/wolfdocx/web_extensions.py +850 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/docx_fixtures.py +2 -4
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_section_break.py +1 -1
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_inspect.py +23 -12
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_table_column.py +3 -2
- wolfdocx-0.1.0/CHANGELOG.md +0 -21
- wolfdocx-0.1.0/PKG-INFO +0 -127
- wolfdocx-0.1.0/PROVENANCE.md +0 -8
- wolfdocx-0.1.0/README.md +0 -93
- wolfdocx-0.1.0/src/wolfdocx/__init__.py +0 -25
- wolfdocx-0.1.0/src/wolfdocx/assembly.py +0 -463
- wolfdocx-0.1.0/src/wolfdocx/document.py +0 -215
- wolfdocx-0.1.0/src/wolfdocx/output.py +0 -13
- wolfdocx-0.1.0/src/wolfdocx/render_warnings.py +0 -106
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/.gitignore +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/LICENSE +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/SECURITY.md +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/_cache_root.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/_comment_threads.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/admission.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/canonical.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/content.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/package.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/package_profile.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/paragraph_authoring.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/regions.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/run_text.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/lists.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/paragraphs.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/run_edits.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/runs.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/sections.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/styling.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/session_ops/tables.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/table_insert.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/src/wolfdocx/text_effects.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/__init__.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/conftest.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_cells.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_page_setup.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_regions.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_spans.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_table_cell_properties.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_table_insert.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_table_merge.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_table_properties.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_table_row_properties.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_authoring_table_structure.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_document_session.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_document_session_paragraphs.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_find_replace.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_find_replace_no_match.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_find_replace_portfolio_edits.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_node_visitor.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_package_graph.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_package_open_tolerance.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_package_profile.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_paragraph_authoring.py +0 -0
- {wolfdocx-0.1.0 → wolfdocx-0.1.2}/tests/test_run_text_edit.py +0 -0
- {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
|
wolfdocx-0.1.2/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://pypi.org/project/wolfdocx/)
|
|
47
|
+
[](https://pypi.org/project/wolfdocx/)
|
|
48
|
+
[](https://github.com/wolfiesch/wolfdocx-oss/actions/workflows/ci.yml)
|
|
49
|
+
[](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).
|