Merge branch 'main' into develop

CoderWanFeng · CoderWanFeng · commit 6e3bc4c7a1a7 · 2026-07-12T22:23:13.000+08:00
diff --git a/office/api/ppt.py b/office/api/ppt.py
@@ -15,8 +15,17 @@
     https://www.python-office.com
 """
 
-# 导入处理PPT的模块
-import poppt
+def _load_poppt():
+    try:
+        import poppt
+    except ModuleNotFoundError as exc:
+        if exc.name != "poppt":
+            raise
+        raise ModuleNotFoundError(
+            "PPT处理功能依赖 poppt，该功能仅支持安装了 Microsoft PowerPoint "
+            "和 poppt 的 Windows 环境。"
+        ) from exc
+    return poppt
 
 
 def ppt2pdf(path: str, output_path=r'./'):
@@ -31,6 +40,7 @@ def ppt2pdf(path: str, output_path=r'./'):
     Returns:
         None
     """
+    poppt = _load_poppt()
     poppt.ppt2pdf(path=path, output_path=output_path)
 
 
@@ -47,6 +57,7 @@ def ppt2img(input_path: str, output_path=r'./', merge: bool = False):
     Returns:
         None
     """
+    poppt = _load_poppt()
     poppt.ppt2img(input_path=input_path, output_path=output_path, merge=merge)
 
 
@@ -63,4 +74,5 @@ def merge4ppt(input_path: str, output_path=r'./', output_name: str = 'merge4ppt.
     Returns:
         None
     """
+    poppt = _load_poppt()
     poppt.merge4ppt(input_path=input_path, output_path=output_path, output_name=output_name)
diff --git a/office/api/wechat.py b/office/api/wechat.py
@@ -16,7 +16,18 @@
 """
 
 
-import PyOfficeRobot
+def _load_py_office_robot():
+    try:
+        import PyOfficeRobot
+    except ModuleNotFoundError as exc:
+        if exc.name != "PyOfficeRobot":
+            raise
+        raise ModuleNotFoundError(
+            "微信自动化功能依赖 PyOfficeRobot，该功能仅支持安装了桌面微信 "
+            "和 PyOfficeRobot 的 Windows 环境。"
+        ) from exc
+    return PyOfficeRobot
+
 
 def send_message(who: str, message: str):
     """Send message to specified contact.
@@ -30,6 +41,7 @@ def send_message(who: str, message: str):
     Returns:
         None
     """
+    PyOfficeRobot = _load_py_office_robot()
     PyOfficeRobot.chat.send_message(who=who, message=message)
 
 
@@ -46,6 +58,7 @@ def send_message_by_time(who, message, time):
     Returns:
         None
     """
+    PyOfficeRobot = _load_py_office_robot()
     PyOfficeRobot.chat.send_message_by_time(who=who, message=message, time=time)
 
 
@@ -61,6 +74,7 @@ def chat_by_keywords(who, keywords):
     Returns:
         None
     """
+    PyOfficeRobot = _load_py_office_robot()
     PyOfficeRobot.chat.chat_by_keywords(who=who, keywords=keywords)
 
 
@@ -76,6 +90,7 @@ def send_file(who, file):
     Returns:
         None
     """
+    PyOfficeRobot = _load_py_office_robot()
     PyOfficeRobot.file.send_file(who=who, file=file)
 
 
@@ -87,6 +102,7 @@ def group_send():
     Returns:
         None
     """
+    PyOfficeRobot = _load_py_office_robot()
     PyOfficeRobot.group.send()
 
 
@@ -109,6 +125,7 @@ def receive_message(who='文件传输助手', txt='userMessage.txt', output_path
     Returns:
         None: function result is saving messages to specified file and path / 函数的执行结果是将消息保存到指定的文件和路径中
     """
+    PyOfficeRobot = _load_py_office_robot()
     PyOfficeRobot.chat.receive_message(who=who, txt=txt, output_path=output_path)
 
 
