Open a .docx file for reading and editing.

Unpacks the DOCX archive, parses all XML parts, and caches them in memory under a handle. Multiple documents may be open concurrently, each under its own handle.

Args: path: Absolute path to the .docx file. document_handle: Optional handle to store this document under. Empty string uses the shared __default__ slot (legacy behavior); pass a unique value (e.g. a UUID) per concurrent session for isolation.

Close a document and clean up temporary files.

Args: document_handle: Handle of the document to close. Empty = __default__ slot.

Create a new blank .docx document (or from a .dotx template).

The document is automatically opened for editing under the given handle. Use save_document to save changes, or start editing immediately with insert_text, add_table, etc.

Args: output_path: Path for the new .docx file. template_path: Optional path to a .dotx template file. document_handle: Optional handle to store this document under.

Create a new .docx document from markdown content.

Supports full GitHub-Flavored Markdown: headings, bold/italic/strikethrough, links, images, bullet/numbered/nested lists, code blocks, blockquotes, tables, footnotes, and task lists. Smart typography (curly quotes, em/en dashes, ellipses) is applied automatically.

Provide exactly one of md_path or markdown. The document is automatically opened for editing under the given handle.

Args: output_path: Path for the new .docx file. md_path: Path to a .md file. Mutually exclusive with markdown. markdown: Raw markdown text. Mutually exclusive with md_path. template_path: Optional path to a .dotx template file. document_handle: Optional handle to store this document under.

Get overview stats: paragraph count, headings, footnotes, comments, images.

Get the document heading structure with levels, text, and paraIds.

Returns a list of headings in document order, each with:

• level (1-9)

• text (heading content)

• style (e.g., "Heading1")

• paraId (unique paragraph identifier for targeting edits)

Search for text across the document body, footnotes, and comments.

Args: query: Text to search for (case-insensitive), or a regex pattern. regex: If true, treat query as a Python regular expression.

Returns matching paragraphs with their paraId, source part, and context.

Get the full text and style of a specific paragraph by its paraId.

Args: para_id: The 8-character hex paraId (e.g., "1A2B3C4D").

Get all tables with row/column counts and cell text content.

Insert a new table after a paragraph with tracked insertion.

Modify a table cell.

By default (tracked=True) the old content is marked as a deletion and the new content as an insertion — the human reviewer accepts/rejects in Word's Track Changes view. Pass tracked=False to overwrite the cell directly with no markup.

Args: table_idx: Table index (0-based). row: Row index (0-based). col: Column index (0-based). text: New cell text. author: Author name shown in Word's review pane (tracked=True only). tracked: True (default) = tracked del+ins. False = direct overwrite, no markup. document_handle: Optional handle for concurrent session isolation.

Add a row to a table with tracked insertion. row_idx=-1 appends.

Delete a table row with tracked changes.

Merge a rectangular range of cells. Horizontal: gridSpan. Vertical: vMerge.

Mark the first row as a repeating header row.

Set column widths in cm. len(widths_cm) must match column count.

Insert a table from CSV text.

Export a table as CSV string.

Delete a table by index (0-based). Raises IndexError if out of range.

Add a new column to every row of a table. First row gets header_text.

Delete a column (0-based) from every row of a table.

Set the width of a table cell in millimetres (stored as DXA).

Set vertical alignment of a table cell: top, center, or bottom.

Set row height in millimetres. rule: exact, atLeast, or auto.

Set table alignment: left, center, or right.

Set borders on all six sides of a table (top, bottom, left, right, insideH, insideV).

Set background shading fill color on a table cell.

Apply a named table style (e.g. TableGrid, LightShading-Accent1) to a table.

Apply list formatting to paragraphs (bullet or numbered).

Get all defined styles with ID, name, type, and base style.

Create a new style in the document.

Args: name: Style name (used as styleId after removing spaces). style_type: "paragraph", "character", "table", or "numbering". based_on: Optional styleId this style inherits from. next_style: Optional styleId applied to the next paragraph.

Update an existing style's basedOn and/or next properties.

Args: name: Style name or styleId (case-insensitive). based_on: New basedOn styleId (replaces existing). next_style: New next styleId (replaces existing).

Delete a style from the document.

Args: name: Style name or styleId (case-insensitive).

Get details of a single style by name or styleId (case-insensitive).

Args: name_or_id: Style name or styleId to look up.

Returns: {"style_id": str, "name": str, "type": str, "base_style": str, "next_style": str}

Deep-copy an existing style under a new name.

Args: source_name_or_id: Name or styleId of the style to copy. new_name: Name for the new style (spaces stripped for styleId).

Returns: {"style_id": str, "name": str, "type": str}

Apply a style to a list of paragraphs by their paraIds.

Args: para_ids: List of paragraph paraIds to update. style_name_or_id: Style name or styleId to apply.

Returns: {"applied": int, "style_id": str, "para_ids": list[str]}

Get all headers and footers with their text content.

Edit text in a header or footer.

By default (tracked=True) the change is recorded as a deletion of the old text and an insertion of the new text — the human reviewer accepts/rejects in Word. Pass tracked=False to replace the text directly with no revision markup.

