Coverage for src / ezxl / __init__.py: 62%

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

2# EzXl - Main Module 

3# Project: EzXl 

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

5 

6"""EzXl — Generic Excel automation library via COM and openpyxl. 

7 

8Provides a clean Python interface for: 

9 

10- Opening and closing Excel files via COM (``ExcelApp``, ``WorkbookProxy``) 

11- Attaching to an already-running Excel instance 

12- Navigating worksheets and manipulating cells/ranges (``SheetProxy``, 

13 ``CellProxy``, ``RangeProxy``) 

14- Converting between file formats without a live Excel process 

15 (``read_excel``, ``read_csv``, ``xlsx_to_csv``, ``csv_to_xlsx``, 

16 ``read_sheet``) 

17- Formatting closed workbook files via openpyxl (``ExcelFormatter``) 

18 

19Requires Python 3.11+ and a 64-bit Excel installation for COM features. 

20Format conversion and closed-file formatting work without Excel installed. 

21""" 

22 

23from __future__ import annotations 

24 

25# /////////////////////////////////////////////////////////////// 

26# IMPORTS 

27# /////////////////////////////////////////////////////////////// 

28# Standard library imports 

29import sys 

30 

31# Local imports 

32from .version import __version__ 

33 

34# /////////////////////////////////////////////////////////////// 

35# METADATA INFORMATION 

36# /////////////////////////////////////////////////////////////// 

37 

38__author__ = "Neuraaak" 

39__maintainer__ = "Neuraaak" 

40__description__ = "EzXl — Generic Excel automation library via COM and openpyxl" 

41__python_requires__ = ">=3.11" 

42__keywords__ = [ 

43 "excel", 

44 "automation", 

45 "com", 

46 "openpyxl", 

47 "xlsx", 

48 "win32com", 

49 "spreadsheet", 

50 "office", 

51] 

52__url__ = "https://github.com/neuraaak/EzXl" 

53__repository__ = "https://github.com/neuraaak/EzXl" 

54 

55# /////////////////////////////////////////////////////////////// 

56# PYTHON VERSION CHECK 

57# /////////////////////////////////////////////////////////////// 

58 

59if sys.version_info < (3, 11): # noqa: UP036 

60 raise RuntimeError( 

61 f"EzXl {__version__} requires Python 3.11 or higher. " 

62 f"Current version: {sys.version}" 

63 ) 

64 

65# /////////////////////////////////////////////////////////////// 

66# PUBLIC API — cross-platform (pure Python, no COM) 

67# /////////////////////////////////////////////////////////////// 

68 

69from .exceptions import ( 

70 COMOperationError, 

71 ExcelNotAvailableError, 

72 ExcelSessionLostError, 

73 ExcelThreadViolationError, 

74 EzXlError, 

75 FormatterError, 

76 GUIOperationError, 

77 SheetNotFoundError, 

78 WorkbookNotFoundError, 

79) 

80from .gui._protocols import ( 

81 AbstractBackstageBackend, 

82 AbstractBackstageFileOps, 

83 AbstractBackstageNavigator, 

84 AbstractDialogBackend, 

85 AbstractKeysBackend, 

86 AbstractMenuBackend, 

87 AbstractRibbonBackend, 

88) 

89from .io._converters import csv_to_xlsx, read_csv, read_excel, read_sheet, xlsx_to_csv 

90from .io._formatters import ExcelFormatter 

91 

92# /////////////////////////////////////////////////////////////// 

93# PUBLIC API — Windows only (COM / win32com / pywinauto) 

94# /////////////////////////////////////////////////////////////// 

95 

96if sys.platform == "win32": 

97 from .core._excel_app import ExcelApp 

98 from .core._sheet import CellProxy, RangeProxy, SheetProxy 

99 from .core._workbook import WorkbookProxy 

100 from .gui._gui_proxy import GUIProxy 

101 from .gui.pywinauto import ( 

102 PywinautoBackstageBackend, 

103 PywinautoKeysBackend, 

104 ) 

105 from .gui.win32com._backstage import COMBackstageBackend 

106 from .gui.win32com._dialog import DialogProxy 

107 from .gui.win32com._menu import MenuProxy 

108 from .gui.win32com._ribbon import RibbonProxy 

109 

110 

111__all__ = [ 

112 # Exceptions 

113 "EzXlError", 

114 "ExcelNotAvailableError", 

115 "ExcelSessionLostError", 

116 "ExcelThreadViolationError", 

117 "WorkbookNotFoundError", 

118 "SheetNotFoundError", 

119 "COMOperationError", 

120 "FormatterError", 

121 "GUIOperationError", 

122 # GUI protocols (cross-platform ABCs) 

123 "AbstractRibbonBackend", 

124 "AbstractMenuBackend", 

125 "AbstractDialogBackend", 

126 "AbstractKeysBackend", 

127 "AbstractBackstageFileOps", 

128 "AbstractBackstageNavigator", 

129 # Compatibility alias — kept for existing imports 

130 "AbstractBackstageBackend", 

131 # Closed-file utilities 

132 "ExcelFormatter", 

133 "read_excel", 

134 "read_csv", 

135 "xlsx_to_csv", 

136 "csv_to_xlsx", 

137 "read_sheet", 

138] 

139 

140if sys.platform == "win32": 

141 __all__ += [ 

142 # COM automation 

143 "ExcelApp", 

144 "WorkbookProxy", 

145 "SheetProxy", 

146 "CellProxy", 

147 "RangeProxy", 

148 # GUI interaction 

149 "GUIProxy", 

150 "COMBackstageBackend", 

151 "RibbonProxy", 

152 "MenuProxy", 

153 "DialogProxy", 

154 # GUI — pywinauto backends 

155 "PywinautoKeysBackend", 

156 "PywinautoBackstageBackend", 

157 ]