Code DOCX Document Library
Library for working with Word documents: comments, tracked changes, and editing
Source Code
#!/usr/bin/env python3
"""
Library for working with Word documents: comments, tracked changes, and editing.
Usage:
from skills.docx.scripts.document import Document
# Initialize
doc = Document('workspace/unpacked')
doc = Document('workspace/unpacked', author="John Doe", initials="JD")
# Find nodes
node = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "1"})
node = doc["word/document.xml"].get_node(tag="w:p", line_number=10)
# Add comments
doc.add_comment(start=node, end=node, text="Comment text")
doc.reply_to_comment(parent_comment_id=0, text="Reply text")
# Suggest tracked changes
doc["word/document.xml"].suggest_deletion(node) # Delete content
doc["word/document.xml"].revert_insertion(ins_node) # Reject insertion
doc["word/document.xml"].revert_deletion(del_node) # Reject deletion
# Save
doc.save()
"""
metadata = {
"id": "code:document.docx.library",
"name": "DOCX Document Library",
"description": "Library for working with Word documents: comments, tracked changes, and editing",
"language": "python",
"packages": ["defusedxml"],
"args": []
}
import html
import random
import shutil
import tempfile
from datetime import datetime, timezone
from pathlib import Path
from defusedxml import minidom
from ooxml.scripts.pack import pack_document
from ooxml.scripts.validation.docx import DOCXSchemaValidator
from ooxml.scripts.validation.redlining import RedliningValidator
# Utility module bullet (resolved to sibling file in scripts/ at runtime)
# code:document.docx.xml_editor
from .utilities import XMLEditor
# Template bullets (resolved to sibling files in scripts/ at runtime)
# code:docx.tpl.people, code:docx.tpl.comments, code:docx.tpl.commentsextended,
# code:docx.tpl.commentsids, code:docx.tpl.commentsextensible
SCRIPT_DIR = Path(__file__).parent
def get_template_path(template_id: str) -> Path:
"""Get path to template bullet file.
Args:
template_id: Template bullet ID (e.g., "code:docx.tpl.comments")
Returns:
Path to the template file in scripts/ directory
"""
# Extract the ID part after "code:" and add .xml extension
name = template_id.replace("code:", "")
return SCRIPT_DIR / f"{name}.xml"
class DocxXMLEditor(XMLEditor):
"""XMLEditor that automatically applies RSID, author, and date to new elements.
Automatically adds attributes to elements that support them when inserting new content:
- w:rsidR, w:rsidRDefault, w:rsidP (for w:p and w:r elements)
- w:author and w:date (for w:ins, w:del, w:comment elements)
- w:id (for w:ins and w:del elements)
Attributes:
dom (defusedxml.minidom.Document): The DOM document for direct manipulation
"""
def __init__(
self, xml_path, rsid: str, author: str = "Claude", initials: str = "C"
):
"""Initialize with required RSID and optional author.
Args:
xml_path: Path to XML file to edit
rsid: RSID to automatically apply to new elements
author: Author name for tracked changes and comments (default: "Claude")
initials: Author initials (default: "C")
"""
super().__init__(xml_path)
self.rsid = rsid
self.author = author
self.initials = initials
def _get_next_change_id(self):
"""Get the next available change ID by checking all tracked change elements."""
max_id = -1
for tag in ("w:ins", "w:del"):
elements = self.dom.getElementsByTagName(tag)
for elem in elements:
change_id = elem.getAttribute("w:id")
if change_id:
try:
max_id = max(max_id, int(change_id))
except ValueError:
pass
return max_id + 1
def _ensure_w16du_namespace(self):
"""Ensure w16du namespace is declared on the root element."""
root = self.dom.documentElement
if not root.hasAttribute("xmlns:w16du"): # type: ignore
root.setAttribute( # type: ignore
"xmlns:w16du",
"http://schemas.microsoft.com/office/word/2023/wordml/word16du",
)
def _ensure_w16cex_namespace(self):
"""Ensure w16cex namespace is declared on the root element."""
root = self.dom.documentElement
if not root.hasAttribute("xmlns:w16cex"): # type: ignore
root.setAttribute( # type: ignore
"xmlns:w16cex",
"http://schemas.microsoft.com/office/word/2018/wordml/cex",
)
def _ensure_w14_namespace(self):
"""Ensure w14 namespace is declared on the root element."""
root = self.dom.documentElement
if not root.hasAttribute("xmlns:w14"): # type: ignore
root.setAttribute( # type: ignore
"xmlns:w14",
"http://schemas.microsoft.com/office/word/2010/wordml",
)
def _inject_attributes_to_nodes(self, nodes):
"""Inject RSID, author, and date attributes into DOM nodes where applicable.
Adds attributes to elements that support them:
- w:r: gets w:rsidR (or w:rsidDel if inside w:del)
- w:p: gets w:rsidR, w:rsidRDefault, w:rsidP, w14:paraId, w14:textId
- w:t: gets xml:space="preserve" if text has leading/trailing whitespace
- w:ins, w:del: get w:id, w:author, w:date, w16du:dateUtc
- w:comment: gets w:author, w:date, w:initials
- w16cex:commentExtensible: gets w16cex:dateUtc
Args:
nodes: List of DOM nodes to process
"""
from datetime import datetime, timezone
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
def is_inside_deletion(elem):
"""Check if element is inside a w:del element."""
parent = elem.parentNode
while parent:
if parent.nodeType == parent.ELEMENT_NODE and parent.tagName == "w:del":
return True
parent = parent.parentNode
return False
def add_rsid_to_p(elem):
if not elem.hasAttribute("w:rsidR"):
elem.setAttribute("w:rsidR", self.rsid)
if not elem.hasAttribute("w:rsidRDefault"):
elem.setAttribute("w:rsidRDefault", self.rsid)
if not elem.hasAttribute("w:rsidP"):
elem.setAttribute("w:rsidP", self.rsid)
# Add w14:paraId and w14:textId if not present
if not elem.hasAttribute("w14:paraId"):
self._ensure_w14_namespace()
elem.setAttribute("w14:paraId", _generate_hex_id())
if not elem.hasAttribute("w14:textId"):
self._ensure_w14_namespace()
elem.setAttribute("w14:textId", _generate_hex_id())
def add_rsid_to_r(elem):
# Use w:rsidDel for <w:r> inside <w:del>, otherwise w:rsidR
if is_inside_deletion(elem):
if not elem.hasAttribute("w:rsidDel"):
elem.setAttribute("w:rsidDel", self.rsid)
else:
if not elem.hasAttribute("w:rsidR"):
elem.setAttribute("w:rsidR", self.rsid)
def add_tracked_change_attrs(elem):
# Auto-assign w:id if not present
if not elem.hasAttribute("w:id"):
elem.setAttribute("w:id", str(self._get_next_change_id()))
if not elem.hasAttribute("w:author"):
elem.setAttribute("w:author", self.author)
if not elem.hasAttribute("w:date"):
elem.setAttribute("w:date", timestamp)
# Add w16du:dateUtc for tracked changes (same as w:date since we generate UTC timestamps)
if elem.tagName in ("w:ins", "w:del") and not elem.hasAttribute(
"w16du:dateUtc"
):
self._ensure_w16du_namespace()
elem.setAttribute("w16du:dateUtc", timestamp)
def add_comment_attrs(elem):
if not elem.hasAttribute("w:author"):
elem.setAttribute("w:author", self.author)
if not elem.hasAttribute("w:date"):
elem.setAttribute("w:date", timestamp)
if not elem.hasAttribute("w:initials"):
elem.setAttribute("w:initials", self.initials)
def add_comment_extensible_date(elem):
# Add w16cex:dateUtc for comment extensible elements
if not elem.hasAttribute("w16cex:dateUtc"):
self._ensure_w16cex_namespace()
elem.setAttribute("w16cex:dateUtc", timestamp)
def add_xml_space_to_t(elem):
# Add xml:space="preserve" to w:t if text has leading/trailing whitespace
if (
elem.firstChild
and elem.firstChild.nodeType == elem.firstChild.TEXT_NODE
):
text = elem.firstChild.data
if text and (text[0].isspace() or text[-1].isspace()):
if not elem.hasAttribute("xml:space"):
elem.setAttribute("xml:space", "preserve")
for node in nodes:
if node.nodeType != node.ELEMENT_NODE:
continue
# Handle the node itself
if node.tagName == "w:p":
add_rsid_to_p(node)
elif node.tagName == "w:r":
add_rsid_to_r(node)
elif node.tagName == "w:t":
add_xml_space_to_t(node)
elif node.tagName in ("w:ins", "w:del"):
add_tracked_change_attrs(node)
elif node.tagName == "w:comment":
add_comment_attrs(node)
elif node.tagName == "w16cex:commentExtensible":
add_comment_extensible_date(node)
# Process descendants (getElementsByTagName doesn't return the element itself)
for elem in node.getElementsByTagName("w:p"):
add_rsid_to_p(elem)
for elem in node.getElementsByTagName("w:r"):
add_rsid_to_r(elem)
for elem in node.getElementsByTagName("w:t"):
add_xml_space_to_t(elem)
for tag in ("w:ins", "w:del"):
for elem in node.getElementsByTagName(tag):
add_tracked_change_attrs(elem)
for elem in node.getElementsByTagName("w:comment"):
add_comment_attrs(elem)
for elem in node.getElementsByTagName("w16cex:commentExtensible"):
add_comment_extensible_date(elem)
def replace_node(self, elem, new_content):
"""Replace node with automatic attribute injection."""
nodes = super().replace_node(elem, new_content)
self._inject_attributes_to_nodes(nodes)
return nodes
def insert_after(self, elem, xml_content):
"""Insert after with automatic attribute injection."""
nodes = super().insert_after(elem, xml_content)
self._inject_attributes_to_nodes(nodes)
return nodes
def insert_before(self, elem, xml_content):
"""Insert before with automatic attribute injection."""
nodes = super().insert_before(elem, xml_content)
self._inject_attributes_to_nodes(nodes)
return nodes
def append_to(self, elem, xml_content):
"""Append to with automatic attribute injection."""
nodes = super().append_to(elem, xml_content)
self._inject_attributes_to_nodes(nodes)
return nodes
def revert_insertion(self, elem):
"""Reject an insertion by wrapping its content in a deletion.
Wraps all runs inside w:ins in w:del, converting w:t to w:delText.
Can process a single w:ins element or a container element with multiple w:ins.
Args:
elem: Element to process (w:ins, w:p, w:body, etc.)
Returns:
list: List containing the processed element(s)
Raises:
ValueError: If the element contains no w:ins elements
Example:
# Reject a single insertion
ins = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "5"})
doc["word/document.xml"].revert_insertion(ins)
# Reject all insertions in a paragraph
para = doc["word/document.xml"].get_node(tag="w:p", line_number=42)
doc["word/document.xml"].revert_insertion(para)
"""
# Collect insertions
ins_elements = []
if elem.tagName == "w:ins":
ins_elements.append(elem)
else:
ins_elements.extend(elem.getElementsByTagName("w:ins"))
# Validate that there are insertions to reject
if not ins_elements:
raise ValueError(
f"revert_insertion requires w:ins elements. "
f"The provided element <{elem.tagName}> contains no insertions. "
)
# Process all insertions - wrap all children in w:del
for ins_elem in ins_elements:
runs = list(ins_elem.getElementsByTagName("w:r"))
if not runs:
continue
# Create deletion wrapper
del_wrapper = self.dom.createElement("w:del")
# Process each run
for run in runs:
# Convert w:t → w:delText and w:rsidR → w:rsidDel
if run.hasAttribute("w:rsidR"):
run.setAttribute("w:rsidDel", run.getAttribute("w:rsidR"))
run.removeAttribute("w:rsidR")
elif not run.hasAttribute("w:rsidDel"):
run.setAttribute("w:rsidDel", self.rsid)
for t_elem in list(run.getElementsByTagName("w:t")):
del_text = self.dom.createElement("w:delText")
# Copy ALL child nodes (not just firstChild) to handle entities
while t_elem.firstChild:
del_text.appendChild(t_elem.firstChild)
for i in range(t_elem.attributes.length):
attr = t_elem.attributes.item(i)
del_text.setAttribute(attr.name, attr.value)
t_elem.parentNode.replaceChild(del_text, t_elem)
# Move all children from ins to del wrapper
while ins_elem.firstChild:
del_wrapper.appendChild(ins_elem.firstChild)
# Add del wrapper back to ins
ins_elem.appendChild(del_wrapper)
# Inject attributes to the deletion wrapper
self._inject_attributes_to_nodes([del_wrapper])
return [elem]
def revert_deletion(self, elem):
"""Reject a deletion by re-inserting the deleted content.
Creates w:ins elements after each w:del, copying deleted content and
converting w:delText back to w:t.
Can process a single w:del element or a container element with multiple w:del.
Args:
elem: Element to process (w:del, w:p, w:body, etc.)
Returns:
list: If elem is w:del, returns [elem, new_ins]. Otherwise returns [elem].
Raises:
ValueError: If the element contains no w:del elements
Example:
# Reject a single deletion - returns [w:del, w:ins]
del_elem = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "3"})
nodes = doc["word/document.xml"].revert_deletion(del_elem)
# Reject all deletions in a paragraph - returns [para]
para = doc["word/document.xml"].get_node(tag="w:p", line_number=42)
nodes = doc["word/document.xml"].revert_deletion(para)
"""
# Collect deletions FIRST - before we modify the DOM
del_elements = []
is_single_del = elem.tagName == "w:del"
if is_single_del:
del_elements.append(elem)
else:
del_elements.extend(elem.getElementsByTagName("w:del"))
# Validate that there are deletions to reject
if not del_elements:
raise ValueError(
f"revert_deletion requires w:del elements. "
f"The provided element <{elem.tagName}> contains no deletions. "
)
# Track created insertion (only relevant if elem is a single w:del)
created_insertion = None
# Process all deletions - create insertions that copy the deleted content
for del_elem in del_elements:
# Clone the deleted runs and convert them to insertions
runs = list(del_elem.getElementsByTagName("w:r"))
if not runs:
continue
# Create insertion wrapper
ins_elem = self.dom.createElement("w:ins")
for run in runs:
# Clone the run
new_run = run.cloneNode(True)
# Convert w:delText → w:t
for del_text in list(new_run.getElementsByTagName("w:delText")):
t_elem = self.dom.createElement("w:t")
# Copy ALL child nodes (not just firstChild) to handle entities
while del_text.firstChild:
t_elem.appendChild(del_text.firstChild)
for i in range(del_text.attributes.length):
attr = del_text.attributes.item(i)
t_elem.setAttribute(attr.name, attr.value)
del_text.parentNode.replaceChild(t_elem, del_text)
# Update run attributes: w:rsidDel → w:rsidR
if new_run.hasAttribute("w:rsidDel"):
new_run.setAttribute("w:rsidR", new_run.getAttribute("w:rsidDel"))
new_run.removeAttribute("w:rsidDel")
elif not new_run.hasAttribute("w:rsidR"):
new_run.setAttribute("w:rsidR", self.rsid)
ins_elem.appendChild(new_run)
# Insert the new insertion after the deletion
nodes = self.insert_after(del_elem, ins_elem.toxml())
# If processing a single w:del, track the created insertion
if is_single_del and nodes:
created_insertion = nodes[0]
# Return based on input type
if is_single_del and created_insertion:
return [elem, created_insertion]
else:
return [elem]
@staticmethod
def suggest_paragraph(xml_content: str) -> str:
"""Transform paragraph XML to add tracked change wrapping for insertion.
Wraps runs in <w:ins> and adds <w:ins/> to w:rPr in w:pPr for numbered lists.
Args:
xml_content: XML string containing a <w:p> element
Returns:
str: Transformed XML with tracked change wrapping
"""
wrapper = f'<root xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">{xml_content}</root>'
doc = minidom.parseString(wrapper)
para = doc.getElementsByTagName("w:p")[0]
# Ensure w:pPr exists
pPr_list = para.getElementsByTagName("w:pPr")
if not pPr_list:
pPr = doc.createElement("w:pPr")
para.insertBefore(
pPr, para.firstChild
) if para.firstChild else para.appendChild(pPr)
else:
pPr = pPr_list[0]
# Ensure w:rPr exists in w:pPr
rPr_list = pPr.getElementsByTagName("w:rPr")
if not rPr_list:
rPr = doc.createElement("w:rPr")
pPr.appendChild(rPr)
else:
rPr = rPr_list[0]
# Add <w:ins/> to w:rPr
ins_marker = doc.createElement("w:ins")
rPr.insertBefore(
ins_marker, rPr.firstChild
) if rPr.firstChild else rPr.appendChild(ins_marker)
# Wrap all non-pPr children in <w:ins>
ins_wrapper = doc.createElement("w:ins")
for child in [c for c in para.childNodes if c.nodeName != "w:pPr"]:
para.removeChild(child)
ins_wrapper.appendChild(child)
para.appendChild(ins_wrapper)
return para.toxml()
def suggest_deletion(self, elem):
"""Mark a w:r or w:p element as deleted with tracked changes (in-place DOM manipulation).
For w:r: wraps in <w:del>, converts <w:t> to <w:delText>, preserves w:rPr
For w:p (regular): wraps content in <w:del>, converts <w:t> to <w:delText>
For w:p (numbered list): adds <w:del/> to w:rPr in w:pPr, wraps content in <w:del>
Args:
elem: A w:r or w:p DOM element without existing tracked changes
Returns:
Element: The modified element
Raises:
ValueError: If element has existing tracked changes or invalid structure
"""
if elem.nodeName == "w:r":
# Check for existing w:delText
if elem.getElementsByTagName("w:delText"):
raise ValueError("w:r element already contains w:delText")
# Convert w:t → w:delText
for t_elem in list(elem.getElementsByTagName("w:t")):
del_text = self.dom.createElement("w:delText")
# Copy ALL child nodes (not just firstChild) to handle entities
while t_elem.firstChild:
del_text.appendChild(t_elem.firstChild)
# Preserve attributes like xml:space
for i in range(t_elem.attributes.length):
attr = t_elem.attributes.item(i)
del_text.setAttribute(attr.name, attr.value)
t_elem.parentNode.replaceChild(del_text, t_elem)
# Update run attributes: w:rsidR → w:rsidDel
if elem.hasAttribute("w:rsidR"):
elem.setAttribute("w:rsidDel", elem.getAttribute("w:rsidR"))
elem.removeAttribute("w:rsidR")
elif not elem.hasAttribute("w:rsidDel"):
elem.setAttribute("w:rsidDel", self.rsid)
# Wrap in w:del
del_wrapper = self.dom.createElement("w:del")
parent = elem.parentNode
parent.insertBefore(del_wrapper, elem)
parent.removeChild(elem)
del_wrapper.appendChild(elem)
# Inject attributes to the deletion wrapper
self._inject_attributes_to_nodes([del_wrapper])
return del_wrapper
elif elem.nodeName == "w:p":
# Check for existing tracked changes
if elem.getElementsByTagName("w:ins") or elem.getElementsByTagName("w:del"):
raise ValueError("w:p element already contains tracked changes")
# Check if it's a numbered list item
pPr_list = elem.getElementsByTagName("w:pPr")
is_numbered = pPr_list and pPr_list[0].getElementsByTagName("w:numPr")
if is_numbered:
# Add <w:del/> to w:rPr in w:pPr
pPr = pPr_list[0]
rPr_list = pPr.getElementsByTagName("w:rPr")
if not rPr_list:
rPr = self.dom.createElement("w:rPr")
pPr.appendChild(rPr)
else:
rPr = rPr_list[0]
# Add <w:del/> marker
del_marker = self.dom.createElement("w:del")
rPr.insertBefore(
del_marker, rPr.firstChild
) if rPr.firstChild else rPr.appendChild(del_marker)
# Convert w:t → w:delText in all runs
for t_elem in list(elem.getElementsByTagName("w:t")):
del_text = self.dom.createElement("w:delText")
# Copy ALL child nodes (not just firstChild) to handle entities
while t_elem.firstChild:
del_text.appendChild(t_elem.firstChild)
# Preserve attributes like xml:space
for i in range(t_elem.attributes.length):
attr = t_elem.attributes.item(i)
del_text.setAttribute(attr.name, attr.value)
t_elem.parentNode.replaceChild(del_text, t_elem)
# Update run attributes: w:rsidR → w:rsidDel
for run in elem.getElementsByTagName("w:r"):
if run.hasAttribute("w:rsidR"):
run.setAttribute("w:rsidDel", run.getAttribute("w:rsidR"))
run.removeAttribute("w:rsidR")
elif not run.hasAttribute("w:rsidDel"):
run.setAttribute("w:rsidDel", self.rsid)
# Wrap all non-pPr children in <w:del>
del_wrapper = self.dom.createElement("w:del")
for child in [c for c in elem.childNodes if c.nodeName != "w:pPr"]:
elem.removeChild(child)
del_wrapper.appendChild(child)
elem.appendChild(del_wrapper)
# Inject attributes to the deletion wrapper
self._inject_attributes_to_nodes([del_wrapper])
return elem
else:
raise ValueError(f"Element must be w:r or w:p, got {elem.nodeName}")
def _generate_hex_id() -> str:
"""Generate random 8-character hex ID for para/durable IDs.
Values are constrained to be less than 0x7FFFFFFF per OOXML spec:
- paraId must be < 0x80000000
- durableId must be < 0x7FFFFFFF
We use the stricter constraint (0x7FFFFFFF) for both.
"""
return f"{random.randint(1, 0x7FFFFFFE):08X}"
def _generate_rsid() -> str:
"""Generate random 8-character hex RSID."""
return "".join(random.choices("0123456789ABCDEF", k=8))
class Document:
"""Manages comments in unpacked Word documents."""
def __init__(
self,
unpacked_dir,
rsid=None,
track_revisions=False,
author="Claude",
initials="C",
):
"""
Initialize with path to unpacked Word document directory.
Automatically sets up comment infrastructure (people.xml, RSIDs).
Args:
unpacked_dir: Path to unpacked DOCX directory (must contain word/ subdirectory)
rsid: Optional RSID to use for all comment elements. If not provided, one will be generated.
track_revisions: If True, enables track revisions in settings.xml (default: False)
author: Default author name for comments (default: "Claude")
initials: Default author initials for comments (default: "C")
"""
self.original_path = Path(unpacked_dir)
if not self.original_path.exists() or not self.original_path.is_dir():
raise ValueError(f"Directory not found: {unpacked_dir}")
# Create temporary directory with subdirectories for unpacked content and baseline
self.temp_dir = tempfile.mkdtemp(prefix="docx_")
self.unpacked_path = Path(self.temp_dir) / "unpacked"
shutil.copytree(self.original_path, self.unpacked_path)
# Pack original directory into temporary .docx for validation baseline (outside unpacked dir)
self.original_docx = Path(self.temp_dir) / "original.docx"
pack_document(self.original_path, self.original_docx, validate=False)
self.word_path = self.unpacked_path / "word"
# Generate RSID if not provided
self.rsid = rsid if rsid else _generate_rsid()
print(f"Using RSID: {self.rsid}")
# Set default author and initials
self.author = author
self.initials = initials
# Cache for lazy-loaded editors
self._editors = {}
# Comment file paths
self.comments_path = self.word_path / "comments.xml"
self.comments_extended_path = self.word_path / "commentsExtended.xml"
self.comments_ids_path = self.word_path / "commentsIds.xml"
self.comments_extensible_path = self.word_path / "commentsExtensible.xml"
# Load existing comments and determine next ID (before setup modifies files)
self.existing_comments = self._load_existing_comments()
self.next_comment_id = self._get_next_comment_id()
# Convenient access to document.xml editor (semi-private)
self._document = self["word/document.xml"]
# Setup tracked changes infrastructure
self._setup_tracking(track_revisions=track_revisions)
# Add author to people.xml
self._add_author_to_people(author)
def __getitem__(self, xml_path: str) -> DocxXMLEditor:
"""
Get or create a DocxXMLEditor for the specified XML file.
Enables lazy-loaded editors with bracket notation:
node = doc["word/document.xml"].get_node(tag="w:p", line_number=42)
Args:
xml_path: Relative path to XML file (e.g., "word/document.xml", "word/comments.xml")
Returns:
DocxXMLEditor instance for the specified file
Raises:
ValueError: If the file does not exist
Example:
# Get node from document.xml
node = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "1"})
# Get node from comments.xml
comment = doc["word/comments.xml"].get_node(tag="w:comment", attrs={"w:id": "0"})
"""
if xml_path not in self._editors:
file_path = self.unpacked_path / xml_path
if not file_path.exists():
raise ValueError(f"XML file not found: {xml_path}")
# Use DocxXMLEditor with RSID, author, and initials for all editors
self._editors[xml_path] = DocxXMLEditor(
file_path, rsid=self.rsid, author=self.author, initials=self.initials
)
return self._editors[xml_path]
def add_comment(self, start, end, text: str) -> int:
"""
Add a comment spanning from one element to another.
Args:
start: DOM element for the starting point
end: DOM element for the ending point
text: Comment content
Returns:
The comment ID that was created
Example:
start_node = cm.get_document_node(tag="w:del", id="1")
end_node = cm.get_document_node(tag="w:ins", id="2")
cm.add_comment(start=start_node, end=end_node, text="Explanation")
"""
comment_id = self.next_comment_id
para_id = _generate_hex_id()
durable_id = _generate_hex_id()
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
# Add comment ranges to document.xml immediately
self._document.insert_before(start, self._comment_range_start_xml(comment_id))
# If end node is a paragraph, append comment markup inside it
# Otherwise insert after it (for run-level anchors)
if end.tagName == "w:p":
self._document.append_to(end, self._comment_range_end_xml(comment_id))
else:
self._document.insert_after(end, self._comment_range_end_xml(comment_id))
# Add to comments.xml immediately
self._add_to_comments_xml(
comment_id, para_id, text, self.author, self.initials, timestamp
)
# Add to commentsExtended.xml immediately
self._add_to_comments_extended_xml(para_id, parent_para_id=None)
# Add to commentsIds.xml immediately
self._add_to_comments_ids_xml(para_id, durable_id)
# Add to commentsExtensible.xml immediately
self._add_to_comments_extensible_xml(durable_id)
# Update existing_comments so replies work
self.existing_comments[comment_id] = {"para_id": para_id}
self.next_comment_id += 1
return comment_id
def reply_to_comment(
self,
parent_comment_id: int,
text: str,
) -> int:
"""
Add a reply to an existing comment.
Args:
parent_comment_id: The w:id of the parent comment to reply to
text: Reply text
Returns:
The comment ID that was created for the reply
Example:
cm.reply_to_comment(parent_comment_id=0, text="I agree with this change")
"""
if parent_comment_id not in self.existing_comments:
raise ValueError(f"Parent comment with id={parent_comment_id} not found")
parent_info = self.existing_comments[parent_comment_id]
comment_id = self.next_comment_id
para_id = _generate_hex_id()
durable_id = _generate_hex_id()
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
# Add comment ranges to document.xml immediately
parent_start_elem = self._document.get_node(
tag="w:commentRangeStart", attrs={"w:id": str(parent_comment_id)}
)
parent_ref_elem = self._document.get_node(
tag="w:commentReference", attrs={"w:id": str(parent_comment_id)}
)
self._document.insert_after(
parent_start_elem, self._comment_range_start_xml(comment_id)
)
parent_ref_run = parent_ref_elem.parentNode
self._document.insert_after(
parent_ref_run, f'<w:commentRangeEnd w:id="{comment_id}"/>'
)
self._document.insert_after(
parent_ref_run, self._comment_ref_run_xml(comment_id)
)
# Add to comments.xml immediately
self._add_to_comments_xml(
comment_id, para_id, text, self.author, self.initials, timestamp
)
# Add to commentsExtended.xml immediately (with parent)
self._add_to_comments_extended_xml(
para_id, parent_para_id=parent_info["para_id"]
)
# Add to commentsIds.xml immediately
self._add_to_comments_ids_xml(para_id, durable_id)
# Add to commentsExtensible.xml immediately
self._add_to_comments_extensible_xml(durable_id)
# Update existing_comments so replies work
self.existing_comments[comment_id] = {"para_id": para_id}
self.next_comment_id += 1
return comment_id
def __del__(self):
"""Clean up temporary directory on deletion."""
if hasattr(self, "temp_dir") and Path(self.temp_dir).exists():
shutil.rmtree(self.temp_dir)
def validate(self) -> None:
"""
Validate the document against XSD schema and redlining rules.
Raises:
ValueError: If validation fails.
"""
# Create validators with current state
schema_validator = DOCXSchemaValidator(
self.unpacked_path, self.original_docx, verbose=False
)
redlining_validator = RedliningValidator(
self.unpacked_path, self.original_docx, verbose=False
)
# Run validations
if not schema_validator.validate():
raise ValueError("Schema validation failed")
if not redlining_validator.validate():
raise ValueError("Redlining validation failed")
def save(self, destination=None, validate=True) -> None:
"""
Save all modified XML files to disk and copy to destination directory.
This persists all changes made via add_comment() and reply_to_comment().
Args:
destination: Optional path to save to. If None, saves back to original directory.
validate: If True, validates document before saving (default: True).
"""
# Only ensure comment relationships and content types if comment files exist
if self.comments_path.exists():
self._ensure_comment_relationships()
self._ensure_comment_content_types()
# Save all modified XML files in temp directory
for editor in self._editors.values():
editor.save()
# Validate by default
if validate:
self.validate()
# Copy contents from temp directory to destination (or original directory)
target_path = Path(destination) if destination else self.original_path
shutil.copytree(self.unpacked_path, target_path, dirs_exist_ok=True)
# ==================== Private: Initialization ====================
def _get_next_comment_id(self):
"""Get the next available comment ID."""
if not self.comments_path.exists():
return 0
editor = self["word/comments.xml"]
max_id = -1
for comment_elem in editor.dom.getElementsByTagName("w:comment"):
comment_id = comment_elem.getAttribute("w:id")
if comment_id:
try:
max_id = max(max_id, int(comment_id))
except ValueError:
pass
return max_id + 1
def _load_existing_comments(self):
"""Load existing comments from files to enable replies."""
if not self.comments_path.exists():
return {}
editor = self["word/comments.xml"]
existing = {}
for comment_elem in editor.dom.getElementsByTagName("w:comment"):
comment_id = comment_elem.getAttribute("w:id")
if not comment_id:
continue
# Find para_id from the w:p element within the comment
para_id = None
for p_elem in comment_elem.getElementsByTagName("w:p"):
para_id = p_elem.getAttribute("w14:paraId")
if para_id:
break
if not para_id:
continue
existing[int(comment_id)] = {"para_id": para_id}
return existing
# ==================== Private: Setup Methods ====================
def _setup_tracking(self, track_revisions=False):
"""Set up comment infrastructure in unpacked directory.
Args:
track_revisions: If True, enables track revisions in settings.xml
"""
# Create or update word/people.xml
people_file = self.word_path / "people.xml"
self._update_people_xml(people_file)
# Update XML files
self._add_content_type_for_people(self.unpacked_path / "[Content_Types].xml")
self._add_relationship_for_people(
self.word_path / "_rels" / "document.xml.rels"
)
# Always add RSID to settings.xml, optionally enable trackRevisions
self._update_settings(
self.word_path / "settings.xml", track_revisions=track_revisions
)
def _update_people_xml(self, path):
"""Create people.xml if it doesn't exist."""
if not path.exists():
# Copy from template
shutil.copy(get_template_path("code:docx.tpl.people"), path)
def _add_content_type_for_people(self, path):
"""Add people.xml content type to [Content_Types].xml if not already present."""
editor = self["[Content_Types].xml"]
if self._has_override(editor, "/word/people.xml"):
return
# Add Override element
root = editor.dom.documentElement
override_xml = '<Override PartName="/word/people.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.people+xml"/>'
editor.append_to(root, override_xml)
def _add_relationship_for_people(self, path):
"""Add people.xml relationship to document.xml.rels if not already present."""
editor = self["word/_rels/document.xml.rels"]
if self._has_relationship(editor, "people.xml"):
return
root = editor.dom.documentElement
root_tag = root.tagName # type: ignore
prefix = root_tag.split(":")[0] + ":" if ":" in root_tag else ""
next_rid = editor.get_next_rid()
# Create the relationship entry
rel_xml = f'<{prefix}Relationship Id="{next_rid}" Type="http://schemas.microsoft.com/office/2011/relationships/people" Target="people.xml"/>'
editor.append_to(root, rel_xml)
def _update_settings(self, path, track_revisions=False):
"""Add RSID and optionally enable track revisions in settings.xml.
Args:
path: Path to settings.xml
track_revisions: If True, adds trackRevisions element
Places elements per OOXML schema order:
- trackRevisions: early (before defaultTabStop)
- rsids: late (after compat)
"""
editor = self["word/settings.xml"]
root = editor.get_node(tag="w:settings")
prefix = root.tagName.split(":")[0] if ":" in root.tagName else "w"
# Conditionally add trackRevisions if requested
if track_revisions:
track_revisions_exists = any(
elem.tagName == f"{prefix}:trackRevisions"
for elem in editor.dom.getElementsByTagName(f"{prefix}:trackRevisions")
)
if not track_revisions_exists:
track_rev_xml = f"<{prefix}:trackRevisions/>"
# Try to insert before documentProtection, defaultTabStop, or at start
inserted = False
for tag in [f"{prefix}:documentProtection", f"{prefix}:defaultTabStop"]:
elements = editor.dom.getElementsByTagName(tag)
if elements:
editor.insert_before(elements[0], track_rev_xml)
inserted = True
break
if not inserted:
# Insert as first child of settings
if root.firstChild:
editor.insert_before(root.firstChild, track_rev_xml)
else:
editor.append_to(root, track_rev_xml)
# Always check if rsids section exists
rsids_elements = editor.dom.getElementsByTagName(f"{prefix}:rsids")
if not rsids_elements:
# Add new rsids section
rsids_xml = f'''<{prefix}:rsids>
<{prefix}:rsidRoot {prefix}:val="{self.rsid}"/>
<{prefix}:rsid {prefix}:val="{self.rsid}"/>
</{prefix}:rsids>'''
# Try to insert after compat, before clrSchemeMapping, or before closing tag
inserted = False
compat_elements = editor.dom.getElementsByTagName(f"{prefix}:compat")
if compat_elements:
editor.insert_after(compat_elements[0], rsids_xml)
inserted = True
if not inserted:
clr_elements = editor.dom.getElementsByTagName(
f"{prefix}:clrSchemeMapping"
)
if clr_elements:
editor.insert_before(clr_elements[0], rsids_xml)
inserted = True
if not inserted:
editor.append_to(root, rsids_xml)
else:
# Check if this rsid already exists
rsids_elem = rsids_elements[0]
rsid_exists = any(
elem.getAttribute(f"{prefix}:val") == self.rsid
for elem in rsids_elem.getElementsByTagName(f"{prefix}:rsid")
)
if not rsid_exists:
rsid_xml = f'<{prefix}:rsid {prefix}:val="{self.rsid}"/>'
editor.append_to(rsids_elem, rsid_xml)
# ==================== Private: XML File Creation ====================
def _add_to_comments_xml(
self, comment_id, para_id, text, author, initials, timestamp
):
"""Add a single comment to comments.xml."""
if not self.comments_path.exists():
shutil.copy(get_template_path("code:docx.tpl.comments"), self.comments_path)
editor = self["word/comments.xml"]
root = editor.get_node(tag="w:comments")
escaped_text = (
text.replace("&", "&").replace("<", "<").replace(">", ">")
)
# Note: w:rsidR, w:rsidRDefault, w:rsidP on w:p, w:rsidR on w:r,
# and w:author, w:date, w:initials on w:comment are automatically added by DocxXMLEditor
comment_xml = f'''<w:comment w:id="{comment_id}">
<w:p w14:paraId="{para_id}" w14:textId="77777777">
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:annotationRef/></w:r>
<w:r><w:rPr><w:color w:val="000000"/><w:sz w:val="20"/><w:szCs w:val="20"/></w:rPr><w:t>{escaped_text}</w:t></w:r>
</w:p>
</w:comment>'''
editor.append_to(root, comment_xml)
def _add_to_comments_extended_xml(self, para_id, parent_para_id):
"""Add a single comment to commentsExtended.xml."""
if not self.comments_extended_path.exists():
shutil.copy(
get_template_path("code:docx.tpl.commentsextended"), self.comments_extended_path
)
editor = self["word/commentsExtended.xml"]
root = editor.get_node(tag="w15:commentsEx")
if parent_para_id:
xml = f'<w15:commentEx w15:paraId="{para_id}" w15:paraIdParent="{parent_para_id}" w15:done="0"/>'
else:
xml = f'<w15:commentEx w15:paraId="{para_id}" w15:done="0"/>'
editor.append_to(root, xml)
def _add_to_comments_ids_xml(self, para_id, durable_id):
"""Add a single comment to commentsIds.xml."""
if not self.comments_ids_path.exists():
shutil.copy(get_template_path("code:docx.tpl.commentsids"), self.comments_ids_path)
editor = self["word/commentsIds.xml"]
root = editor.get_node(tag="w16cid:commentsIds")
xml = f'<w16cid:commentId w16cid:paraId="{para_id}" w16cid:durableId="{durable_id}"/>'
editor.append_to(root, xml)
def _add_to_comments_extensible_xml(self, durable_id):
"""Add a single comment to commentsExtensible.xml."""
if not self.comments_extensible_path.exists():
shutil.copy(
get_template_path("code:docx.tpl.commentsextensible"), self.comments_extensible_path
)
editor = self["word/commentsExtensible.xml"]
root = editor.get_node(tag="w16cex:commentsExtensible")
xml = f'<w16cex:commentExtensible w16cex:durableId="{durable_id}"/>'
editor.append_to(root, xml)
# ==================== Private: XML Fragments ====================
def _comment_range_start_xml(self, comment_id):
"""Generate XML for comment range start."""
return f'<w:commentRangeStart w:id="{comment_id}"/>'
def _comment_range_end_xml(self, comment_id):
"""Generate XML for comment range end with reference run.
Note: w:rsidR is automatically added by DocxXMLEditor.
"""
return f'''<w:commentRangeEnd w:id="{comment_id}"/>
<w:r>
<w:rPr><w:rStyle w:val="CommentReference"/></w:rPr>
<w:commentReference w:id="{comment_id}"/>
</w:r>'''
def _comment_ref_run_xml(self, comment_id):
"""Generate XML for comment reference run.
Note: w:rsidR is automatically added by DocxXMLEditor.
"""
return f'''<w:r>
<w:rPr><w:rStyle w:val="CommentReference"/></w:rPr>
<w:commentReference w:id="{comment_id}"/>
</w:r>'''
# ==================== Private: Metadata Updates ====================
def _has_relationship(self, editor, target):
"""Check if a relationship with given target exists."""
for rel_elem in editor.dom.getElementsByTagName("Relationship"):
if rel_elem.getAttribute("Target") == target:
return True
return False
def _has_override(self, editor, part_name):
"""Check if an override with given part name exists."""
for override_elem in editor.dom.getElementsByTagName("Override"):
if override_elem.getAttribute("PartName") == part_name:
return True
return False
def _has_author(self, editor, author):
"""Check if an author already exists in people.xml."""
for person_elem in editor.dom.getElementsByTagName("w15:person"):
if person_elem.getAttribute("w15:author") == author:
return True
return False
def _add_author_to_people(self, author):
"""Add author to people.xml (called during initialization)."""
people_path = self.word_path / "people.xml"
# people.xml should already exist from _setup_tracking
if not people_path.exists():
raise ValueError("people.xml should exist after _setup_tracking")
editor = self["word/people.xml"]
root = editor.get_node(tag="w15:people")
# Check if author already exists
if self._has_author(editor, author):
return
# Add author with proper XML escaping to prevent injection
escaped_author = html.escape(author, quote=True)
person_xml = f'''<w15:person w15:author="{escaped_author}">
<w15:presenceInfo w15:providerId="None" w15:userId="{escaped_author}"/>
</w15:person>'''
editor.append_to(root, person_xml)
def _ensure_comment_relationships(self):
"""Ensure word/_rels/document.xml.rels has comment relationships."""
editor = self["word/_rels/document.xml.rels"]
if self._has_relationship(editor, "comments.xml"):
return
root = editor.dom.documentElement
root_tag = root.tagName # type: ignore
prefix = root_tag.split(":")[0] + ":" if ":" in root_tag else ""
next_rid_num = int(editor.get_next_rid()[3:])
# Add relationship elements
rels = [
(
next_rid_num,
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments",
"comments.xml",
),
(
next_rid_num + 1,
"http://schemas.microsoft.com/office/2011/relationships/commentsExtended",
"commentsExtended.xml",
),
(
next_rid_num + 2,
"http://schemas.microsoft.com/office/2016/09/relationships/commentsIds",
"commentsIds.xml",
),
(
next_rid_num + 3,
"http://schemas.microsoft.com/office/2018/08/relationships/commentsExtensible",
"commentsExtensible.xml",
),
]
for rel_id, rel_type, target in rels:
rel_xml = f'<{prefix}Relationship Id="rId{rel_id}" Type="{rel_type}" Target="{target}"/>'
editor.append_to(root, rel_xml)
def _ensure_comment_content_types(self):
"""Ensure [Content_Types].xml has comment content types."""
editor = self["[Content_Types].xml"]
if self._has_override(editor, "/word/comments.xml"):
return
root = editor.dom.documentElement
# Add Override elements
overrides = [
(
"/word/comments.xml",
"application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml",
),
(
"/word/commentsExtended.xml",
"application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml",
),
(
"/word/commentsIds.xml",
"application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml",
),
(
"/word/commentsExtensible.xml",
"application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtensible+xml",
),
]
for part_name, content_type in overrides:
override_xml = (
f'<Override PartName="{part_name}" ContentType="{content_type}"/>'
)
editor.append_to(root, override_xml)