Args: location: "header" or "footer" (matches the first found of that type). old_text: Text to find and replace. new_text: Replacement text. author: Author name shown in Word's review pane (tracked=True only). tracked: True (default) = tracked del+ins. False = direct replacement, no markup. document_handle: Optional handle for concurrent session isolation.

Delete a header by location: default, first, or even.

Delete a footer by location: default, first, or even.

Get core document properties (title, creator, subject, dates, revision).

Set core document properties. Empty string = unchanged.

Get custom document properties from docProps/custom.xml.

Set (upsert) a custom document property.

Args: name: Property name. value: Property value as a string. vt_type: VT type element name (lpwstr, i4, bool, etc.).

Delete a custom document property by name.

Args: name: Property name to delete.

Get all embedded images with rId, filename, content type, and dimensions.

Insert an image into the document after a paragraph.

Insert a floating (anchored) image. wrap: square|topbottom|none.

Remove the drawing containing the image with the given rId from the document.

Also removes the relationship entry from word/_rels/document.xml.rels.

Args: rId: The relationship ID of the image to delete (e.g. 'rId5').

Replace the binary for an existing image in-place.

The image dimensions and position in the document are preserved.

Args: rId: The relationship ID of the image to replace. new_image_path: Absolute path to the new image file on disk.

Resize an embedded image by updating its EMU extent attributes.

Args: rId: The relationship ID of the image to resize. width_cm: New width in centimetres. height_cm: New height in centimetres.

Set accessibility alt text and title on an embedded image.

Args: rId: The relationship ID of the image. alt_text: Alt text (descr attribute on wp:docPr). title: Optional title attribute on wp:docPr.

Set or remove a border on an embedded image.

Args: rId: The relationship ID of the image (e.g. 'rId6'). border_pt: Border width in points. Use 0 to remove the border. color: RGB hex color string without '#' (default '000000' = black).

Returns: JSON with rId, border_pt, and color fields.

Get all endnotes with their ID and text content.

Add an endnote to a paragraph.

Cross-reference endnote IDs between document.xml and endnotes.xml.

List all footnotes with their ID and text content.

Add a footnote to a paragraph. url, if provided, is rendered as a hotlink.

Add a subsequent reference to an existing footnote without creating a new definition.

Use when the same source must be cited again in a different paragraph. Inserts a hyperlink-wrapped footnoteReference that navigates to the same footnote as the original citation. Does not duplicate the footnote definition in footnotes.xml.

Cross-reference footnote IDs between document.xml and footnotes.xml.

Update the text of an existing footnote.

Args: footnote_id: The numeric ID of the footnote to update (must be >= 1). text: The new text content for the footnote.

Delete a footnote and its in-body reference.

Removes the footnote definition from footnotes.xml and removes the footnoteReference run from the document body.

Args: footnote_id: The numeric ID of the footnote to delete.

Update the text of an existing endnote.

Args: endnote_id: The numeric ID of the endnote to update (must be >= 1). text: The new text content for the endnote.

Delete an endnote and its in-body reference.

Removes the endnote definition from endnotes.xml and removes the endnoteReference run from the document body.

Args: endnote_id: The numeric ID of the endnote to delete.

Insert a page break after a paragraph.

Add a section break at a paragraph. break_type: nextPage/continuous/evenPage/oddPage.

Modify section properties (page size, orientation, margins). 0/empty = unchanged.

Set page size from millimetre values.

Args: width_mm: Page width in mm (e.g. 210 for A4, 215.9 for Letter). height_mm: Page height in mm (e.g. 297 for A4, 279.4 for Letter). para_id: paraId of paragraph with section break. None = body section.

Set page margins from millimetre values.

Args: top_mm: Top margin in mm. None = unchanged. bottom_mm: Bottom margin in mm. None = unchanged. left_mm: Left margin in mm. None = unchanged. right_mm: Right margin in mm. None = unchanged. para_id: paraId of paragraph with section break. None = body section.

Set page orientation, swapping width/height dimensions if needed.

Args: orientation: "portrait" or "landscape". para_id: paraId of paragraph with section break. None = body section.

List all sections in the document with their properties.

Returns a JSON array of section objects, each containing: index, break_type, page_width, page_height, orientation, columns, margin_top, margin_bottom (all sizes in twips/DXA). The final section always has break_type="".

Set the number of columns in a section.

Args: section_index: Zero-based section index (use get_sections to find it). num_columns: Number of text columns (1 = single column). equal_width: If True, all columns are equal width. Default True.

Remove a section break from a paragraph.

Removes the w:sectPr from the paragraph's w:pPr. After removal the paragraph's content flows into the next section rather than ending one.

Args: para_id: paraId of the paragraph that holds the section break.

Raises: ValueError: If the paragraph has no section break.

Enable or disable a different first-page header/footer for a section.

When enabled, the section can have a unique header/footer on its first page, separate from the header/footer used on subsequent pages.

Args: section_index: Zero-based section index (use get_sections to find it). enabled: True to enable different first page, False to disable.

