Win32com backends reference¶

Module-level reference for the COM GUI backend implementations.

📦 Ribbon backend module¶

_ribbon ¶

RibbonProxy — MSO ribbon interaction via Application.CommandBars.

Provides a thin, thread-safe wrapper around the four key CommandBars.*Mso methods that cover the most common automation needs: executing a command, and querying its enabled / pressed / visible state.

All COM calls are guarded by wrap_com_error and assert_main_thread.

RibbonProxy ¶

RibbonProxy(app: ExcelAppLike)

Bases: AbstractRibbonBackend

Ribbon command execution and state queries via MSO identifiers.

Wraps Application.CommandBars methods to execute and inspect built-in Excel ribbon commands without navigating the UI manually.

Parameters:

Name	Type	Description	Default
`app`	`ExcelAppLike`	The active `ExcelApp` instance that owns this proxy.	required

Example

proxy = RibbonProxy(xl) proxy.execute("FileSave") proxy.is_enabled("FileSave") True

execute ¶

execute(mso_id: str) -> None

Execute a built-in ribbon command by its MSO identifier.

Calls Application.CommandBars.ExecuteMso(mso_id). Use this to trigger any standard Excel ribbon button programmatically.

Parameters:

Name	Type	Description	Default
`mso_id`	`str`	MSO control identifier string (e.g. `"FileSave"`, `"Copy"`, `"PasteValues"`).	required

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`GUIOperationError`	If the MSO ID is unknown or the command cannot be executed in the current application state.

Example

ribbon.execute("FileSave")

is_enabled ¶

is_enabled(mso_id: str) -> bool

Return whether a ribbon command is currently enabled.

Calls Application.CommandBars.GetEnabledMso(mso_id).

Parameters:

Name	Type	Description	Default
`mso_id`	`str`	MSO control identifier string.	required

Returns:

Name	Type	Description
`bool`	`bool`	`True` if the command is enabled; `False` otherwise.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`GUIOperationError`	If the MSO ID is unknown or the query fails.

Example

ribbon.is_enabled("FileSave") True

is_pressed ¶

is_pressed(mso_id: str) -> bool

Return whether a ribbon toggle command is currently pressed.

Calls Application.CommandBars.GetPressedMso(mso_id).

Parameters:

Name	Type	Description	Default
`mso_id`	`str`	MSO control identifier string.	required

Returns:

Name	Type	Description
`bool`	`bool`	`True` if the toggle command is in the pressed/active state; `False` if not pressed or if the control does not support the pressed-state query (e.g. regular buttons such as `"FileSave"` always return `False`).

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.

Example

ribbon.is_pressed("Bold") False

is_visible ¶

is_visible(mso_id: str) -> bool

Return whether a ribbon command is currently visible.

Calls Application.CommandBars.GetVisibleMso(mso_id).

Parameters:

Name	Type	Description	Default
`mso_id`	`str`	MSO control identifier string.	required

Returns:

Name	Type	Description
`bool`	`bool`	`True` if the command is visible in the current ribbon state; `False` otherwise.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`GUIOperationError`	If the MSO ID is unknown or the query fails.

Example

ribbon.is_visible("FileSave") True

_menu ¶

MenuProxy — legacy CommandBar interaction via Application.CommandBars.

Provides access to Excel's classic CommandBar (pre-ribbon) menu system. Supports traversing named bars by a sequence of control captions and executing the terminal control.

All COM calls are guarded by wrap_com_error and assert_main_thread.

Note

CommandBars are a legacy API. Many bars are hidden or non-functional in modern Excel (2013+). Prefer RibbonProxy.execute for built-in commands. Use MenuProxy only when a specific add-in or legacy toolbar must be driven.

MenuProxy ¶

MenuProxy(app: ExcelAppLike)

Bases: AbstractMenuBackend

Legacy CommandBar menu traversal and control execution.

Allows navigating an Excel CommandBar by name and executing controls by their caption path. Also exposes discovery helpers to list all available bars and the top-level controls of any given bar.

Parameters:

Name	Type	Description	Default
`app`	`ExcelAppLike`	The active `ExcelApp` instance that owns this proxy.	required

Example

proxy = MenuProxy(xl) proxy.list_bars() ['Standard', 'Formatting', ...] proxy.click("Standard", "Open")

click ¶

click(bar_name: str, *item_path: str) -> None

Traverse a CommandBar by caption path and execute the final control.

Looks up the CommandBar named bar_name, then iterates through item_path — each element being the caption of a nested control — descending into sub-controls at each step. Calls .Execute() on the control identified by the last element.

Parameters:

Name	Type	Description	Default
`bar_name`	`str`	The name of the CommandBar to start from (e.g. `"Standard"`).	required
`*item_path`	`str`	One or more control captions forming the path to the target control. At least one caption is required.	`()`

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`GUIOperationError`	If the bar, any intermediate control, or the final control cannot be found, or if `Execute` fails.

Example

menu.click("Standard", "Open") menu.click("Tools", "Macros", "Visual Basic Editor")

