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
@@ -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)