wolfdocx 0.1.0__py3-none-any.whl
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/__init__.py +25 -0
- wolfdocx/_cache_root.py +24 -0
- wolfdocx/_comment_threads.py +278 -0
- wolfdocx/_inspection_cache.py +374 -0
- wolfdocx/_version.py +3 -0
- wolfdocx/admission.py +163 -0
- wolfdocx/assembly.py +463 -0
- wolfdocx/authoring.py +2773 -0
- wolfdocx/canonical.py +267 -0
- wolfdocx/content.py +963 -0
- wolfdocx/document.py +215 -0
- wolfdocx/errors.py +169 -0
- wolfdocx/find_replace.py +1210 -0
- wolfdocx/formatting.py +3160 -0
- wolfdocx/inspect.py +3999 -0
- wolfdocx/model.py +1038 -0
- wolfdocx/numbering_authoring.py +1422 -0
- wolfdocx/output.py +13 -0
- wolfdocx/package.py +2313 -0
- wolfdocx/package_profile.py +128 -0
- wolfdocx/page_setup.py +2483 -0
- wolfdocx/paragraph_authoring.py +1842 -0
- wolfdocx/properties.py +2728 -0
- wolfdocx/protection.py +1909 -0
- wolfdocx/regions.py +1993 -0
- wolfdocx/render_warnings.py +106 -0
- wolfdocx/reporting.py +943 -0
- wolfdocx/review.py +2862 -0
- wolfdocx/run_text.py +117 -0
- wolfdocx/section_break.py +1810 -0
- wolfdocx/session_ops/__init__.py +45 -0
- wolfdocx/session_ops/_bridge.py +151 -0
- wolfdocx/session_ops/lists.py +104 -0
- wolfdocx/session_ops/paragraphs.py +39 -0
- wolfdocx/session_ops/rich_objects.py +2598 -0
- wolfdocx/session_ops/run_edits.py +70 -0
- wolfdocx/session_ops/runs.py +313 -0
- wolfdocx/session_ops/sections.py +109 -0
- wolfdocx/session_ops/styling.py +99 -0
- wolfdocx/session_ops/tables.py +247 -0
- wolfdocx/styles_authoring.py +2822 -0
- wolfdocx/table_cell_properties.py +1458 -0
- wolfdocx/table_column.py +1501 -0
- wolfdocx/table_delete.py +942 -0
- wolfdocx/table_insert.py +1114 -0
- wolfdocx/table_merge.py +1863 -0
- wolfdocx/table_properties.py +2429 -0
- wolfdocx/table_row_properties.py +1095 -0
- wolfdocx/table_structure.py +1044 -0
- wolfdocx/text_effects.py +1438 -0
- wolfdocx-0.1.0.dist-info/METADATA +127 -0
- wolfdocx-0.1.0.dist-info/RECORD +54 -0
- wolfdocx-0.1.0.dist-info/WHEEL +4 -0
- wolfdocx-0.1.0.dist-info/licenses/LICENSE +21 -0
wolfdocx/__init__.py
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""Read, write, and edit DOCX packages with the Python standard library."""
|
|
2
|
+
|
|
3
|
+
from .document import Document
|
|
4
|
+
from .model import DocumentVisitor, Node, NodeEditError, NodeType, StoryType, VisitorAction
|
|
5
|
+
from .package import PackageError, PackageGraph, PackageLimits
|
|
6
|
+
from .session_ops import SessionEditReport
|
|
7
|
+
from .session_ops.rich_objects import SessionSaveReport
|
|
8
|
+
|
|
9
|
+
__version__ = "0.1.0"
|
|
10
|
+
|
|
11
|
+
__all__ = [
|
|
12
|
+
"Document",
|
|
13
|
+
"DocumentVisitor",
|
|
14
|
+
"Node",
|
|
15
|
+
"NodeEditError",
|
|
16
|
+
"NodeType",
|
|
17
|
+
"StoryType",
|
|
18
|
+
"VisitorAction",
|
|
19
|
+
"PackageError",
|
|
20
|
+
"PackageGraph",
|
|
21
|
+
"PackageLimits",
|
|
22
|
+
"SessionEditReport",
|
|
23
|
+
"SessionSaveReport",
|
|
24
|
+
"__version__",
|
|
25
|
+
]
|
wolfdocx/_cache_root.py
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""The WolfDocx user cache directory shared by every on-disk cache."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
import sys
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def default_cache_root() -> Path:
|
|
11
|
+
"""Return ``WOLFDOCX_CACHE_DIR`` when set, else the platform user cache directory."""
|
|
12
|
+
configured = os.environ.get("WOLFDOCX_CACHE_DIR")
|
|
13
|
+
if configured:
|
|
14
|
+
return Path(configured).expanduser()
|
|
15
|
+
if sys.platform == "darwin":
|
|
16
|
+
return Path.home() / "Library" / "Caches" / "wolfdocx"
|
|
17
|
+
if os.name == "nt":
|
|
18
|
+
local_app_data = os.environ.get("LOCALAPPDATA")
|
|
19
|
+
if local_app_data:
|
|
20
|
+
return Path(local_app_data) / "wolfdocx" / "Cache"
|
|
21
|
+
xdg_cache = os.environ.get("XDG_CACHE_HOME")
|
|
22
|
+
if xdg_cache:
|
|
23
|
+
return Path(xdg_cache).expanduser() / "wolfdocx"
|
|
24
|
+
return Path.home() / ".cache" / "wolfdocx"
|
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
"""Internal thread and extended metadata helpers for Word comments.
|
|
2
|
+
|
|
3
|
+
Provides collision-safe paragraph/durable ID generation, parent-child thread
|
|
4
|
+
linkage, resolution tracking, and XML manipulation for word/commentsExtended.xml,
|
|
5
|
+
word/commentsIds.xml, and word/people.xml.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import hashlib
|
|
11
|
+
import re
|
|
12
|
+
from collections.abc import Mapping
|
|
13
|
+
from dataclasses import dataclass
|
|
14
|
+
from typing import Any
|
|
15
|
+
from xml.etree import ElementTree as ET
|
|
16
|
+
|
|
17
|
+
from .inspect import Q, parse_xml_with_preserved_qnames
|
|
18
|
+
from .package import PackageError, PackageGraph
|
|
19
|
+
|
|
20
|
+
_DOCUMENT = "word/document.xml"
|
|
21
|
+
|
|
22
|
+
_COMMENTS_EXTENDED_CONTENT_TYPE = (
|
|
23
|
+
"application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml"
|
|
24
|
+
)
|
|
25
|
+
_COMMENTS_EXTENDED_RELATIONSHIP = (
|
|
26
|
+
"http://schemas.microsoft.com/office/2011/relationships/commentsExtended"
|
|
27
|
+
)
|
|
28
|
+
_COMMENTS_EXTENDED_PART = "word/commentsExtended.xml"
|
|
29
|
+
|
|
30
|
+
_COMMENTS_IDS_CONTENT_TYPE = (
|
|
31
|
+
"application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml"
|
|
32
|
+
)
|
|
33
|
+
_COMMENTS_IDS_RELATIONSHIP = "http://schemas.microsoft.com/office/2016/09/relationships/commentsIds"
|
|
34
|
+
_COMMENTS_IDS_PART = "word/commentsIds.xml"
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
_W14 = "http://schemas.microsoft.com/office/word/2010/wordml"
|
|
38
|
+
_W15 = "http://schemas.microsoft.com/office/word/2012/wordml"
|
|
39
|
+
_W16CID = "http://schemas.microsoft.com/office/word/2016/wordml/cid"
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@dataclass(frozen=True)
|
|
43
|
+
class CommentReply:
|
|
44
|
+
"""One reply appended to an existing parent comment thread."""
|
|
45
|
+
|
|
46
|
+
comment_id: int
|
|
47
|
+
comment_sha256: str
|
|
48
|
+
author: str
|
|
49
|
+
initials: str | None
|
|
50
|
+
date: str
|
|
51
|
+
text: str
|
|
52
|
+
|
|
53
|
+
def target_dict(self) -> dict[str, Any]:
|
|
54
|
+
return {"action": "reply", "comment_id": self.comment_id}
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@dataclass(frozen=True)
|
|
58
|
+
class CommentResolve:
|
|
59
|
+
"""One resolution status change on an existing comment thread."""
|
|
60
|
+
|
|
61
|
+
comment_id: int
|
|
62
|
+
comment_sha256: str
|
|
63
|
+
resolved: bool
|
|
64
|
+
|
|
65
|
+
def target_dict(self) -> dict[str, Any]:
|
|
66
|
+
return {"action": "resolve", "comment_id": self.comment_id}
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def collect_existing_para_ids(roots: Mapping[str, ET.Element]) -> set[str]:
|
|
70
|
+
"""Collect all 8-hex paragraph IDs across all parsed parts."""
|
|
71
|
+
para_ids: set[str] = set()
|
|
72
|
+
for root in roots.values():
|
|
73
|
+
for elem in root.iter():
|
|
74
|
+
for key, val in elem.attrib.items():
|
|
75
|
+
if key.endswith(("paraId", "paraIdParent")):
|
|
76
|
+
para_ids.add(val.upper())
|
|
77
|
+
return para_ids
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def generate_collision_safe_para_id(occupied: set[str], seed: str | int) -> str:
|
|
81
|
+
"""Generate an 8-character uppercase hex paragraph ID that avoids collision."""
|
|
82
|
+
h = int(hashlib.sha256(f"para_{seed}".encode()).hexdigest()[:8], 16)
|
|
83
|
+
candidate_int = (h & 0x7FFFFFFF) or 1
|
|
84
|
+
candidate = f"{candidate_int:08X}"
|
|
85
|
+
while candidate in occupied or candidate == "00000000":
|
|
86
|
+
candidate_int = ((candidate_int + 1) & 0x7FFFFFFF) or 1
|
|
87
|
+
candidate = f"{candidate_int:08X}"
|
|
88
|
+
occupied.add(candidate)
|
|
89
|
+
return candidate
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def collect_existing_durable_ids(roots: Mapping[str, ET.Element]) -> set[str]:
|
|
93
|
+
"""Collect all durable IDs across commentsIds.xml."""
|
|
94
|
+
durable_ids: set[str] = set()
|
|
95
|
+
for root in roots.values():
|
|
96
|
+
for elem in root.iter():
|
|
97
|
+
for key, val in elem.attrib.items():
|
|
98
|
+
if key.endswith("durableId"):
|
|
99
|
+
durable_ids.add(val.upper())
|
|
100
|
+
return durable_ids
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def generate_collision_safe_durable_id(occupied: set[str], seed: str | int) -> str:
|
|
104
|
+
"""Generate an 8-hex durable ID in the exclusive range (0, 0x7FFFFFFF)."""
|
|
105
|
+
h = int(hashlib.sha256(f"durable_{seed}".encode()).hexdigest()[:8], 16)
|
|
106
|
+
candidate_int = (h & 0x7FFFFFFF) or 1
|
|
107
|
+
if candidate_int == 0x7FFFFFFF:
|
|
108
|
+
candidate_int = 1
|
|
109
|
+
candidate = f"{candidate_int:08X}"
|
|
110
|
+
while candidate in occupied or candidate == "00000000":
|
|
111
|
+
candidate_int = candidate_int + 1 if candidate_int < 0x7FFFFFFE else 1
|
|
112
|
+
candidate = f"{candidate_int:08X}"
|
|
113
|
+
occupied.add(candidate)
|
|
114
|
+
return candidate
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def resolve_metadata_part(
|
|
118
|
+
graph: PackageGraph,
|
|
119
|
+
rel_type: str,
|
|
120
|
+
content_type: str,
|
|
121
|
+
) -> tuple[str | None, ET.Element | None, str | None]:
|
|
122
|
+
"""Resolve one relationship-reachable modern metadata part from document.xml."""
|
|
123
|
+
matches = [
|
|
124
|
+
r for r in graph.relationships_for(_DOCUMENT) if not r.is_external and r.type == rel_type
|
|
125
|
+
]
|
|
126
|
+
if not matches:
|
|
127
|
+
return None, None, None
|
|
128
|
+
if len(matches) > 1:
|
|
129
|
+
return None, None, "comment_metadata_part_ambiguous"
|
|
130
|
+
target = matches[0].resolved_target()
|
|
131
|
+
pkg_part = graph.part(target)
|
|
132
|
+
if pkg_part is None or pkg_part.content_type != content_type:
|
|
133
|
+
return None, None, "comment_metadata_part_unsupported"
|
|
134
|
+
try:
|
|
135
|
+
data = graph.read_part_bytes(target)
|
|
136
|
+
root = parse_xml_with_preserved_qnames(data)
|
|
137
|
+
except (PackageError, ET.ParseError):
|
|
138
|
+
return None, None, "comment_metadata_part_invalid"
|
|
139
|
+
return target, root, None
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def last_comment_paragraph(comment: ET.Element, namespace: str) -> ET.Element | None:
|
|
143
|
+
"""The paragraph used by both commentEx and commentId identity associations."""
|
|
144
|
+
last = None
|
|
145
|
+
for paragraph in comment.iter(Q(namespace, "p")):
|
|
146
|
+
last = paragraph
|
|
147
|
+
return last
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def comment_identity_code(
|
|
151
|
+
comments_root: ET.Element | None,
|
|
152
|
+
comments_ns: str,
|
|
153
|
+
extended_root: ET.Element | None,
|
|
154
|
+
ids_root: ET.Element | None,
|
|
155
|
+
) -> str | None:
|
|
156
|
+
"""Diagnose identity ambiguity without rewriting or discarding orphan rows.
|
|
157
|
+
|
|
158
|
+
Deleted comments may leave metadata behind. An unbound row is preserved, but
|
|
159
|
+
a row naming a live nonterminal paragraph cannot identify that comment.
|
|
160
|
+
"""
|
|
161
|
+
paragraph_ids: set[str] = set()
|
|
162
|
+
terminal_ids: set[str] = set()
|
|
163
|
+
if comments_root is not None:
|
|
164
|
+
for comment in comments_root.findall(Q(comments_ns, "comment")):
|
|
165
|
+
last = last_comment_paragraph(comment, comments_ns)
|
|
166
|
+
for paragraph in comment.iter(Q(comments_ns, "p")):
|
|
167
|
+
value = paragraph.get(Q(_W14, "paraId"))
|
|
168
|
+
if value is None:
|
|
169
|
+
continue
|
|
170
|
+
if not re.fullmatch(r"[0-9A-Fa-f]{8}", value) or not (
|
|
171
|
+
0 < int(value, 16) < 0x80000000
|
|
172
|
+
):
|
|
173
|
+
return "comment_paragraph_id_invalid"
|
|
174
|
+
normalized = value.upper()
|
|
175
|
+
if normalized in paragraph_ids:
|
|
176
|
+
return "comment_paragraph_id_ambiguous"
|
|
177
|
+
paragraph_ids.add(normalized)
|
|
178
|
+
if paragraph is last:
|
|
179
|
+
terminal_ids.add(normalized)
|
|
180
|
+
|
|
181
|
+
for root, namespace, root_name, row_name in (
|
|
182
|
+
(extended_root, _W15, "commentsEx", "commentEx"),
|
|
183
|
+
(ids_root, _W16CID, "commentsIds", "commentId"),
|
|
184
|
+
):
|
|
185
|
+
if root is None:
|
|
186
|
+
continue
|
|
187
|
+
if root.tag != Q(namespace, root_name):
|
|
188
|
+
return "comment_metadata_part_unsupported"
|
|
189
|
+
associations: set[str] = set()
|
|
190
|
+
durable_ids: set[str] = set()
|
|
191
|
+
for row in root.findall(Q(namespace, row_name)):
|
|
192
|
+
value = row.get(Q(namespace, "paraId"), "")
|
|
193
|
+
if not re.fullmatch(r"[0-9A-Fa-f]{8}", value) or not (0 < int(value, 16) < 0x80000000):
|
|
194
|
+
return "comment_paragraph_id_invalid"
|
|
195
|
+
normalized = value.upper()
|
|
196
|
+
if normalized in associations:
|
|
197
|
+
return "comment_identity_association_ambiguous"
|
|
198
|
+
associations.add(normalized)
|
|
199
|
+
if normalized in paragraph_ids and normalized not in terminal_ids:
|
|
200
|
+
return "comment_identity_association_invalid"
|
|
201
|
+
if namespace == _W16CID:
|
|
202
|
+
durable = row.get(Q(namespace, "durableId"), "")
|
|
203
|
+
if not re.fullmatch(r"[0-9A-Fa-f]{8}", durable) or not (
|
|
204
|
+
0 < int(durable, 16) < 0x7FFFFFFF
|
|
205
|
+
):
|
|
206
|
+
return "comment_durable_id_invalid"
|
|
207
|
+
if durable.upper() in durable_ids:
|
|
208
|
+
return "comment_durable_id_ambiguous"
|
|
209
|
+
durable_ids.add(durable.upper())
|
|
210
|
+
else:
|
|
211
|
+
parent = row.get(Q(namespace, "paraIdParent"))
|
|
212
|
+
if parent is not None:
|
|
213
|
+
if not re.fullmatch(r"[0-9A-Fa-f]{8}", parent) or not (
|
|
214
|
+
0 < int(parent, 16) < 0x80000000
|
|
215
|
+
):
|
|
216
|
+
return "comment_paragraph_id_invalid"
|
|
217
|
+
parent_id = parent.upper()
|
|
218
|
+
if parent_id in paragraph_ids and parent_id not in terminal_ids:
|
|
219
|
+
return "comment_identity_association_invalid"
|
|
220
|
+
return None
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def parse_thread_state(
|
|
224
|
+
comments_root: ET.Element,
|
|
225
|
+
comments_ns: str,
|
|
226
|
+
extended_root: ET.Element | None,
|
|
227
|
+
) -> tuple[dict[int, int | None], dict[int, bool], dict[int, str], dict[str, int]]:
|
|
228
|
+
"""Index parent_comment_id, resolved status, and para_ids for all comments.
|
|
229
|
+
|
|
230
|
+
Returns:
|
|
231
|
+
parents: comment_id -> parent_comment_id (or None)
|
|
232
|
+
resolutions: comment_id -> bool
|
|
233
|
+
comment_to_para: comment_id -> para_id (str)
|
|
234
|
+
para_to_comment: para_id -> comment_id
|
|
235
|
+
"""
|
|
236
|
+
comment_to_para: dict[int, str] = {}
|
|
237
|
+
para_to_comment: dict[str, int] = {}
|
|
238
|
+
|
|
239
|
+
for comment_elem in comments_root.findall(Q(comments_ns, "comment")):
|
|
240
|
+
raw_id = comment_elem.get(Q(comments_ns, "id"))
|
|
241
|
+
if raw_id is None or not raw_id.isdigit():
|
|
242
|
+
continue
|
|
243
|
+
cid = int(raw_id)
|
|
244
|
+
p = last_comment_paragraph(comment_elem, comments_ns)
|
|
245
|
+
if p is not None:
|
|
246
|
+
para_id = p.get(f"{{{_W14}}}paraId")
|
|
247
|
+
if para_id:
|
|
248
|
+
normalized = para_id.upper()
|
|
249
|
+
comment_to_para[cid] = normalized
|
|
250
|
+
para_to_comment[normalized] = cid
|
|
251
|
+
|
|
252
|
+
parents: dict[int, int | None] = {}
|
|
253
|
+
resolutions: dict[int, bool] = {}
|
|
254
|
+
|
|
255
|
+
if extended_root is not None:
|
|
256
|
+
for child in extended_root:
|
|
257
|
+
if child.tag == f"{{{_W15}}}commentEx":
|
|
258
|
+
pid = child.get(f"{{{_W15}}}paraId")
|
|
259
|
+
if pid:
|
|
260
|
+
pid_norm = pid.upper()
|
|
261
|
+
done = child.get(f"{{{_W15}}}done") == "1"
|
|
262
|
+
parent_pid = child.get(f"{{{_W15}}}paraIdParent")
|
|
263
|
+
parent_norm = parent_pid.upper() if parent_pid else None
|
|
264
|
+
cid = para_to_comment.get(pid_norm)
|
|
265
|
+
if cid is not None:
|
|
266
|
+
resolutions[cid] = done
|
|
267
|
+
if parent_norm:
|
|
268
|
+
parents[cid] = para_to_comment.get(parent_norm)
|
|
269
|
+
else:
|
|
270
|
+
parents[cid] = None
|
|
271
|
+
|
|
272
|
+
for cid in comment_to_para:
|
|
273
|
+
if cid not in parents:
|
|
274
|
+
parents[cid] = None
|
|
275
|
+
if cid not in resolutions:
|
|
276
|
+
resolutions[cid] = False
|
|
277
|
+
|
|
278
|
+
return parents, resolutions, comment_to_para, para_to_comment
|