list_bars ¶

list_bars() -> list[str]

Return the names of all CommandBars registered with Excel.

Iterates the Application.CommandBars collection and collects each bar's .Name attribute. Bars with no name are skipped.

Returns:

Type	Description
`list[str]`	list[str]: Sorted list of CommandBar names.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`GUIOperationError`	If the COM collection cannot be iterated.

Example

menu.list_bars() ['3-D Settings', 'Borders', 'Cell', ...]

list_controls ¶

list_controls(bar_name: str) -> list[str]

Return the captions of all top-level controls in a CommandBar.

Iterates the .Controls collection of the named bar. Controls that have no Caption (e.g. separator lines) are skipped.

Parameters:

Name	Type	Description	Default
`bar_name`	`str`	The name of the CommandBar to inspect.	required

Returns:

Type	Description
`list[str]`	list[str]: Captions of the bar's top-level controls, in order.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`GUIOperationError`	If the bar cannot be found or the controls collection cannot be iterated.

Example

menu.list_controls("Standard") ['New', 'Open', 'Save', ...]

📦 Dialog backend module¶

_dialog ¶

DialogProxy — native Excel dialog helpers via Application COM methods.

Exposes three dialog types:

get_file_open — Application.GetOpenFilename; returns the user-selected path or None on cancel.
get_file_save — Application.GetSaveAsFilename; returns the user-selected path or None on cancel.
alert — a modal message box. Primary implementation uses ctypes.windll.user32.MessageBoxW to avoid requiring a running VBA environment. Falls back gracefully if ctypes is unavailable.

All COM calls are guarded by wrap_com_error and assert_main_thread.

DialogProxy ¶

DialogProxy(app: ExcelAppLike)

Bases: AbstractDialogBackend

File and message dialog helpers backed by Excel COM and Win32.

Provides a clean Python interface for the three most common GUI dialogs needed during Excel automation: open-file picker, save-file picker, and a simple information alert.

Parameters:

Name	Type	Description	Default
`app`	`ExcelAppLike`	The active `ExcelApp` instance that owns this proxy.	required

Example

proxy = DialogProxy(xl) path = proxy.get_file_open(title="Select a report") if path: ... wb = xl.open(path)

get_file_open ¶

get_file_open(title: str = 'Open', initial_dir: str | None = None, filter: str = 'Excel Files (*.xls*), *.xls*') -> str | None

Show Excel's built-in Open file picker dialog.

Calls Application.GetOpenFilename. The dialog is modal; this method blocks until the user confirms or cancels.

Parameters:

Name	Type	Description	Default
`title`	`str`	Dialog title bar text. Defaults to `"Open"`.	`'Open'`
`initial_dir`	`str \| None`	Directory to open the dialog in. If `None`, Excel uses its current working directory.	`None`
`filter`	`str`	File-type filter string in Excel's two-part format: `"<description>, <wildcard>"`. Defaults to Excel files.	`'Excel Files (.xls), .xls'`

Returns:

Type	Description
`str \| None`	str \| None: Absolute path chosen by the user, or `None` if the dialog was cancelled.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`GUIOperationError`	If the COM call fails.

Example

path = dialog.get_file_open(title="Pick a workbook") if path is not None: ... xl.open(path)

get_file_save ¶

get_file_save(title: str = 'Save As', initial_dir: str | None = None, filter: str = 'Excel Files (*.xlsx), *.xlsx') -> str | None

Show Excel's built-in Save As file picker dialog.

Calls Application.GetSaveAsFilename. The dialog is modal; this method blocks until the user confirms or cancels.

Parameters:

Name	Type	Description	Default
`title`	`str`	Dialog title bar text. Defaults to `"Save As"`.	`'Save As'`
`initial_dir`	`str \| None`	Directory to open the dialog in. If `None`, Excel uses its current working directory.	`None`
`filter`	`str`	File-type filter string in Excel's two-part format: `"<description>, <wildcard>"`. Defaults to `.xlsx`.	`'Excel Files (.xlsx), .xlsx'`

Returns:

Type	Description
`str \| None`	str \| None: Absolute path chosen by the user, or `None` if the dialog was cancelled.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`GUIOperationError`	If the COM call fails.

Example

path = dialog.get_file_save(title="Save report as") if path is not None: ... wb.save_as(path)

alert ¶

alert(message: str, title: str = 'EzXl') -> None

Display a modal information message box.

Uses ctypes.windll.user32.MessageBoxW (Win32 API) directly. This approach avoids any dependency on a running VBA environment and does not require Excel to have a document open.

The dialog shows a single OK button with an information icon. This method blocks until the user dismisses the dialog.

Parameters:

Name	Type	Description	Default
`message`	`str`	The body text displayed in the message box.	required
`title`	`str`	Caption for the message box title bar. Defaults to `"EzXl"`.	`'EzXl'`

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`GUIOperationError`	If the Win32 MessageBoxW call fails.

Example

dialog.alert("Export complete.", title="Success")

📦 Backstage backend module¶

