feat: add save_to_word function for exporting images to Word documents

Author: dwr-psandhu

pydelmod/plotutils.py

@@ -1,3 +1,4 @@
+from xml.dom.minidom import Document
 import pandas as pd
 import numpy as np
 import hvplot.pandas
@@ -82,3 +83,51 @@ def exceedance_plot(
 
 def save_figure(fig, filename):
     fig.savefig(filename, dpi=300, bbox_inches="tight")
+
+
+#
+import pathlib
+
+
+def save_to_word(
+    word_file, image_file, image_alt_text=None, image_caption=None, image_width=6.0
+):
+    """
+    Save an image to a Word document with metadata.
+
+    word_file: The path to the Word document. If it exists, the image will be added to it, else a new one will be created.
+    image_file: The path to the image file.
+    image_alt_text: Alternative text for the image.
+    image_caption: Caption for the image.
+    image_width: Width of the image in inches.
+
+    Note: requires pip install python-docx
+    """
+    try:
+        from pydoc import doc
+        from docx import Document
+        from docx.shared import Inches
+        from docx.oxml.shared import OxmlElement, qn
+    except ImportError:
+        print("Error: Required modules are not installed.")
+        print("pip install python-docx")
+        return
+    if not pathlib.Path(word_file).exists():
+        doc = Document()
+    else:
+        doc = Document(word_file)
+
+    p = doc.add_paragraph()
+    run = p.add_run()
+    picture = run.add_picture(image_file, width=Inches(image_width))
+    # Add alt text (good for accessibility/search inside Word)
+    # (python-docx doesn’t expose alt text directly; set it via XML on the inline drawing)
+    if image_alt_text:
+        inline = picture._inline
+        docPr = inline.docPr
+        docPr.set("title", image_caption)
+        docPr.set("descr", image_alt_text)
+    if image_caption:
+        caption = doc.add_paragraph(image_caption)
+    doc.add_page_break()
+    doc.save(word_file)