Returns: {"section_index": int, "different_first_page": bool}

Enable or disable different odd/even page headers globally.

This is a document-level setting stored in word/settings.xml. When enabled, even-numbered pages can use a different header/footer from odd-numbered pages.

Args: enabled: True to enable different odd/even headers, False to disable.

Returns: {"odd_even_headers": bool}

Add a cross-reference link from one paragraph to another.

Set document protection. edit: trackedChanges/comments/readOnly/forms/none.

Merge another DOCX document's content into the current document.

Check paraId uniqueness across all document parts.

Insert a VML watermark into the document's default header.

Places a <v:shape> with a <v:textpath> inside the default header, which is the standard Word watermark pattern.

Args: text: Watermark text (e.g. "DRAFT", "CONFIDENTIAL"). diagonal: If True (default), diagonal orientation; if False, horizontal. document_handle: Optional handle for concurrent session isolation.

Remove VML watermarks (e.g., DRAFT) from all document headers.

Run a comprehensive structural audit of the document.

Insert text into a paragraph.

By default (tracked=True) the insertion is marked as a proposed addition that appears underlined in Word's Track Changes view. The human reviewer must accept it in Word before it becomes permanent. Pass tracked=False to write the text directly with no revision markup.

Args: para_id: paraId of the target paragraph. text: Text to insert. position: Where to insert — "start", "end", or a substring to insert after. author: Author name shown in Word's review pane (tracked=True only). context_before: Text immediately before the insertion point (for precise anchoring). context_after: Text immediately after the insertion point (for precise anchoring). ignore_case: If True, match context_before/context_after case-insensitively. tracked: True (default) = revision markup the human accepts/rejects in Word. False = text written directly, no markup. document_handle: Optional handle for concurrent session isolation.

Delete text from a paragraph.

Finds the text within the paragraph (across run boundaries if needed). With tracked=True (default) the deleted text stays visible as red strikethrough in Word's Track Changes view — the human reviewer must accept the deletion to remove it permanently. With tracked=False the text is removed immediately.

Provide context_before/context_after to disambiguate when the same text appears multiple times, or when it contains smart quotes / special whitespace.

Args: para_id: paraId of the target paragraph. text: Text to delete (ASCII quotes/dashes/spaces match their Unicode equivalents). author: Author name shown in Word's review pane (tracked=True only). context_before: Text immediately before the target (for precise anchoring). context_after: Text immediately after the target (for precise anchoring). ignore_case: If True, match text and context case-insensitively. tracked: True (default) = red strikethrough the human accepts/rejects. False = text removed immediately, no markup. document_handle: Optional handle for concurrent session isolation.

Replace text in a paragraph.

With tracked=True (default) the old text is shown as red strikethrough and the new text as an underlined insertion — the human reviewer accepts/rejects in Word. Only the actually-changed portion is marked; common leading/trailing text is left as plain runs. With tracked=False the replacement is applied immediately without any visible markup.

Args: para_id: paraId of the target paragraph. find: Text to find and replace (may span run boundaries). replace: Replacement text. author: Author name shown in Word's review pane (tracked=True only). context_before: Text immediately before the target (for precise anchoring). context_after: Text immediately after the target (for precise anchoring). tracked: True (default) = strikethrough + underline the human accepts/rejects. False = replaced immediately, no markup. document_handle: Optional handle for concurrent session isolation.

Return the full accepted-view text of the document.

Accepted view: w:ins text included, w:del text excluded. Includes text inside w:hyperlink runs. Paragraphs are joined by newline. Footnote text is returned separately.

Returns JSON: {"body": str, "footnotes": str}

Return all pending tracked changes (insertions and deletions) as a JSON list.

Each entry contains: type, change_id, author, date, para_id, text. Changes are returned in document order.

Accept tracked changes — keep insertions, remove deletions. Empty author = all.

Reject tracked changes — remove insertions, restore deleted text.

Accept a single tracked change by its change_id.

For insertions: keeps the inserted text (unwraps w:ins). For deletions: discards the deleted text (removes w:del).

Args: change_id: The integer id attribute of the w:ins or w:del element.

Reject a single tracked change by its change_id.

For insertions: discards the inserted text (removes w:ins). For deletions: keeps the deleted text (unwraps w:del, restoring text).

Args: change_id: The integer id attribute of the w:ins or w:del element.

Accept all tracked changes in document order.

Returns a JSON object with the count of accepted changes: {"accepted": int}.

Reject all tracked changes in document order.

Returns a JSON object with the count of rejected changes: {"rejected": int}.

Apply character formatting to text with tracked-change markup.

List all comments with their ID, author, date, and text.

Add a comment anchored to a paragraph.

Reply to an existing comment (creates a threaded reply).

Replace the text of an existing comment.

Args: comment_id: ID of the comment to update. text: New comment text.

Delete a comment and remove its range markers from the document.

Args: comment_id: ID of the comment to delete.

Mark a comment as resolved (sets w15:done='1' in commentsExtended.xml).

Args: comment_id: ID of the comment to resolve.