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.
Files changed (54) hide show
  1. wolfdocx/__init__.py +25 -0
  2. wolfdocx/_cache_root.py +24 -0
  3. wolfdocx/_comment_threads.py +278 -0
  4. wolfdocx/_inspection_cache.py +374 -0
  5. wolfdocx/_version.py +3 -0
  6. wolfdocx/admission.py +163 -0
  7. wolfdocx/assembly.py +463 -0
  8. wolfdocx/authoring.py +2773 -0
  9. wolfdocx/canonical.py +267 -0
  10. wolfdocx/content.py +963 -0
  11. wolfdocx/document.py +215 -0
  12. wolfdocx/errors.py +169 -0
  13. wolfdocx/find_replace.py +1210 -0
  14. wolfdocx/formatting.py +3160 -0
  15. wolfdocx/inspect.py +3999 -0
  16. wolfdocx/model.py +1038 -0
  17. wolfdocx/numbering_authoring.py +1422 -0
  18. wolfdocx/output.py +13 -0
  19. wolfdocx/package.py +2313 -0
  20. wolfdocx/package_profile.py +128 -0
  21. wolfdocx/page_setup.py +2483 -0
  22. wolfdocx/paragraph_authoring.py +1842 -0
  23. wolfdocx/properties.py +2728 -0
  24. wolfdocx/protection.py +1909 -0
  25. wolfdocx/regions.py +1993 -0
  26. wolfdocx/render_warnings.py +106 -0
  27. wolfdocx/reporting.py +943 -0
  28. wolfdocx/review.py +2862 -0
  29. wolfdocx/run_text.py +117 -0
  30. wolfdocx/section_break.py +1810 -0
  31. wolfdocx/session_ops/__init__.py +45 -0
  32. wolfdocx/session_ops/_bridge.py +151 -0
  33. wolfdocx/session_ops/lists.py +104 -0
  34. wolfdocx/session_ops/paragraphs.py +39 -0
  35. wolfdocx/session_ops/rich_objects.py +2598 -0
  36. wolfdocx/session_ops/run_edits.py +70 -0
  37. wolfdocx/session_ops/runs.py +313 -0
  38. wolfdocx/session_ops/sections.py +109 -0
  39. wolfdocx/session_ops/styling.py +99 -0
  40. wolfdocx/session_ops/tables.py +247 -0
  41. wolfdocx/styles_authoring.py +2822 -0
  42. wolfdocx/table_cell_properties.py +1458 -0
  43. wolfdocx/table_column.py +1501 -0
  44. wolfdocx/table_delete.py +942 -0
  45. wolfdocx/table_insert.py +1114 -0
  46. wolfdocx/table_merge.py +1863 -0
  47. wolfdocx/table_properties.py +2429 -0
  48. wolfdocx/table_row_properties.py +1095 -0
  49. wolfdocx/table_structure.py +1044 -0
  50. wolfdocx/text_effects.py +1438 -0
  51. wolfdocx-0.1.0.dist-info/METADATA +127 -0
  52. wolfdocx-0.1.0.dist-info/RECORD +54 -0
  53. wolfdocx-0.1.0.dist-info/WHEEL +4 -0
  54. 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
+ ]
@@ -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