@@ -123,4 +140,5 @@ def chat_robot(who='程序员晚枫'):
     Returns:
         None
     """
+    PyOfficeRobot = _load_py_office_robot()
     PyOfficeRobot.chat.chat_robot(who=who)
diff --git a/office/api/word.py b/office/api/word.py
@@ -15,7 +15,17 @@
     https://www.python-office.com
 """
 
-import poword
+def _load_poword():
+    try:
+        import poword
+    except ModuleNotFoundError as exc:
+        if exc.name != "poword":
+            raise
+        raise ModuleNotFoundError(
+            "Word处理功能依赖 poword，该功能仅支持安装了 Microsoft Word "
+            "和 poword 的 Windows 环境。"
+        ) from exc
+    return poword
 
 
 def docx2pdf(path: str, output_path: str = None):
@@ -32,6 +42,7 @@ def docx2pdf(path: str, output_path: str = None):
     """
     if output_path is None:
         output_path = path
+    poword = _load_poword()
     poword.docx2pdf(path=path, output_path=output_path)
 
 def merge4docx(input_path: str, output_path: str, new_word_name: str = 'merge4docx'):
@@ -47,6 +58,7 @@ def merge4docx(input_path: str, output_path: str, new_word_name: str = 'merge4do
     Returns:
         None
     """
+    poword = _load_poword()
     poword.merge4docx(input_path=input_path, output_path=output_path, new_word_name=new_word_name)
 
 
@@ -63,6 +75,7 @@ def doc2docx(input_path: str, output_path: str = r'./', output_name: str = None)
     Returns:
         None
     """
+    poword = _load_poword()
     poword.doc2docx(input_path=input_path, output_path=output_path, output_name=output_name)
 
 
@@ -79,6 +92,7 @@ def docx2doc(input_path: str, output_path: str = r'./', output_name: str = None)
     Returns:
         None
     """
+    poword = _load_poword()
     poword.docx2doc(input_path=input_path, output_path=output_path, output_name=output_name)
 
 def docx4imgs(word_path, img_path):
