Coverage for src / ezxl / gui / __init__.py: 56%

1# /////////////////////////////////////////////////////////////// 

2# gui - GUI-level Excel interaction subpackage 

3# Project: EzXl 

4# /////////////////////////////////////////////////////////////// 

5 

6""" 

7EzXl GUI subpackage — ribbon, menu, dialog, and key automation via COM. 

8 

9Provides ``GUIProxy`` as the single entry point, accessible through 

10``ExcelApp.gui``. The proxy bundles six interaction surfaces: 

11 

12- ``GUIProxy.ribbon`` — MSO ribbon command execution and state queries. 

13- ``GUIProxy.menu`` — Legacy CommandBar traversal and control execution. 

14- ``GUIProxy.dialog`` — File-open, file-save, and message-box dialogs. 

15- ``GUIProxy.send_keys(keys)`` — Direct ``Application.SendKeys`` pass-through. 

16- ``GUIProxy.backstage`` — File operations via COM (save, save_as, open_file, 

17 close_workbook). Default: :class:`~ezxl.gui.win32com.COMBackstageBackend`. 

18- ``GUIProxy.backstage_nav`` — UIA Backstage navigation (open_options, 

19 open_save_as_panel). Defaults to ``None``; inject a 

20 :class:`~ezxl.gui.pywinauto.PywinautoBackstageBackend` explicitly. 

21 

22All COM calls are wrapped via ``wrap_com_error``. Thread identity is asserted 

23on every public method call using ``assert_main_thread``. 

24 

25Typical usage:: 

26 

27 with ExcelApp(mode="attach") as xl: 

28 xl.gui.ribbon.execute("FileSave") 

29 path = xl.gui.dialog.get_file_open() 

30 xl.gui.backstage.save_as(path="C:\\\\output.xlsx") 

31 

32With UIA navigator:: 

33 

34 gui = GUIProxy( 

35 xl, 

36 backstage_nav=PywinautoBackstageBackend(hwnd=xl.hwnd, locale="fr"), 

37 ) 

38 gui.backstage_nav.open_options() 

39""" 

40 

41from __future__ import annotations 

42 

43# /////////////////////////////////////////////////////////////// 

44# IMPORTS 

45# /////////////////////////////////////////////////////////////// 

46# Standard library imports 

47import sys 

48 

49# Local imports — cross-platform (pure Python ABCs) 

50from ._protocols import ( 

51 AbstractBackstageBackend, 

52 AbstractBackstageFileOps, 

53 AbstractBackstageNavigator, 

54 AbstractDialogBackend, 

55 AbstractKeysBackend, 

56 AbstractMenuBackend, 

57 AbstractRibbonBackend, 

58) 

59 

60__all__ = [ 

61 "AbstractRibbonBackend", 

62 "AbstractMenuBackend", 

63 "AbstractDialogBackend", 

64 "AbstractKeysBackend", 

65 # Backstage protocols 

66 "AbstractBackstageFileOps", 

67 "AbstractBackstageNavigator", 

68 # Compatibility alias — kept for existing imports 

69 "AbstractBackstageBackend", 

70] 

71 

72# Local imports — Windows only (COM / pywinauto) 

73if sys.platform == "win32": 

74 from ._gui_proxy import GUIProxy 

75 from .pywinauto import ( 

76 PywinautoBackstageBackend, 

77 PywinautoKeysBackend, 

78 ) 

79 from .win32com import COMBackstageBackend, DialogProxy, MenuProxy, RibbonProxy 

80 

81 __all__ += [ 

82 "GUIProxy", 

83 "COMBackstageBackend", 

84 "RibbonProxy", 

85 "MenuProxy", 

86 "DialogProxy", 

87 "PywinautoKeysBackend", 

88 "PywinautoBackstageBackend", 

89 ]