_backstage ¶

COMBackstageBackend — Excel Backstage file operations via COM.

Implements :class:~ezxl.gui._protocols.AbstractBackstageFileOps using the Excel COM object model. COM calls are direct and focus-independent — no keyboard sequences or window handles are required.

Advantages over the pywinauto backend¶

No focus requirement: COM calls work regardless of which window is active.
Locale-independent: COM APIs are language-neutral.
No external dependency: uses only win32com.client (already required).

Limitations¶

open_options is provided as a convenience method but is not part of the :class:~ezxl.gui._protocols.AbstractBackstageFileOps contract. It may fail in restricted environments (e.g. during a macro run or when the ribbon is disabled). The preferred implementation for open_options is :class:~ezxl.gui.pywinauto.PywinautoBackstageBackend via :class:~ezxl.gui._protocols.AbstractBackstageNavigator.
save_as with path=None shows the built-in Excel Save As dialog (xlDialogSaveAs). The dialog blocks until the user dismisses it.
close_workbook raises :exc:~ezxl.exceptions.WorkbookNotFoundError if no workbook is currently open.

All COM calls are guarded by :func:~ezxl.utils._com_utils.wrap_com_error and :func:~ezxl.utils._com_utils.assert_main_thread.

COMBackstageBackend ¶

COMBackstageBackend(app: ExcelAppLike)

Bases: AbstractBackstageFileOps

Excel Backstage file operations via the COM object model.

Implements :class:~ezxl.gui._protocols.AbstractBackstageFileOps using Excel's COM API. All operations are focus-independent and locale-independent.

This is the default backstage backend for :class:~ezxl.gui.GUIProxy. For UIA-based Backstage navigation (Options panel, visual panel opening), inject a :class:~ezxl.gui.pywinauto.PywinautoBackstageBackend as the backstage_nav argument::

gui = GUIProxy(
    xl,
    backstage=COMBackstageBackend(xl),
    backstage_nav=PywinautoBackstageBackend(hwnd=xl.hwnd, locale="fr"),
)

Parameters:

Name	Type	Description	Default
`app`	`ExcelAppLike`	The active `ExcelApp` instance that owns this backend.	required

Example

backend = COMBackstageBackend(xl) backend.save() backend.save_as(path="C:\Reports\output.xlsx") backend.open_file() backend.close_workbook()

save ¶

save() -> None

Save the active workbook via ActiveWorkbook.Save().

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`WorkbookNotFoundError`	If no workbook is currently open.
`COMOperationError`	If the COM call fails.

Example

backend.save()

save_as ¶

save_as(path: str | None = None) -> None

Save the active workbook under a new path, or show the Save As dialog.

If path is provided, calls ActiveWorkbook.SaveAs(Filename=path) directly — no dialog is shown. If path is None, opens the built-in Excel Save As dialog (xlDialogSaveAs), which blocks until the user dismisses it.

Parameters:

Name	Type	Description	Default
`path`	`str \| None`	Absolute path for the new file. If `None`, the built-in dialog is displayed for manual path selection.	`None`

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`WorkbookNotFoundError`	If no workbook is currently open.
`COMOperationError`	If the COM call fails.

Example

backend.save_as() # opens dialog backend.save_as(path="C:\output.xlsx") # direct save

open_file ¶

open_file() -> None

Show the built-in Excel Open dialog (xlDialogOpen).

The dialog blocks until the user selects a file or cancels.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`COMOperationError`	If the COM call fails.

Example

backend.open_file()

close_workbook ¶

close_workbook() -> None

Close the active workbook without saving (SaveChanges=False).

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`WorkbookNotFoundError`	If no workbook is currently open.
`COMOperationError`	If the COM call fails.

Example

backend.close_workbook()

open_options ¶

open_options() -> None

Open the Excel Options dialog via CommandBars.ExecuteMso.

This method is not part of :class:AbstractBackstageFileOps. It is provided as a convenience fallback when :class:~ezxl.gui.pywinauto.PywinautoBackstageBackend (the preferred implementation via :class:AbstractBackstageNavigator) is unavailable.

Uses the "ApplicationOptionsDialog" MSO identifier. This may fail in restricted environments (e.g. when a macro is running or the ribbon is disabled).

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`GUIOperationError`	If the Options dialog cannot be opened via COM.

Example

backend.open_options()

Win32com backends reference¶

📦 Ribbon backend module¶

_ribbon ¶

RibbonProxy ¶

execute ¶

is_enabled ¶

is_pressed ¶

is_visible ¶

📦 Menu backend module¶

_menu ¶

MenuProxy ¶

click ¶

list_bars ¶

list_controls ¶

📦 Dialog backend module¶

_dialog ¶

DialogProxy ¶

get_file_open ¶

get_file_save ¶

alert ¶

📦 Backstage backend module¶

_backstage ¶

Advantages over the pywinauto backend¶

Limitations¶

COMBackstageBackend ¶

save ¶

save_as ¶

open_file ¶

close_workbook ¶

open_options ¶