doc-control 0.0.1.dev0__py3-none-any.whl

doc_control/ooxml/formatting.py

@@ -0,0 +1,181 @@
+"""Direct paragraph and run properties: set them on a ``w:pPr`` / ``w:rPr`` in schema order.
+
+:func:`apply_ppr` and :func:`apply_rpr` take a property dict (the keys of
+:data:`PARAGRAPH_KEYS` and :data:`RUN_KEYS`) and change the element in place. They return
+whether anything changed; setting what is already there changes nothing. Children are
+inserted where CT_PPrBase / CT_RPr put them, so Word accepts the result. Lengths come in
+centimetres and points and are written in twips and half-points.
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from typing import Any
+
+from doc_control.ooxml.splice import W_NS
+
+W = f"{{{W_NS}}}"
+
+PARAGRAPH_KEYS = (
+    "align",
+    "indent_left_cm",
+    "indent_right_cm",
+    "indent_first_line_cm",
+    "spacing_before_pt",
+    "spacing_after_pt",
+    "line_spacing",
+)
+RUN_KEYS = ("bold", "italic", "underline", "small_caps", "font", "size_pt")
+ALIGNMENTS = {"left": "left", "center": "center", "right": "right", "justify": "both"}
+
+_PPR_NAMES = """
+pStyle keepNext keepLines pageBreakBefore framePr widowControl numPr suppressLineNumbers pBdr
+shd tabs suppressAutoHyphens kinsoku wordWrap overflowPunct topLinePunct autoSpaceDE
+autoSpaceDN bidi adjustRightInd snapToGrid spacing ind contextualSpacing mirrorIndents
+suppressOverlap jc textDirection textAlignment textboxTightWrap outlineLvl divId cnfStyle
+rPr sectPr pPrChange
+"""
+_RPR_NAMES = """
+ins del moveFrom moveTo rStyle rFonts b bCs i iCs caps smallCaps strike dstrike outline
+shadow emboss imprint noProof snapToGrid vanish webHidden color spacing w kern position sz
+szCs highlight u effect bdr shd fitText vertAlign rtl cs em lang eastAsianLayout specVanish
+oMath rPrChange
+"""
+_PPR_ORDER = tuple(W + n for n in _PPR_NAMES.split())
+_RPR_ORDER = tuple(W + n for n in _RPR_NAMES.split())
+_THEME_FONTS = tuple(
+    W + n for n in ("asciiTheme", "hAnsiTheme", "cstheme", "eastAsiaTheme", "hint")
+)
+_OFF = frozenset({"0", "false", "off"})
+_TWIPS_PER_CM = 1440 / 2.54
+
+
+def twips(cm: float) -> int:
+    return round(cm * _TWIPS_PER_CM)
+
+
+def _child(parent: ET.Element, tag: str, order: tuple[str, ...]) -> tuple[ET.Element, bool]:
+    """The child ``tag`` of ``parent``, created in schema position if missing."""
+    found = parent.find(tag)
+    if found is not None:
+        return found, False
+    rank = order.index(tag)
+    at = len(parent)
+    for i, existing in enumerate(parent):
+        if (
+            isinstance(existing.tag, str)
+            and existing.tag in order
+            and order.index(existing.tag) > rank
+        ):
+            at = i
+            break
+    elem = ET.Element(tag)
+    parent.insert(at, elem)
+    return elem, True
+
+
+def _set_attrs(elem: ET.Element, attrs: dict[str, str], drop: tuple[str, ...] = ()) -> bool:
+    changed = False
+    for name in drop:
+        if name in elem.attrib:
+            del elem.attrib[name]
+            changed = True
+    for name, value in attrs.items():
+        if elem.get(name) != value:
+            elem.set(name, value)
+            changed = True
+    return changed
+
+
+def _set_toggle(rpr: ET.Element, name: str, on: bool) -> bool:
+    tag = W + name
+    existing = rpr.find(tag)
+    if existing is not None:
+        current = (existing.get(W + "val") or "1").lower() not in _OFF
+        if current == on:
+            return False
+    elem, _ = _child(rpr, tag, _RPR_ORDER)
+    if on:
+        elem.attrib.pop(W + "val", None)
+    else:
+        elem.set(W + "val", "0")
+    return True
+
+
+def _set_val(parent: ET.Element, name: str, value: str, order: tuple[str, ...]) -> bool:
+    elem, created = _child(parent, W + name, order)
+    return _set_attrs(elem, {W + "val": value}) or created
+
+
+def apply_rpr(rpr: ET.Element, props: dict[str, Any]) -> bool:
+    """Set run properties (``RUN_KEYS`` plus ``style``, a character style id)."""
+    changed = False
+    if "style" in props:
+        changed |= _set_val(rpr, "rStyle", props["style"], _RPR_ORDER)
+    if "bold" in props:
+        changed |= _set_toggle(rpr, "b", props["bold"])
+    if "italic" in props:
+        changed |= _set_toggle(rpr, "i", props["italic"])
+    if "small_caps" in props:
+        changed |= _set_toggle(rpr, "smallCaps", props["small_caps"])
+    if "underline" in props:
+        changed |= _set_val(rpr, "u", "single" if props["underline"] else "none", _RPR_ORDER)
+    if "font" in props:
+        fonts, created = _child(rpr, W + "rFonts", _RPR_ORDER)
+        name = props["font"]
+        changed |= (
+            _set_attrs(
+                fonts,
+                {W + k: name for k in ("ascii", "hAnsi", "cs", "eastAsia")},
+                drop=_THEME_FONTS,
+            )
+            or created
+        )
+    if "size_pt" in props:
+        half = str(round(props["size_pt"] * 2))
+        changed |= _set_val(rpr, "sz", half, _RPR_ORDER)
+        changed |= _set_val(rpr, "szCs", half, _RPR_ORDER)
+    return changed
+
+
+def apply_ppr(ppr: ET.Element, props: dict[str, Any]) -> bool:
+    """Set paragraph properties (``PARAGRAPH_KEYS`` plus ``style``, a paragraph style id)."""
+    changed = False
+    if "style" in props:
+        changed |= _set_val(ppr, "pStyle", props["style"], _PPR_ORDER)
+    if "align" in props:
+        changed |= _set_val(ppr, "jc", ALIGNMENTS[props["align"]], _PPR_ORDER)
+    ind: dict[str, str] = {}
+    ind_drop: tuple[str, ...] = ()
+    if "indent_left_cm" in props:
+        ind[W + "left"] = str(twips(props["indent_left_cm"]))
+        ind_drop += (W + "start", W + "leftChars")
+    if "indent_right_cm" in props:
+        ind[W + "right"] = str(twips(props["indent_right_cm"]))
+        ind_drop += (W + "end", W + "rightChars")
+    if "indent_first_line_cm" in props:
+        value = twips(props["indent_first_line_cm"])
+        if value >= 0:
+            ind[W + "firstLine"] = str(value)
+            ind_drop += (W + "hanging", W + "hangingChars", W + "firstLineChars")
+        else:
+            ind[W + "hanging"] = str(-value)
+            ind_drop += (W + "firstLine", W + "firstLineChars", W + "hangingChars")
+    if ind:
+        elem, created = _child(ppr, W + "ind", _PPR_ORDER)
+        changed |= _set_attrs(elem, ind, drop=ind_drop) or created
+    spacing: dict[str, str] = {}
+    spacing_drop: tuple[str, ...] = ()
+    if "spacing_before_pt" in props:
+        spacing[W + "before"] = str(round(props["spacing_before_pt"] * 20))
+        spacing_drop += (W + "beforeLines", W + "beforeAutospacing")
+    if "spacing_after_pt" in props:
+        spacing[W + "after"] = str(round(props["spacing_after_pt"] * 20))
+        spacing_drop += (W + "afterLines", W + "afterAutospacing")
+    if "line_spacing" in props:
+        spacing[W + "line"] = str(round(props["line_spacing"] * 240))
+        spacing[W + "lineRule"] = "auto"
+    if spacing:
+        elem, created = _child(ppr, W + "spacing", _PPR_ORDER)
+        changed |= _set_attrs(elem, spacing, drop=spacing_drop) or created
+    return changed

doc_control/ooxml/resolve.py

@@ -0,0 +1,269 @@
+"""Accepting and rejecting tracked changes in one paragraph element.
+
+:func:`scan` lists the revisions of a paragraph (as ``revisions.list`` reports
+them) and :func:`resolve_paragraph` applies a decision, ``accept`` or ``reject``,
+to chosen ones. Both work on the element from
+:meth:`doc_control.ooxml.splice.DocumentSpans.parse_paragraph`; the element is
+edited in place and the caller serialises and splices it.
+
+What each revision does
+    ``w:ins``, ``w:moveTo`` (content): accepting unwraps the element and keeps its
+    content, rejecting removes it with everything inside.
+    ``w:del``, ``w:moveFrom``: accepting removes the element with its content,
+    rejecting unwraps it and turns ``w:delText``/``w:delInstrText`` back into
+    ``w:t``/``w:instrText``.
+    ``w:rPrChange``: accepting drops the record, rejecting puts the recorded
+    run properties back. ``w:pPrChange``: the same for paragraph properties
+    (the paragraph's mark properties and section break stay).
+    Paragraph marks (``w:pPr/w:rPr`` holding ``w:ins``, ``w:del``, ``w:moveFrom``
+    or ``w:moveTo``): the marker is dropped; when the decision removes the mark
+    (accepting a deleted or moved-away mark, rejecting an inserted or moved-in
+    one) :func:`resolve_paragraph` reports it, and the caller joins the paragraph
+    with the next one.
+
+Nesting
+    Decisions apply top down: rejecting an insertion removes a deletion nested in
+    it, whatever its own decision; accepting it unwraps it and leaves the nested
+    deletion pending (or resolved by its own decision).
+
+What survives a removal
+    Bookmark, comment-range and permission markers inside removed content are kept
+    where they were, and so is a run holding a comment reference, so removing text
+    never orphans a comment or splits a bookmark.
+
+Not covered: revisions in text boxes (``w:txbxContent``) are left as they are, as
+``revisions.list`` does not report them, and table row and cell revisions live
+outside paragraphs.
+"""
+
+from __future__ import annotations
+
+import copy
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+
+from doc_control.ooxml.revisions import AUTHOR, DEL, DELTEXT, ID, INS, PPR, RPR, R, T, W
+
+MOVE_FROM, MOVE_TO = W + "moveFrom", W + "moveTo"
+RPR_CHANGE, PPR_CHANGE = W + "rPrChange", W + "pPrChange"
+SECT_PR = W + "sectPr"
+_TEXT_BOX = W + "txbxContent"
+_DEL_INSTR, _INSTR = W + "delInstrText", W + "instrText"
+_COMMENT_REFERENCE = W + "commentReference"
+_KEPT_MARKERS = frozenset(
+    W + name
+    for name in (
+        "bookmarkStart",
+        "bookmarkEnd",
+        "commentRangeStart",
+        "commentRangeEnd",
+        "permStart",
+        "permEnd",
+    )
+)
+
+_CONTENT_KIND = {INS: "insert", DEL: "delete", MOVE_FROM: "move_from", MOVE_TO: "move_to"}
+_MARK_KIND = {
+    INS: "mark_insert",
+    DEL: "mark_delete",
+    MOVE_FROM: "mark_move_from",
+    MOVE_TO: "mark_move_to",
+}
+_MARK_REMOVED = frozenset(
+    {
+        ("mark_insert", "reject"),
+        ("mark_move_to", "reject"),
+        ("mark_delete", "accept"),
+        ("mark_move_from", "accept"),
+    }
+)
+_KEEPS_CONTENT_WHEN_ACCEPTED = frozenset({INS, MOVE_TO})
+
+ACCEPT, REJECT = "accept", "reject"
+
+
+@dataclass(eq=False)
+class Revision:
+    """One revision found in a paragraph; ``kind`` is the ``revisions.list`` type."""
+
+    id: str
+    kind: str
+    author: str
+    elem: ET.Element
+
+
+def scan(p: ET.Element) -> list[Revision]:
+    """The revisions of paragraph ``p`` in document order (text boxes excluded)."""
+    out: list[Revision] = []
+    _scan(p, out)
+    return out
+
+
+def _scan(elem: ET.Element, out: list[Revision]) -> None:
+    for child in elem:
+        tag = child.tag
+        if not isinstance(tag, str) or tag == _TEXT_BOX:
+            continue
+        if tag == PPR:
+            for mark in child.iterfind(f"{RPR}/*"):
+                if mark.tag in _MARK_KIND:
+                    out.append(_revision(mark, _MARK_KIND[mark.tag]))
+                elif mark.tag == RPR_CHANGE:
+                    out.append(_revision(mark, "mark_format"))
+            change = child.find(PPR_CHANGE)
+            if change is not None:
+                out.append(_revision(change, "paragraph_format"))
+            continue
+        if tag in _CONTENT_KIND:
+            out.append(_revision(child, _CONTENT_KIND[tag]))
+        elif tag == RPR_CHANGE:
+            out.append(_revision(child, "format"))
+        _scan(child, out)
+
+
+def _revision(elem: ET.Element, kind: str) -> Revision:
+    return Revision(elem.get(ID) or "", kind, elem.get(AUTHOR) or "", elem)
+
+
+def resolve_paragraph(p: ET.Element, actions: dict[int, str]) -> bool:
+    """Apply ``actions`` (``id(revision.elem)`` -> ``"accept"``/``"reject"``) to ``p``.
+
+    Returns True when a decision removes the paragraph's mark: the caller joins ``p``
+    with the paragraph after it (or keeps ``p`` if there is none).
+    """
+    ppr = p.find(PPR)
+    removed = _resolve_ppr(ppr, actions) if ppr is not None else False
+    _walk(p, actions)
+    return removed
+
+
+def _resolve_ppr(ppr: ET.Element, actions: dict[int, str]) -> bool:
+    removed = False
+    rpr = ppr.find(RPR)
+    if rpr is not None:
+        emptied = False
+        for mark in list(rpr):
+            act = actions.get(id(mark))
+            if act is None or mark.tag not in _MARK_KIND:
+                continue
+            rpr.remove(mark)
+            emptied = True
+            if (_MARK_KIND[mark.tag], act) in _MARK_REMOVED:
+                removed = True
+        _resolve_rpr(rpr, actions)
+        if emptied and len(rpr) == 0:
+            ppr.remove(rpr)
+    change = ppr.find(PPR_CHANGE)
+    act = actions.get(id(change)) if change is not None else None
+    if change is not None and act is not None:
+        if act == REJECT:
+            old = change.find(PPR)
+            kept = [c for c in ppr if c.tag in (RPR, SECT_PR)]
+            ppr[:] = ([copy.deepcopy(c) for c in old] if old is not None else []) + kept
+        else:
+            ppr.remove(change)
+    return removed
+
+
+def _resolve_rpr(rpr: ET.Element, actions: dict[int, str]) -> None:
+    change = rpr.find(RPR_CHANGE)
+    act = actions.get(id(change)) if change is not None else None
+    if change is None or act is None:
+        return
+    if act == REJECT:
+        old = change.find(RPR)
+        keep = [c for c in rpr if c.tag in _MARK_KIND]  # revision marks of a paragraph mark
+        rpr[:] = keep + ([copy.deepcopy(c) for c in old] if old is not None else [])
+    else:
+        rpr.remove(change)
+
+
+def _walk(node: ET.Element, actions: dict[int, str]) -> None:
+    i = 0
+    while i < len(node):
+        child = node[i]
+        tag = child.tag
+        if not isinstance(tag, str) or tag in (_TEXT_BOX, PPR):
+            i += 1
+            continue
+        if tag == RPR:
+            _resolve_rpr(child, actions)
+            i += 1
+            continue
+        act = actions.get(id(child)) if tag in _CONTENT_KIND else None
+        if act is None:
+            _walk(child, actions)
+            i += 1
+            continue
+        if (tag in _KEEPS_CONTENT_WHEN_ACCEPTED) == (act == ACCEPT):
+            _walk(child, actions)
+            content = list(child)
+            if tag in (DEL, MOVE_FROM):
+                for c in content:
+                    _undelete(c)
+            node[i : i + 1] = content
+            i += len(content)
+        else:
+            left = _survivors(child)
+            node[i : i + 1] = left
+            i += len(left)
+
+
+def _undelete(elem: ET.Element) -> None:
+    """Turn deleted text back into text, except inside a nested deletion."""
+    if elem.tag == DELTEXT:
+        elem.tag = T
+    elif elem.tag == _DEL_INSTR:
+        elem.tag = _INSTR
+    for c in elem:
+        if c.tag not in (DEL, MOVE_FROM):
+            _undelete(c)
+
+
+def _survivors(elem: ET.Element) -> list[ET.Element]:
+    """What stays where removed content was: markers and comment-reference runs."""
+    out: list[ET.Element] = []
+    for c in elem:
+        tag = c.tag
+        if not isinstance(tag, str):
+            continue
+        if tag in _KEPT_MARKERS:
+            out.append(c)
+        elif tag == R:
+            if any(x.tag == _COMMENT_REFERENCE for x in c):
+                c[:] = [x for x in c if x.tag in (RPR, _COMMENT_REFERENCE)]
+                out.append(c)
+        elif tag.startswith(W) and tag != RPR:
+            out.extend(_survivors(c))
+    return out
+
+
+MOVE_RANGE_TAGS = {
+    "from": (W + "moveFromRangeStart", W + "moveFromRangeEnd"),
+    "to": (W + "moveToRangeStart", W + "moveToRangeEnd"),
+}
+
+
+def drop_move_markers(p: ET.Element, sides: set[str]) -> bool:
+    """Remove the move range markers of ``sides`` (``"from"``, ``"to"``) from ``p``.
+
+    Called once no revision of that side is left in the document, so the markers
+    (matched by their ``w:id``, start and end alike) mark nothing any more. Returns
+    True if anything was removed.
+    """
+    tags = {t for side in sides for t in MOVE_RANGE_TAGS[side]}
+    changed = False
+
+    def walk(node: ET.Element) -> None:
+        nonlocal changed
+        for child in list(node):
+            if not isinstance(child.tag, str) or child.tag == _TEXT_BOX:
+                continue
+            if child.tag in tags:
+                node.remove(child)
+                changed = True
+            else:
+                walk(child)
+
+    walk(p)
+    return changed