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
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
"""Session run edits using the stateless planner only when an edit is requested."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import TYPE_CHECKING
|
|
6
|
+
|
|
7
|
+
from ..package import PackageGraph
|
|
8
|
+
from ._bridge import EditHost, SessionEditReport
|
|
9
|
+
|
|
10
|
+
if TYPE_CHECKING:
|
|
11
|
+
from .runs import Loader, RunPlan
|
|
12
|
+
|
|
13
|
+
_DOCUMENT = "word/document.xml"
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class RunEdits(EditHost):
|
|
17
|
+
def insert_run(
|
|
18
|
+
self,
|
|
19
|
+
paragraph: int,
|
|
20
|
+
text: str,
|
|
21
|
+
*,
|
|
22
|
+
run: int | None = None,
|
|
23
|
+
position: str = "after",
|
|
24
|
+
part: str = _DOCUMENT,
|
|
25
|
+
) -> SessionEditReport:
|
|
26
|
+
"""Insert a run of ``text`` before or after run ``run`` of ``paragraph``;
|
|
27
|
+
without ``run``, append it after the paragraph's last run."""
|
|
28
|
+
return self._run_edit(paragraph, "insert", run, position, text, part, None)
|
|
29
|
+
|
|
30
|
+
def delete_run(self, paragraph: int, run: int, *, part: str = _DOCUMENT) -> SessionEditReport:
|
|
31
|
+
"""Delete run ``run`` of ``paragraph``."""
|
|
32
|
+
return self._run_edit(paragraph, "delete", run, "after", None, part, None)
|
|
33
|
+
|
|
34
|
+
def _run_edit(
|
|
35
|
+
self,
|
|
36
|
+
paragraph: int,
|
|
37
|
+
action: str,
|
|
38
|
+
run: int | None,
|
|
39
|
+
position: str,
|
|
40
|
+
text: str | None,
|
|
41
|
+
part: str,
|
|
42
|
+
fingerprint: str | None,
|
|
43
|
+
) -> SessionEditReport:
|
|
44
|
+
from .runs import _check_run_fields, _plan_run_edit, _target
|
|
45
|
+
|
|
46
|
+
_check_run_fields(paragraph, action, run, position, text, part)
|
|
47
|
+
|
|
48
|
+
def plan(graph: PackageGraph, load: Loader) -> RunPlan:
|
|
49
|
+
return _plan_run_edit(
|
|
50
|
+
graph,
|
|
51
|
+
load,
|
|
52
|
+
paragraph=paragraph,
|
|
53
|
+
action=action,
|
|
54
|
+
run=run,
|
|
55
|
+
position=position,
|
|
56
|
+
text=text,
|
|
57
|
+
part=part,
|
|
58
|
+
fingerprint=fingerprint,
|
|
59
|
+
)
|
|
60
|
+
|
|
61
|
+
return self._edit_part(
|
|
62
|
+
"run",
|
|
63
|
+
part,
|
|
64
|
+
plan,
|
|
65
|
+
failure_code="run_staged_verification_failed",
|
|
66
|
+
detail={
|
|
67
|
+
"target": _target(part, paragraph, run, action, position),
|
|
68
|
+
"action": action,
|
|
69
|
+
},
|
|
70
|
+
)
|
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
"""Source-bound insertion and deletion of text runs, in a session or file to file.
|
|
2
|
+
|
|
3
|
+
A run is addressed as a 1-based direct ``w:r`` child of a paragraph; the paragraph
|
|
4
|
+
is 1-based over every ``w:p`` of a body, header, or footer part in document order,
|
|
5
|
+
as :class:`~wolfdocx.ParagraphRequest` addresses it, and is bound by the fingerprint
|
|
6
|
+
:func:`~wolfdocx.paragraph_authoring.paragraph_authoring_structure_fingerprint`
|
|
7
|
+
returns. An inserted run takes the anchor run's ``w:rPr`` (without its tracked
|
|
8
|
+
property change), so it reads as the text next to it; ``\\t`` and ``\\n`` become
|
|
9
|
+
``w:tab`` and ``w:br``. Only runs of plain text and simple controls are deleted;
|
|
10
|
+
a run holding a field, note or comment reference, drawing, or object is refused.
|
|
11
|
+
|
|
12
|
+
:func:`author_run` publishes through :meth:`~wolfdocx.Document.save`, and the session
|
|
13
|
+
methods plan with the same :func:`_plan_run_edit`, so both rewrite the paragraph
|
|
14
|
+
identically. Only the target paragraph's bytes change within its part.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
import copy
|
|
20
|
+
import re
|
|
21
|
+
from collections.abc import Callable
|
|
22
|
+
from dataclasses import dataclass
|
|
23
|
+
from pathlib import Path
|
|
24
|
+
from typing import Any
|
|
25
|
+
from xml.etree import ElementTree as ET
|
|
26
|
+
from xml.parsers import expat
|
|
27
|
+
|
|
28
|
+
from ..inspect import Q
|
|
29
|
+
from ..package import PackageError, PackageGraph
|
|
30
|
+
|
|
31
|
+
__all__ = ["RunReport", "RunRequest", "author_run"]
|
|
32
|
+
|
|
33
|
+
_PUBLISHED = "published"
|
|
34
|
+
_DOCUMENT = "word/document.xml"
|
|
35
|
+
_REFUSED = "refused"
|
|
36
|
+
_ACTIONS = ("insert", "delete")
|
|
37
|
+
_POSITIONS = ("before", "after")
|
|
38
|
+
# Run content a deletion may remove without orphaning a field, reference, or part.
|
|
39
|
+
_DELETABLE_RUN_CHILDREN = frozenset(
|
|
40
|
+
{
|
|
41
|
+
"rPr",
|
|
42
|
+
"t",
|
|
43
|
+
"tab",
|
|
44
|
+
"br",
|
|
45
|
+
"cr",
|
|
46
|
+
"noBreakHyphen",
|
|
47
|
+
"softHyphen",
|
|
48
|
+
"lastRenderedPageBreak",
|
|
49
|
+
}
|
|
50
|
+
)
|
|
51
|
+
_CONTROL_SPLIT = re.compile(r"(\t|\n)")
|
|
52
|
+
|
|
53
|
+
Loader = Callable[[str], tuple[bytes, ET.Element]]
|
|
54
|
+
RunPlan = tuple[bytes, ET.Element] | str
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@dataclass(frozen=True)
|
|
58
|
+
class RunRequest:
|
|
59
|
+
"""One source-bound request to insert or delete a text run.
|
|
60
|
+
|
|
61
|
+
``run`` names the anchor run for an insertion (omitted: append after the last
|
|
62
|
+
run) and the run to delete for a deletion.
|
|
63
|
+
"""
|
|
64
|
+
|
|
65
|
+
source: Path
|
|
66
|
+
destination: Path
|
|
67
|
+
source_sha256: str
|
|
68
|
+
paragraph: int
|
|
69
|
+
structure_fingerprint_sha256: str
|
|
70
|
+
action: str = "insert"
|
|
71
|
+
run: int | None = None
|
|
72
|
+
position: str = "after"
|
|
73
|
+
text: str | None = None
|
|
74
|
+
part: str = _DOCUMENT
|
|
75
|
+
|
|
76
|
+
def __post_init__(self) -> None:
|
|
77
|
+
from ..paragraph_authoring import _require_sha256
|
|
78
|
+
|
|
79
|
+
for name in ("source", "destination"):
|
|
80
|
+
value = getattr(self, name)
|
|
81
|
+
if not isinstance(value, (str, Path)) or not str(value):
|
|
82
|
+
raise ValueError(f"run_{name}_invalid")
|
|
83
|
+
object.__setattr__(self, name, Path(value))
|
|
84
|
+
_require_sha256(self.source_sha256, "run_source_sha256")
|
|
85
|
+
_require_sha256(self.structure_fingerprint_sha256, "run_structure_fingerprint_sha256")
|
|
86
|
+
_check_run_fields(
|
|
87
|
+
self.paragraph, self.action, self.run, self.position, self.text, self.part
|
|
88
|
+
)
|
|
89
|
+
|
|
90
|
+
def target_dict(self) -> dict[str, Any]:
|
|
91
|
+
return _target(self.part, self.paragraph, self.run, self.action, self.position)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
@dataclass(frozen=True)
|
|
95
|
+
class RunReport:
|
|
96
|
+
"""Content-safe result of one :func:`author_run`."""
|
|
97
|
+
|
|
98
|
+
status: str
|
|
99
|
+
code: str | None
|
|
100
|
+
source_sha256: str
|
|
101
|
+
destination_sha256: str | None
|
|
102
|
+
target: dict[str, Any]
|
|
103
|
+
action: str
|
|
104
|
+
|
|
105
|
+
@property
|
|
106
|
+
def passed(self) -> bool:
|
|
107
|
+
return self.status == _PUBLISHED
|
|
108
|
+
|
|
109
|
+
def to_dict(self) -> dict[str, Any]:
|
|
110
|
+
return {
|
|
111
|
+
"schema_version": 1,
|
|
112
|
+
"operation": "run",
|
|
113
|
+
"passed": self.passed,
|
|
114
|
+
"status": self.status,
|
|
115
|
+
"code": self.code,
|
|
116
|
+
"source_sha256": self.source_sha256,
|
|
117
|
+
"destination_sha256": self.destination_sha256,
|
|
118
|
+
"target": self.target,
|
|
119
|
+
"action": self.action,
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def _check_run_fields(
|
|
124
|
+
paragraph: Any, action: Any, run: Any, position: Any, text: Any, part: Any
|
|
125
|
+
) -> None:
|
|
126
|
+
"""Raise the request's validation error; shared by requests and session calls."""
|
|
127
|
+
from ..authoring import _MAX_TEXT_CHARACTERS
|
|
128
|
+
from ..paragraph_authoring import _is_valid_xml_text
|
|
129
|
+
|
|
130
|
+
if isinstance(paragraph, bool) or not isinstance(paragraph, int) or paragraph < 1:
|
|
131
|
+
raise ValueError("run_paragraph_invalid")
|
|
132
|
+
if action not in _ACTIONS:
|
|
133
|
+
raise ValueError("run_action_invalid")
|
|
134
|
+
if run is not None and (isinstance(run, bool) or not isinstance(run, int) or run < 1):
|
|
135
|
+
raise ValueError("run_index_invalid")
|
|
136
|
+
if position not in _POSITIONS:
|
|
137
|
+
raise ValueError("run_position_invalid")
|
|
138
|
+
if not isinstance(part, str) or not part:
|
|
139
|
+
raise ValueError("run_part_invalid")
|
|
140
|
+
if action == "delete":
|
|
141
|
+
if run is None:
|
|
142
|
+
raise ValueError("run_index_missing")
|
|
143
|
+
if text is not None or position != "after":
|
|
144
|
+
raise ValueError("run_request_fields_invalid")
|
|
145
|
+
return
|
|
146
|
+
if run is None and position != "after":
|
|
147
|
+
raise ValueError("run_position_invalid")
|
|
148
|
+
if not isinstance(text, str):
|
|
149
|
+
raise TypeError("run_text_invalid")
|
|
150
|
+
if not text:
|
|
151
|
+
raise ValueError("run_text_empty")
|
|
152
|
+
if len(text) > _MAX_TEXT_CHARACTERS:
|
|
153
|
+
raise ValueError("run_text_limit_exceeded")
|
|
154
|
+
if not _is_valid_xml_text(text):
|
|
155
|
+
raise ValueError("run_text_invalid")
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def _target(
|
|
159
|
+
part: str, paragraph: int, run: int | None, action: str, position: str
|
|
160
|
+
) -> dict[str, Any]:
|
|
161
|
+
target: dict[str, Any] = {"part": part, "paragraph": paragraph}
|
|
162
|
+
if run is not None:
|
|
163
|
+
target["run"] = run
|
|
164
|
+
if action == "insert":
|
|
165
|
+
target["position"] = position
|
|
166
|
+
return target
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def _new_run(text: str, anchor: ET.Element | None, ns: str) -> ET.Element:
|
|
170
|
+
from ..authoring import _XML_SPACE_ATTRIBUTE
|
|
171
|
+
|
|
172
|
+
run = ET.Element(Q(ns, "r"))
|
|
173
|
+
properties = anchor.find(Q(ns, "rPr")) if anchor is not None else None
|
|
174
|
+
if properties is not None:
|
|
175
|
+
properties = copy.deepcopy(properties)
|
|
176
|
+
for change in properties.findall(Q(ns, "rPrChange")):
|
|
177
|
+
properties.remove(change)
|
|
178
|
+
run.append(properties)
|
|
179
|
+
for piece in _CONTROL_SPLIT.split(text):
|
|
180
|
+
if piece == "\t":
|
|
181
|
+
ET.SubElement(run, Q(ns, "tab"))
|
|
182
|
+
elif piece == "\n":
|
|
183
|
+
ET.SubElement(run, Q(ns, "br"))
|
|
184
|
+
elif piece:
|
|
185
|
+
node = ET.SubElement(run, Q(ns, "t"))
|
|
186
|
+
node.text = piece
|
|
187
|
+
if piece[:1].isspace() or piece[-1:].isspace():
|
|
188
|
+
node.set(_XML_SPACE_ATTRIBUTE, "preserve")
|
|
189
|
+
return run
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def _plan_run_edit(
|
|
193
|
+
graph: PackageGraph,
|
|
194
|
+
load: Loader,
|
|
195
|
+
*,
|
|
196
|
+
paragraph: int,
|
|
197
|
+
action: str,
|
|
198
|
+
run: int | None,
|
|
199
|
+
position: str,
|
|
200
|
+
text: str | None,
|
|
201
|
+
part: str,
|
|
202
|
+
fingerprint: str | None,
|
|
203
|
+
) -> RunPlan:
|
|
204
|
+
"""Rewrite the target paragraph in the tree ``load`` returns and splice it into
|
|
205
|
+
the part's bytes. Returns the new part bytes and the tree they must parse to, or a
|
|
206
|
+
refusal code. ``fingerprint=None`` binds to the current paragraph."""
|
|
207
|
+
from ..authoring import _cell_structure_fingerprint
|
|
208
|
+
from ..paragraph_authoring import (
|
|
209
|
+
_is_admitted_paragraph,
|
|
210
|
+
_paragraph_xml_fragment,
|
|
211
|
+
_paragraph_xml_span,
|
|
212
|
+
_resolve_target_story,
|
|
213
|
+
)
|
|
214
|
+
|
|
215
|
+
root, container, ns, part_bytes, err = _resolve_target_story(graph, part, load)
|
|
216
|
+
if err is not None:
|
|
217
|
+
return "run_" + err.removeprefix("paragraph_")
|
|
218
|
+
assert root is not None and container is not None and ns is not None
|
|
219
|
+
assert part_bytes is not None
|
|
220
|
+
paragraphs = list(root.iter(Q(ns, "p")))
|
|
221
|
+
if paragraph > len(paragraphs):
|
|
222
|
+
return "run_paragraph_missing"
|
|
223
|
+
target = paragraphs[paragraph - 1]
|
|
224
|
+
if fingerprint is not None and _cell_structure_fingerprint(target) != fingerprint:
|
|
225
|
+
return "run_structure_fingerprint_mismatch"
|
|
226
|
+
parents = {child: parent for parent in root.iter() for child in parent}
|
|
227
|
+
if not _is_admitted_paragraph(target, container, parents, ns):
|
|
228
|
+
return "run_context_unsupported"
|
|
229
|
+
runs = [child for child in target if child.tag == Q(ns, "r")]
|
|
230
|
+
if run is not None and run > len(runs):
|
|
231
|
+
return "run_target_missing"
|
|
232
|
+
if action == "delete":
|
|
233
|
+
doomed = runs[run - 1] # type: ignore[operator]
|
|
234
|
+
deletable = {Q(ns, name) for name in _DELETABLE_RUN_CHILDREN}
|
|
235
|
+
if any(child.tag not in deletable for child in doomed):
|
|
236
|
+
return "run_content_unsupported"
|
|
237
|
+
target.remove(doomed)
|
|
238
|
+
else:
|
|
239
|
+
assert text is not None
|
|
240
|
+
anchor = runs[run - 1] if run is not None else (runs[-1] if runs else None)
|
|
241
|
+
new_run = _new_run(text, anchor, ns)
|
|
242
|
+
if anchor is None:
|
|
243
|
+
target.append(new_run)
|
|
244
|
+
else:
|
|
245
|
+
index = list(target).index(anchor)
|
|
246
|
+
target.insert(index + 1 if position == "after" else index, new_run)
|
|
247
|
+
try:
|
|
248
|
+
start, end, _after, encoding = _paragraph_xml_span(part_bytes, ns, paragraph)
|
|
249
|
+
fragment = _paragraph_xml_fragment(target, encoding)
|
|
250
|
+
except (expat.ExpatError, ValueError, LookupError):
|
|
251
|
+
return "run_staged_verification_failed"
|
|
252
|
+
return part_bytes[:start] + fragment + part_bytes[end:], root
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
_SAVE_CODES = {
|
|
256
|
+
"document_destination_exists": "run_destination_occupied",
|
|
257
|
+
"document_publication_unavailable": "run_publication_unavailable",
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
def author_run(request: RunRequest) -> RunReport:
|
|
262
|
+
"""Insert or delete one run of ``request.source`` and publish ``request.destination``.
|
|
263
|
+
|
|
264
|
+
The source must still hash to ``request.source_sha256`` and the paragraph must
|
|
265
|
+
still match its structure fingerprint; an existing destination is never replaced.
|
|
266
|
+
"""
|
|
267
|
+
from ..document import Document
|
|
268
|
+
|
|
269
|
+
def refusal(code: str) -> RunReport:
|
|
270
|
+
return RunReport(
|
|
271
|
+
_REFUSED,
|
|
272
|
+
code,
|
|
273
|
+
request.source_sha256,
|
|
274
|
+
None,
|
|
275
|
+
request.target_dict(),
|
|
276
|
+
request.action,
|
|
277
|
+
)
|
|
278
|
+
|
|
279
|
+
if not isinstance(request, RunRequest):
|
|
280
|
+
raise TypeError("run_request_invalid")
|
|
281
|
+
if not request.source.is_file():
|
|
282
|
+
return refusal("run_source_missing")
|
|
283
|
+
if request.destination.exists() or request.destination.is_symlink():
|
|
284
|
+
return refusal("run_destination_occupied")
|
|
285
|
+
try:
|
|
286
|
+
document = Document(request.source)
|
|
287
|
+
except (PackageError, OSError):
|
|
288
|
+
return refusal("run_package_invalid")
|
|
289
|
+
with document:
|
|
290
|
+
if document.source_sha256 != request.source_sha256:
|
|
291
|
+
return refusal("run_source_hash_mismatch")
|
|
292
|
+
edited = document._run_edit(
|
|
293
|
+
request.paragraph,
|
|
294
|
+
request.action,
|
|
295
|
+
request.run,
|
|
296
|
+
request.position,
|
|
297
|
+
request.text,
|
|
298
|
+
request.part,
|
|
299
|
+
request.structure_fingerprint_sha256,
|
|
300
|
+
)
|
|
301
|
+
if not edited.passed:
|
|
302
|
+
return refusal(edited.code or "run_staged_verification_failed")
|
|
303
|
+
saved = document.save(request.destination)
|
|
304
|
+
if not saved.passed:
|
|
305
|
+
return refusal(_SAVE_CODES.get(saved.code or "", "run_staged_verification_failed"))
|
|
306
|
+
return RunReport(
|
|
307
|
+
_PUBLISHED,
|
|
308
|
+
None,
|
|
309
|
+
request.source_sha256,
|
|
310
|
+
saved.destination_sha256,
|
|
311
|
+
request.target_dict(),
|
|
312
|
+
request.action,
|
|
313
|
+
)
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
"""Session sections, page setup, and headers and footers through their operation modules."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Mapping, Sequence
|
|
6
|
+
from typing import TYPE_CHECKING, Any
|
|
7
|
+
|
|
8
|
+
from ._bridge import EditHost, SessionEditReport, Staged, bound_fingerprint
|
|
9
|
+
|
|
10
|
+
if TYPE_CHECKING:
|
|
11
|
+
from ..page_setup import PageSetupRequest
|
|
12
|
+
from ..regions import RegionParagraph, RegionRequest
|
|
13
|
+
from ..section_break import SectionBreakRequest
|
|
14
|
+
|
|
15
|
+
_DOCUMENT = "word/document.xml"
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class SectionEdits(EditHost):
|
|
19
|
+
def insert_section_break(
|
|
20
|
+
self, after: int, *, break_type: str = "nextPage", part: str = _DOCUMENT
|
|
21
|
+
) -> SessionEditReport:
|
|
22
|
+
"""End a section after body item ``after`` (a 1-based direct ``w:body`` child)."""
|
|
23
|
+
return self._section_break(after, part, action="insert", break_type=break_type)
|
|
24
|
+
|
|
25
|
+
def delete_section_break(self, paragraph: int, *, part: str = _DOCUMENT) -> SessionEditReport:
|
|
26
|
+
"""Remove the section break carried by body item ``paragraph``."""
|
|
27
|
+
return self._section_break(paragraph, part, action="delete")
|
|
28
|
+
|
|
29
|
+
def set_page_setup(
|
|
30
|
+
self, section: int = 1, *, part: str = _DOCUMENT, **settings: Any
|
|
31
|
+
) -> SessionEditReport:
|
|
32
|
+
"""Change the page setup of ``section``; ``settings`` are the
|
|
33
|
+
:class:`~wolfdocx.page_setup.PageSetupRequest` fields (``page_size``,
|
|
34
|
+
``orientation``, ``margins``, ``columns``, and the rest)."""
|
|
35
|
+
from ..page_setup import (
|
|
36
|
+
PageSetupRequest,
|
|
37
|
+
author_page_setup,
|
|
38
|
+
page_setup_structure_fingerprint,
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
def build(staged: Staged) -> PageSetupRequest:
|
|
42
|
+
return PageSetupRequest(
|
|
43
|
+
source=staged.source,
|
|
44
|
+
destination=staged.destination,
|
|
45
|
+
source_sha256=staged.source_sha256,
|
|
46
|
+
structure_fingerprint_sha256=bound_fingerprint(
|
|
47
|
+
page_setup_structure_fingerprint(staged.source, section=section, part=part)
|
|
48
|
+
),
|
|
49
|
+
section=section,
|
|
50
|
+
part=part,
|
|
51
|
+
**settings,
|
|
52
|
+
)
|
|
53
|
+
|
|
54
|
+
return self._apply_operation("page-setup", build, author_page_setup)
|
|
55
|
+
|
|
56
|
+
def edit_header_footer(
|
|
57
|
+
self,
|
|
58
|
+
kind: str = "header",
|
|
59
|
+
action: str = "create",
|
|
60
|
+
*,
|
|
61
|
+
section: int = 1,
|
|
62
|
+
variant: str = "default",
|
|
63
|
+
paragraphs: Sequence[RegionParagraph | Mapping[str, Any]] = (),
|
|
64
|
+
link_to_previous: bool | None = None,
|
|
65
|
+
) -> SessionEditReport:
|
|
66
|
+
"""Create, replace, remove, link, or unlink one section's header or footer.
|
|
67
|
+
|
|
68
|
+
``kind`` is ``"header"`` or ``"footer"``; ``variant`` is ``"default"``,
|
|
69
|
+
``"first"``, or ``"even"``; ``paragraphs`` follow
|
|
70
|
+
:class:`~wolfdocx.regions.RegionParagraph`.
|
|
71
|
+
"""
|
|
72
|
+
from ..regions import RegionRequest, author_region
|
|
73
|
+
|
|
74
|
+
def build(staged: Staged) -> RegionRequest:
|
|
75
|
+
return RegionRequest(
|
|
76
|
+
source=staged.source,
|
|
77
|
+
source_sha256=staged.source_sha256,
|
|
78
|
+
destination=staged.destination,
|
|
79
|
+
section=section,
|
|
80
|
+
kind=kind,
|
|
81
|
+
variant=variant,
|
|
82
|
+
paragraphs=paragraphs,
|
|
83
|
+
action=action,
|
|
84
|
+
link_to_previous=link_to_previous,
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
return self._apply_operation("header-footer", build, author_region)
|
|
88
|
+
|
|
89
|
+
def _section_break(self, item: int, part: str, **fields: Any) -> SessionEditReport:
|
|
90
|
+
from ..section_break import (
|
|
91
|
+
SectionBreakRequest,
|
|
92
|
+
author_section_break,
|
|
93
|
+
section_break_anchor_fingerprint,
|
|
94
|
+
)
|
|
95
|
+
|
|
96
|
+
def build(staged: Staged) -> SectionBreakRequest:
|
|
97
|
+
return SectionBreakRequest(
|
|
98
|
+
source=staged.source,
|
|
99
|
+
destination=staged.destination,
|
|
100
|
+
source_sha256=staged.source_sha256,
|
|
101
|
+
insert_after=item,
|
|
102
|
+
anchor_fingerprint_sha256=bound_fingerprint(
|
|
103
|
+
section_break_anchor_fingerprint(staged.source, insert_after=item, part=part)
|
|
104
|
+
),
|
|
105
|
+
part=part,
|
|
106
|
+
**fields,
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
return self._apply_operation("section-break", build, author_section_break)
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
"""Session text and paragraph styling through :func:`~wolfdocx.formatting.author_format`."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import TYPE_CHECKING, Any
|
|
6
|
+
|
|
7
|
+
from ._bridge import EditHost, SessionEditReport, Staged, bound_fingerprint
|
|
8
|
+
|
|
9
|
+
if TYPE_CHECKING:
|
|
10
|
+
from ..formatting import FormatRequest
|
|
11
|
+
|
|
12
|
+
_DOCUMENT = "word/document.xml"
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _format_target(staged: Staged, paragraph: int, part: str) -> dict[str, Any]:
|
|
16
|
+
from ..formatting import discover_format_targets
|
|
17
|
+
|
|
18
|
+
targets: list[dict[str, Any]] = discover_format_targets(staged.source, part=part).get(
|
|
19
|
+
"targets", []
|
|
20
|
+
)
|
|
21
|
+
return next((target for target in targets if target["paragraph"] == paragraph), {})
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class StylingEdits(EditHost):
|
|
25
|
+
def format_text(
|
|
26
|
+
self,
|
|
27
|
+
paragraph: int,
|
|
28
|
+
start: int,
|
|
29
|
+
end: int,
|
|
30
|
+
*,
|
|
31
|
+
expected_old_text: str | None = None,
|
|
32
|
+
part: str = _DOCUMENT,
|
|
33
|
+
**formatting: Any,
|
|
34
|
+
) -> SessionEditReport:
|
|
35
|
+
"""Apply run formatting to visible characters ``[start, end)`` of ``paragraph``.
|
|
36
|
+
|
|
37
|
+
``formatting`` takes the :class:`~wolfdocx.formatting.RunFormatEdit` fields
|
|
38
|
+
(``bold``, ``italic``, ``underline``, ``color``, ``font_size``, ``style``, and
|
|
39
|
+
the rest). ``expected_old_text`` is an optional guard; when omitted it is the
|
|
40
|
+
session's current text of that range.
|
|
41
|
+
"""
|
|
42
|
+
from ..formatting import FormatRequest, RunFormatEdit, author_format
|
|
43
|
+
|
|
44
|
+
def build(staged: Staged) -> FormatRequest:
|
|
45
|
+
target = _format_target(staged, paragraph, part)
|
|
46
|
+
text = target.get("text", "")
|
|
47
|
+
return FormatRequest(
|
|
48
|
+
source=staged.source,
|
|
49
|
+
source_sha256=staged.source_sha256,
|
|
50
|
+
destination=staged.destination,
|
|
51
|
+
run_edits=(
|
|
52
|
+
RunFormatEdit(
|
|
53
|
+
paragraph=paragraph,
|
|
54
|
+
start=start,
|
|
55
|
+
end=end,
|
|
56
|
+
expected_old_text=(
|
|
57
|
+
text[start:end] if expected_old_text is None else expected_old_text
|
|
58
|
+
),
|
|
59
|
+
structure_fingerprint_sha256=bound_fingerprint(
|
|
60
|
+
target.get("structure_fingerprint_sha256")
|
|
61
|
+
),
|
|
62
|
+
part=part,
|
|
63
|
+
**formatting,
|
|
64
|
+
),
|
|
65
|
+
),
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
return self._apply_operation("format", build, author_format)
|
|
69
|
+
|
|
70
|
+
def format_paragraph(
|
|
71
|
+
self, paragraph: int, *, part: str = _DOCUMENT, **formatting: Any
|
|
72
|
+
) -> SessionEditReport:
|
|
73
|
+
"""Apply paragraph formatting to ``paragraph``.
|
|
74
|
+
|
|
75
|
+
``formatting`` takes the :class:`~wolfdocx.formatting.ParagraphFormatEdit`
|
|
76
|
+
fields (``style``, ``alignment``, ``spacing``, ``indent``, ``keep_next``, and
|
|
77
|
+
the rest).
|
|
78
|
+
"""
|
|
79
|
+
from ..formatting import FormatRequest, ParagraphFormatEdit, author_format
|
|
80
|
+
|
|
81
|
+
def build(staged: Staged) -> FormatRequest:
|
|
82
|
+
target = _format_target(staged, paragraph, part)
|
|
83
|
+
return FormatRequest(
|
|
84
|
+
source=staged.source,
|
|
85
|
+
source_sha256=staged.source_sha256,
|
|
86
|
+
destination=staged.destination,
|
|
87
|
+
paragraph_edits=(
|
|
88
|
+
ParagraphFormatEdit(
|
|
89
|
+
paragraph=paragraph,
|
|
90
|
+
structure_fingerprint_sha256=bound_fingerprint(
|
|
91
|
+
target.get("structure_fingerprint_sha256")
|
|
92
|
+
),
|
|
93
|
+
part=part,
|
|
94
|
+
**formatting,
|
|
95
|
+
),
|
|
96
|
+
),
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
return self._apply_operation("format", build, author_format)
|