@@ -93,4 +107,5 @@ def docx4imgs(word_path, img_path):
     Returns:
         None
     """
+    poword = _load_poword()
     poword.docx4imgs(word_path=word_path, img_path=img_path)
diff --git a/tests/test_code/test_optional_imports.py b/tests/test_code/test_optional_imports.py
@@ -0,0 +1,169 @@
+"""Tests for optional platform-specific imports."""
+
+from contextlib import contextmanager
+import importlib
+import os
+import sys
+import tempfile
+import types
+import unittest
+from unittest import mock
+
+
+SUPPORTED_DEPENDENCIES = [
+    "poexcel",
+    "popdf",
+    "poimage",
+    "pofile",
+    "povideo",
+    "poocr",
+    "pomarkdown",
+    "wftools",
+    "pospider",
+]
+
+WINDOWS_ONLY_DEPENDENCIES = [
+    "poppt",
+    "poword",
+    "PyOfficeRobot",
+]
+
+MANAGED_MODULE_PREFIXES = (
+    "office",
+    "pocode",
+)
+
+WINDOWS_ONLY_LOADERS = [
+    (
+        "office.api.word",
+        "_load_poword",
+        "poword",
+        "win32com",
+        "Word处理功能依赖 poword",
+    ),
+    (
+        "office.api.ppt",
+        "_load_poppt",
+        "poppt",
+        "comtypes",
+        "PPT处理功能依赖 poppt",
+    ),
+    (
+        "office.api.wechat",
+        "_load_py_office_robot",
+        "PyOfficeRobot",
+        "uiautomation",
+        "微信自动化功能依赖 PyOfficeRobot",
+    ),
+]
+
+
+def _is_managed_module(name):
+    return any(name == prefix or name.startswith(f"{prefix}.") for prefix in MANAGED_MODULE_PREFIXES)
+
+
+class TestOptionalImports(unittest.TestCase):
+    """Check that Windows-only dependencies do not break package imports."""
+
+    @contextmanager
+    def _optional_import_test_environment(self):
+        module_names = (
+            SUPPORTED_DEPENDENCIES
+            + WINDOWS_ONLY_DEPENDENCIES
+            + ["pocode", "pocode.api", "pocode.api.color"]
+        )
+        original_modules = {
+            name: sys.modules.get(name)
+            for name in list(sys.modules)
+            if name in module_names or _is_managed_module(name)
+        }
+        original_home = os.environ.get("HOME")
+
+        try:
+            with tempfile.TemporaryDirectory() as temp_home:
+                mark_dir = os.path.join(temp_home, ".python-office")
+                os.makedirs(mark_dir)
+                with open(os.path.join(mark_dir, "first_run_mark"), "w", encoding="utf-8") as mark_file:
+                    mark_file.write("already checked")
+
+                os.environ["HOME"] = temp_home
+
+                for name in list(sys.modules):
+                    if _is_managed_module(name):
+                        sys.modules.pop(name, None)
+
+                for name in SUPPORTED_DEPENDENCIES:
+                    sys.modules[name] = types.ModuleType(name)
+
+                sys.modules["pocode"] = types.ModuleType("pocode")
+                sys.modules["pocode.api"] = types.ModuleType("pocode.api")
+                color_module = types.ModuleType("pocode.api.color")
+                color_module.random_color_print = lambda *args, **kwargs: None
+                sys.modules["pocode.api.color"] = color_module
+
+                for name in WINDOWS_ONLY_DEPENDENCIES:
+                    sys.modules.pop(name, None)
+
+                yield
+        finally:
+            if original_home is None:
+                os.environ.pop("HOME", None)
+            else:
+                os.environ["HOME"] = original_home
+
+            for name in list(sys.modules):
+                if name in module_names or _is_managed_module(name):
+                    sys.modules.pop(name, None)
+
+            for name, module in original_modules.items():
+                if module is not None:
+                    sys.modules[name] = module
+
+    def test_import_office_without_windows_only_dependencies(self):
+        with self._optional_import_test_environment():
+            importlib.import_module("office")
+
+    def test_loader_preserves_dependency_internal_import_errors(self):
+        with self._optional_import_test_environment():
+            importlib.import_module("office")
+            original_import = __import__
+
+            for module_name, loader_name, dependency_name, internal_name, message in WINDOWS_ONLY_LOADERS:
+                with self.subTest(dependency_name=dependency_name):
+                    api_module = importlib.import_module(module_name)
+                    loader = getattr(api_module, loader_name)
+
+                    def import_with_missing_internal_dependency(
+                        name, globals=None, locals=None, fromlist=(), level=0
+                    ):
+                        if name == dependency_name:
+                            raise ModuleNotFoundError(
+                                f"No module named '{internal_name}'",
+                                name=internal_name,
+                            )
+                        return original_import(name, globals, locals, fromlist, level)
+
+                    with mock.patch("builtins.__import__", side_effect=import_with_missing_internal_dependency):
+                        with self.assertRaises(ModuleNotFoundError) as error:
+                            loader()
+
+                    self.assertEqual(internal_name, error.exception.name)
+                    self.assertNotIn(message, str(error.exception))
+
+    def test_loader_reports_missing_windows_only_dependency(self):
+        with self._optional_import_test_environment():
+            importlib.import_module("office")
+
+            for module_name, loader_name, dependency_name, _, message in WINDOWS_ONLY_LOADERS:
+                with self.subTest(dependency_name=dependency_name):
+                    api_module = importlib.import_module(module_name)
+                    loader = getattr(api_module, loader_name)
+
+                    with self.assertRaises(ModuleNotFoundError) as error:
+                        loader()
+
+                    self.assertIn(message, str(error.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()
