feat: add Word COM automation support for document handling and updates

Author: Krande

src/paradoc/io/word/exporter.py

@@ -24,6 +24,7 @@ def __init__(self, one_doc: OneDoc, main_tmpl=MY_DOCX_TMPL, app_tmpl=MY_DOCX_TMP
         self.main_tmpl = main_tmpl
         self.app_tmpl = app_tmpl
         self.use_custom_docx_compile = kwargs.get("use_custom_docx_compile", True)
+        self.enable_word_com_automation = kwargs.get("enable_word_com_automation", False)
 
     def export(self, output_name, dest_file, check_open_docs=False):
         if self.use_custom_docx_compile:
@@ -68,13 +69,16 @@ def _compile_individual_md_files_to_docx(self, output_name, dest_file, check_ope
         fix_headers_after_compose(composer_main.doc)
 
         print("Close Existing Word documents")
-        if check_open_docs:
+        if check_open_docs and self.enable_word_com_automation:
             close_word_docs_by_name([output_name, f"{output_name}.docx"])
 
         print(f'Saving Composed Document to "{dest_file}"')
         composer_main.save(dest_file)
 
-        docx_update(str(dest_file))
+        # Only attempt Word COM automation if explicitly enabled
+        # This is disabled by default to avoid fatal COM errors in test/CI environments
+        if self.enable_word_com_automation:
+            docx_update(str(dest_file))
 
     def format_tables(self, composer_doc: Document, is_appendix):
         for i, docx_tbl in enumerate(self.get_all_tables(composer_doc)):

src/paradoc/io/word/utils.py

@@ -28,67 +28,101 @@ def open_word_win32():
     import sys
 
     if sys.platform != "win32":
-        return
+        return None
 
     try:
         import win32com.client
 
+        # Use early binding to avoid some COM issues
         word = win32com.client.DispatchEx("Word.Application")
+        word.Visible = False
+        return word
     except (ModuleNotFoundError, ImportError):
-        logger.error(
-            "Ensure you have you have win32com installed. "
-            'Use "conda install -c conda-forge pywin32" to install. '
-            f"{traceback.format_exc()}"
+        logger.warning(
+            "win32com not available - Word COM automation will be skipped. "
+            'Install with "conda install -c conda-forge pywin32" if needed.'
         )
         return None
-    except BaseException as e:
-        logger.error(
-            "Probably unable to find COM connection to Word application. "
-            f"Is Word installed? {traceback.format_exc()}, {e}"
+    except Exception as e:
+        logger.warning(
+            f"Unable to start Word COM automation - will be skipped. Error: {e}"
         )
         return None
-    return word
 
 
 def docx_update(docx_file):
+    """
+    Update fields and table of contents in a .docx file using Word COM automation.
+    This is optional - if it fails, the document will still be saved correctly,
+    just without automatically updated field numbers.
+    """
     word = open_word_win32()
     if word is None:
+        logger.debug("Skipping Word COM update - automation not available")
         return
-    doc = word.Documents.Open(docx_file)
+
+    doc = None
     try:
+        # Convert to absolute path for COM
+        abs_path = str(pathlib.Path(docx_file).absolute())
+        doc = word.Documents.Open(abs_path, ReadOnly=False)
+
         # update all figure / table numbers
         word.ActiveDocument.Fields.Update()
 
         # update Table of content / figure / table
         if len(word.ActiveDocument.TablesOfContents) > 0:
             word.ActiveDocument.TablesOfContents(1).Update()
         else:
-            logger.error("No table of contents is found")
-        # word.ActiveDocument.TablesOfFigures(1).Update()
-        # word.ActiveDocument.TablesOfFigures(2).Update()
+            logger.debug("No table of contents found in document")
+
     except Exception as e:
-        raise Exception(e)
+        logger.warning(f"Failed to update document via Word COM (non-critical): {e}")
     finally:
-        doc.Close(SaveChanges=True)
+        # Clean up in reverse order
+        if doc is not None:
+            try:
+                doc.Close(SaveChanges=True)
+            except Exception as e:
+                logger.warning(f"Failed to close document: {e}")
 
-        word.Quit()
+        if word is not None:
+            try:
+                word.Quit()
+            except Exception as e:
+                logger.warning(f"Failed to quit Word application: {e}")
 
 
 def close_word_docs_by_name(names: list) -> None:
+    """
+    Close Word documents by name using COM automation.
+    This is optional - if it fails, documents will remain open which is non-critical.
+    """
     word = open_word_win32()
     if word is None:
+        logger.debug("Skipping Word document close - COM automation not available")
         return
 
-    if len(word.Documents) > 0:
-        for doc in word.Documents:
-            doc_name = doc.Name
-            if doc_name in names:
-                print(f'Closing "{doc}"')
-                doc.Close()
-    else:
-        print(f"No Word docs named {names} found to be open. Ending Word Application COM session")
-
-    word.Quit()
+    try:
+        if len(word.Documents) > 0:
+            for doc in word.Documents:
+                try:
+                    doc_name = doc.Name
+                    if doc_name in names:
+                        logger.info(f'Closing "{doc_name}"')
+                        doc.Close()
+                except Exception as e:
+                    logger.warning(f"Failed to close document: {e}")
+        else:
+            logger.debug(f"No Word docs named {names} found to be open")
+    except Exception as e:
+        logger.warning(f"Failed to access Word documents: {e}")
+    finally:
+        if word is not None:
+            try:
+                word.Quit()
+            except Exception as e:
+                logger.warning(f"Failed to quit Word application: {e}")
 
 
 def iter_block_items(parent):