Full API reference¶

This page renders the full public API from the top-level ezxl package via mkdocstrings.

🔍 Top-level package¶

ezxl ¶

EzXl — Generic Excel automation library via COM and openpyxl.

Provides a clean Python interface for:

Opening and closing Excel files via COM (ExcelApp, WorkbookProxy)
Attaching to an already-running Excel instance
Navigating worksheets and manipulating cells/ranges (SheetProxy, CellProxy, RangeProxy)
Converting between file formats without a live Excel process (read_excel, read_csv, xlsx_to_csv, csv_to_xlsx, read_sheet)
Formatting closed workbook files via openpyxl (ExcelFormatter)

Requires Python 3.11+ and a 64-bit Excel installation for COM features. Format conversion and closed-file formatting work without Excel installed.

COMOperationError ¶

COMOperationError(message: str, cause: BaseException | None = None)

Bases: EzXlError

Raised for unclassified COM errors that do not map to a specific subclass.

This is the catch-all wrapper for pywintypes.com_error exceptions. If a COM error can be identified as a lost session or unavailability issue, the more specific subclass should be used instead.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the error.	required
`cause`	`BaseException \| None`	Original exception that triggered this error, if any.	`None`

ExcelNotAvailableError ¶

ExcelNotAvailableError(message: str, cause: BaseException | None = None)

Bases: EzXlError

Raised when Excel is not open or the COM server is unreachable.

Typically thrown when win32com.client.Dispatch or win32com.client.GetActiveObject fails because no Excel process is running, or because the COM registration is broken.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the error.	required
`cause`	`BaseException \| None`	Original exception that triggered this error, if any.	`None`

Example

raise ExcelNotAvailableError( ... "No running Excel instance found", cause=original_err ... )

ExcelSessionLostError ¶

ExcelSessionLostError(message: str, cause: BaseException | None = None)

Bases: EzXlError

Raised when an established COM connection is lost mid-operation.

This can happen when the user closes Excel while an automation session is active, or when Excel crashes. Unlike ExcelNotAvailableError, this implies a previously valid connection existed.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the error.	required
`cause`	`BaseException \| None`	Original exception that triggered this error, if any.	`None`

ExcelThreadViolationError ¶

ExcelThreadViolationError(message: str, cause: BaseException | None = None)

Bases: EzXlError

Raised when a COM call is attempted from the wrong thread.

Excel COM operates under the Single-Threaded Apartment (STA) model. All COM calls must originate from the thread that created the ExcelApp instance. This exception is raised proactively before the COM call reaches the dispatcher to give a clear diagnostic.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the error.	required
`cause`	`BaseException \| None`	Original exception that triggered this error, if any.	`None`

EzXlError ¶

EzXlError(message: str, cause: BaseException | None = None)

Bases: Exception

Base exception for all EzXl errors.

All exceptions raised by the EzXl library inherit from this class. Catching EzXlError is sufficient to handle any EzXl-originated failure without importing subclasses.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the error.	required
`cause`	`BaseException \| None`	Original exception that triggered this error, if any.	`None`

Example

try: ... raise EzXlError("something went wrong") ... except EzXlError as e: ... print(e) something went wrong

FormatterError ¶

FormatterError(message: str, cause: BaseException | None = None)

Bases: EzXlError

Raised when an openpyxl-based formatting operation fails.

This exception covers errors that occur during closed-file formatting via ExcelFormatter, such as invalid cell references, unsupported style properties, or file I/O failures.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the error.	required
`cause`	`BaseException \| None`	Original exception that triggered this error, if any.	`None`

GUIOperationError ¶

GUIOperationError(message: str, cause: BaseException | None = None)

Bases: EzXlError

Raised when a GUI-level COM operation fails for ribbon, menu, or dialog.

Distinct from COMOperationError to allow consumer code to differentiate between generic COM failures and failures that occur specifically within GUI interaction surfaces (ribbon, CommandBars, file dialogs, message boxes).

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the error.	required
`cause`	`BaseException \| None`	Original exception that triggered this error, if any.	`None`

Example

raise GUIOperationError( ... "Failed to execute ribbon command 'FileSave'", cause=exc ... )

SheetNotFoundError ¶

SheetNotFoundError(message: str, cause: BaseException | None = None)

Bases: EzXlError

Raised when a worksheet cannot be found by name in a workbook.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the error.	required
`cause`	`BaseException \| None`	Original exception that triggered this error, if any.	`None`

Example

raise SheetNotFoundError("No sheet named 'Summary' in 'report.xlsx'")

WorkbookNotFoundError ¶

WorkbookNotFoundError(message: str, cause: BaseException | None = None)

Bases: EzXlError

Raised when a workbook cannot be found by name in the Excel session.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the error.	required
`cause`	`BaseException \| None`	Original exception that triggered this error, if any.	`None`

Example

raise WorkbookNotFoundError("No workbook named 'report.xlsx'")

AbstractBackstageFileOps ¶

Bases: ABC

Contract for Excel Backstage file operations via COM.

Covers the four operations that the COM object model executes reliably, focus-independently, and locale-independently: save, save_as, open_file, and close_workbook.

This contract is implemented by :class:~ezxl.gui.win32com.COMBackstageBackend. Inject it into :class:~ezxl.gui.GUIProxy via the backstage parameter::

gui = GUIProxy(xl, backstage=COMBackstageBackend(xl))

save `abstractmethod` ¶

save() -> None

Save the active workbook.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`WorkbookNotFoundError`	If no workbook is currently open.
`GUIOperationError`	If the action cannot be completed.

save_as `abstractmethod` ¶

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

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

Parameters:

Name	Type	Description	Default
`path`	`str \| None`	Absolute path for the new file, including extension. If `None`, the built-in Save As 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.
`GUIOperationError`	If the panel cannot be opened or path entry fails.

open_file `abstractmethod` ¶

open_file() -> None

Show the built-in Excel Open dialog.

Raises:

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

close_workbook `abstractmethod` ¶

close_workbook() -> None

Close the active workbook without saving.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`WorkbookNotFoundError`	If no workbook is currently open.
`GUIOperationError`	If the action cannot be completed.

AbstractBackstageNavigator ¶

Bases: ABC

Contract for Excel Backstage visual navigation via UI Automation.

Covers operations that require UIA-level interaction with the Backstage overlay: navigating to the Options panel, opening the Save As panel without confirming, and UIA-driven open/close actions.

This contract is implemented by :class:~ezxl.gui.pywinauto.PywinautoBackstageBackend. Inject it into :class:~ezxl.gui.GUIProxy via the backstage_nav parameter::

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

Note

backstage_nav is optional — :class:~ezxl.gui.GUIProxy defaults it to None. Access it via xl.gui.backstage_nav; guard with an is not None check before calling if it may be absent.

open_options `abstractmethod` ¶

open_options() -> None

Navigate to the Excel Options panel via the Backstage.

Raises:

Type	Description
`GUIOperationError`	If the Options panel cannot be reached.

open_save_as_panel `abstractmethod` ¶

open_save_as_panel() -> None

Open the Save As panel in the Backstage without confirming a save.

Clicks the "Enregistrer sous" (or locale equivalent) ListItem and leaves the panel open for manual interaction.

Raises:

Type	Description
`GUIOperationError`	If the panel cannot be reached.

open_file `abstractmethod` ¶

open_file() -> None

Open the Open panel via the Backstage.

Raises:

Type	Description
`GUIOperationError`	If the panel cannot be reached.

close_workbook `abstractmethod` ¶

close_workbook() -> None

Close the active workbook via a Backstage UIA click.

Raises:

Type	Description
`GUIOperationError`	If the action cannot be completed.

AbstractDialogBackend ¶

Bases: ABC

Contract for file-open, file-save, and message-box dialogs.

Any class that implements this interface can be injected into :class:~ezxl.gui.GUIProxy as the dialog backend, replacing the default COM/Win32-based implementation.

Default parameter values in implementing methods must match those declared on :class:~ezxl.gui.DialogProxy.

get_file_open `abstractmethod` ¶

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

Show a file-open picker dialog and return the selected path.

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`, the backend chooses the initial directory.	`None`
`filter`	`str`	File-type filter string. 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 underlying call fails.

get_file_save `abstractmethod` ¶

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

Show a file-save picker dialog and return the selected path.

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`, the backend chooses the initial directory.	`None`
`filter`	`str`	File-type filter string. 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 underlying call fails.

alert `abstractmethod` ¶

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

Display a modal information message box.

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 underlying call fails.

AbstractKeysBackend ¶

Bases: ABC

Contract for keystroke injection into Excel.

Any class that implements this interface can be injected into :class:~ezxl.gui.GUIProxy as the keys backend, replacing the default COM-based implementation.

send_keys `abstractmethod` ¶

send_keys(keys: str, wait: bool = True) -> None

Send a keystroke sequence to the Excel Application window.

Parameters:

Name	Type	Description	Default
`keys`	`str`	Keystroke string in VBA SendKeys notation (e.g. `"{ENTER}"`, `"^s"` for Ctrl+S).	required
`wait`	`bool`	If `True`, block until Excel processes the keystrokes before returning. Defaults to `True`.	`True`

Raises:

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

AbstractMenuBackend ¶

Bases: ABC

Contract for legacy CommandBar traversal and control execution.

Any class that implements this interface can be injected into :class:~ezxl.gui.GUIProxy as the menu backend, replacing the default COM-based implementation.

click `abstractmethod` ¶

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

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

Parameters:

Name	Type	Description	Default
`bar_name`	`str`	The name of the CommandBar to start from.	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 execution fails.

list_bars `abstractmethod` ¶

list_bars() -> list[str]

Return the names of all CommandBars registered with Excel.

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.

list_controls `abstractmethod` ¶

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

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

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.

AbstractRibbonBackend ¶

Bases: ABC

Contract for ribbon command execution and state queries.

Any class that implements this interface can be injected into :class:~ezxl.gui.GUIProxy as the ribbon backend, replacing the default COM-based implementation.

Implementations are responsible for thread-safety; the caller (:class:~ezxl.gui.GUIProxy) does not perform additional thread checks.

execute `abstractmethod` ¶

execute(mso_id: str) -> None

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

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.

is_enabled `abstractmethod` ¶

is_enabled(mso_id: str) -> bool

Return whether a ribbon command is currently enabled.

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.

is_pressed `abstractmethod` ¶

is_pressed(mso_id: str) -> bool

Return whether a ribbon toggle command is currently pressed.

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.

Raises:

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

is_visible `abstractmethod` ¶

is_visible(mso_id: str) -> bool

Return whether a ribbon command is currently visible.

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.

ExcelFormatter ¶

ExcelFormatter(path: str | Path)

Fluent formatter for closed Excel workbook files.

All formatting operations are buffered and applied in a single write pass when save() is called. The workbook is opened with openpyxl only at save time, minimising I/O overhead.

The API is intentionally flat: no sheet selector is exposed here. The formatter operates on the active sheet of the workbook. Consumer libraries that need multi-sheet formatting should instantiate one ExcelFormatter per sheet operation.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to an existing `.xlsx` workbook file.	required

Raises:

Type	Description
`FileNotFoundError`	If `path` does not exist.
`ImportError`	If openpyxl is not installed.

Example

( ... ExcelFormatter("report.xlsx") ... .column_width("A", 20) ... .font("A1", bold=True, size=14, color="FFFFFF") ... .fill("A1", "4F81BD") ... .save() ... )

column_width ¶

column_width(col: str, width: float) -> ExcelFormatter

Set the width of a column.

Parameters:

Name	Type	Description	Default
`col`	`str`	Column letter (e.g. `"A"`, `"BC"`).	required
`width`	`float`	Column width in Excel character units.	required

Returns:

Name	Type	Description
`ExcelFormatter`	`ExcelFormatter`	`self` for method chaining.

Example

formatter.column_width("A", 20).column_width("B", 15)

row_height ¶

row_height(row: int, height: float) -> ExcelFormatter

Set the height of a row.

Parameters:

Name	Type	Description	Default
`row`	`int`	1-based row index.	required
`height`	`float`	Row height in points.	required

Returns:

Name	Type	Description
`ExcelFormatter`	`ExcelFormatter`	`self` for method chaining.

Example

formatter.row_height(1, 30)

font ¶

font(ref: str, *, bold: bool = False, italic: bool = False, size: int | None = None, color: str | None = None) -> ExcelFormatter

Apply font formatting to a cell or range.

Parameters:

Name	Type	Description	Default
`ref`	`str`	Cell or range address in A1 notation (e.g. `"A1"` or `"A1:D1"`).	required
`bold`	`bool`	Apply bold weight. Defaults to `False`.	`False`
`italic`	`bool`	Apply italic style. Defaults to `False`.	`False`
`size`	`int \| None`	Font size in points. `None` leaves the size unchanged.	`None`
`color`	`str \| None`	Font colour as a 6-character hex string without `#` (e.g. `"FF0000"` for red). `None` leaves colour unchanged.	`None`

Returns:

Name	Type	Description
`ExcelFormatter`	`ExcelFormatter`	`self` for method chaining.

Example

formatter.font("A1", bold=True, size=12, color="FF0000")

fill ¶

fill(ref: str, color: str) -> ExcelFormatter

Apply a solid background fill to a cell or range.

Parameters:

Name	Type	Description	Default
`ref`	`str`	Cell or range address in A1 notation.	required
`color`	`str`	Background colour as a 6-character hex string without `#` (e.g. `"4F81BD"` for a medium blue).	required

Returns:

Name	Type	Description
`ExcelFormatter`	`ExcelFormatter`	`self` for method chaining.

Example

formatter.fill("A1:D1", "4F81BD")

border ¶

border(ref: str, style: str = 'thin') -> ExcelFormatter

Apply a border to all edges of a cell or range.

Parameters:

Name	Type	Description	Default
`ref`	`str`	Cell or range address in A1 notation.	required
`style`	`str`	Border style name as understood by openpyxl (e.g. `"thin"`, `"medium"`, `"thick"`, `"dashed"`). Defaults to `"thin"`.	`'thin'`

Returns:

Name	Type	Description
`ExcelFormatter`	`ExcelFormatter`	`self` for method chaining.

Example

formatter.border("A1:D5", style="thin")

align ¶

align(ref: str, *, horizontal: str | None = None, vertical: str | None = None, wrap: bool = False) -> ExcelFormatter

Apply alignment to a cell or range.

Parameters:

Name	Type	Description	Default
`ref`	`str`	Cell or range address in A1 notation.	required
`horizontal`	`str \| None`	Horizontal alignment. Accepted values: `"left"`, `"center"`, `"right"`, `"fill"`, `"justify"`, `"centerContinuous"`, `"distributed"`. `None` leaves the setting unchanged.	`None`
`vertical`	`str \| None`	Vertical alignment. Accepted values: `"top"`, `"center"`, `"bottom"`, `"justify"`, `"distributed"`. `None` leaves the setting unchanged.	`None`
`wrap`	`bool`	Enable text wrapping. Defaults to `False`.	`False`

Returns:

Name	Type	Description
`ExcelFormatter`	`ExcelFormatter`	`self` for method chaining.

Example

formatter.align("A1", horizontal="center", vertical="top", wrap=True)

save ¶

save(dest: str | Path | None = None) -> None

Apply all buffered operations and write the workbook.

Parameters:

Name	Type	Description	Default
`dest`	`str \| Path \| None`	Destination path. Pass `None` to overwrite the source file in place. Parent directories of `dest` must exist.	`None`

Raises:

Type	Description
`FormatterError`	If any openpyxl operation fails.
`ImportError`	If openpyxl is not installed.

Example

formatter.save() # overwrite source formatter.save("output/report.xlsx") # write to new path

ExcelApp ¶

ExcelApp(mode: Literal['dispatch', 'attach'] = 'dispatch', visible: bool = True)

COM automation session for a single Excel Application instance.

Provides a unified interface for opening, navigating, and controlling Excel via COM, regardless of whether the Application object was dispatched (new process) or attached (existing process).

Threading

This class is not thread-safe. Excel COM uses the STA model. All method calls must originate from the thread that constructed the instance. Calls from other threads raise ExcelThreadViolationError immediately.

Lifecycle¶

Two usage patterns are supported:

Context manager (recommended for short, bounded sessions) — cleanup is automatic on exit::

with ExcelApp(mode="dispatch", visible=False) as xl:
    wb = xl.open("C:/reports/budget.xlsx")
    wb.save()
# Excel quit automatically

Manual lifecycle (long-running sessions, e.g. consumer libraries) — call :meth:quit explicitly when done. In attach mode, quit is optional; Excel stays running and the Python reference is released::

xl = ExcelApp(mode="attach")
wb = xl.open("C:/reports/budget.xlsx")
# ... many operations spread across multiple calls ...
xl.quit()   # optional in attach mode — Excel stays running

The COM object is resolved lazily on the first public method call; constructing an ExcelApp instance does not connect to COM.

Parameters:

Name	Type	Description	Default
`mode`	`Literal['dispatch', 'attach']`	`"dispatch"` to start a new Excel instance, or `"attach"` to bind to the already-running one.	`'dispatch'`
`visible`	`bool`	Whether to make the Excel window visible. Only relevant in `dispatch` mode; ignored when attaching.	`True`

Raises:

Type	Description
`ExcelNotAvailableError`	If `mode="attach"` and no Excel instance is currently running.

gui `property` ¶

gui: Any

Access GUI interaction helpers (ribbon, menus, dialogs, keys).

Returns a GUIProxy that bundles all GUI automation surfaces. The proxy is created fresh on each access; it holds no state of its own beyond a reference to this ExcelApp instance.

Surfaces available via the proxy:

gui.ribbon — MSO ribbon execution and state queries.
gui.menu — Legacy CommandBar traversal and execution.
gui.dialog — File-open, file-save, and alert dialogs.
gui.send_keys(…) — Application.SendKeys pass-through.

Returns:

Name	Type	Description
`GUIProxy`	`Any`	Facade bound to this `ExcelApp` instance.

Raises:

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

Example

with ExcelApp(mode="attach") as xl: ... xl.gui.ribbon.execute("FileSave") ... path = xl.gui.dialog.get_file_open()

hwnd `property` ¶

hwnd: int

Win32 window handle of this Excel Application instance.

Returns the Application.Hwnd COM property. Used to bind pywinauto backends to the exact same Excel window managed by this ExcelApp session, preventing cross-instance interference when multiple Excel processes are running simultaneously.

Returns:

Name	Type	Description
`int`	`int`	The Win32 HWND of the Excel main window.

Raises:

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

Example

hwnd = xl.hwnd gui = GUIProxy(xl, keys=PywinautoKeysBackend(hwnd=hwnd))

open ¶

open(path: str | Path) -> WorkbookProxy

Open a workbook file and return a proxy for it.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Absolute path to the workbook file.	required

Returns:

Name	Type	Description
`WorkbookProxy`	`WorkbookProxy`	A proxy bound to the opened workbook.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`COMOperationError`	If Excel cannot open the file.

Example

wb = xl.open("C:/data/report.xlsx")

workbook ¶

workbook(name: str | None = None) -> WorkbookProxy

Return a proxy for an already-open workbook.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	The workbook name as displayed in Excel's title bar (e.g. `"report.xlsx"`). Pass `None` to get the active workbook.	`None`

Returns:

Name	Type	Description
`WorkbookProxy`	`WorkbookProxy`	A proxy bound to the named workbook.

Raises:

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

Example

wb = xl.workbook("report.xlsx")

run_macro ¶

run_macro(name: str, *args: Any) -> Any

Execute a VBA macro by name with optional arguments.

Parameters:

Name	Type	Description	Default
`name`	`str`	Fully qualified macro name (e.g. `"Module1.MyMacro"` or `"'report.xlsm'!Module1.MyMacro"`).	required
`*args`	`Any`	Positional arguments forwarded to the macro.	`()`

Returns:

Name	Type	Description
`Any`	`Any`	The return value of the macro, if any.

Raises:

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

Example

xl.run_macro("Module1.FormatSheet", "Sheet1")

execute_ribbon ¶

execute_ribbon(mso_id: str) -> None

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

Uses Application.CommandBars.ExecuteMso to trigger any built-in Excel ribbon button programmatically without navigating a menu tree.

Parameters:

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

Raises:

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

Example

xl.execute_ribbon("FileSave")

wait_ready ¶

wait_ready(timeout: float = 30.0) -> None

Block until Excel reports it is ready.

Delegates to _com_utils.wait_until_ready. Useful after operations that trigger asynchronous recalculation or file I/O.

Parameters:

Name	Type	Description	Default
`timeout`	`float`	Maximum seconds to wait. Defaults to 30.	`30.0`

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`COMOperationError`	If the timeout is exceeded.

Example

xl.wait_ready(timeout=60.0)

quit ¶

quit(save_changes: bool = False) -> None

Quit the Excel Application.

This method is safe to call multiple times; subsequent calls after the first are no-ops.

Parameters:

Name	Type	Description	Default
`save_changes`	`bool`	If `True`, Excel will prompt to save unsaved workbooks. If `False`, all unsaved changes are discarded. Defaults to `False`.	`False`

Raises:

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

Example

xl.quit(save_changes=False)

CellProxy ¶

CellProxy(sheet: SheetProxy, ref: str)

COM proxy for a single cell in a worksheet.

Instances are created by SheetProxy.cell(). Do not instantiate directly.

Parameters:

Name	Type	Description	Default
`sheet`	`SheetProxy`	The parent `SheetProxy`.	required
`ref`	`str`	Cell address in A1 notation (e.g. `"B3"`).	required

Example

cell = ws.cell("C7") cell.value = 100 print(cell.formula) 100

address `property` ¶

address: str

The absolute address of this cell (e.g. "$B$3").

Returns:

Name	Type	Description
`str`	`str`	Cell address in absolute notation.

value `property` `writable` ¶

value: Any

The cell's current value, normalised to a Python type.

COM date objects are converted to datetime. Error values (#N/A etc.) are returned as None with a WARNING log.

Returns:

Name	Type	Description
`Any`	`Any`	The cell value, or `None` for empty/error cells.

formula `property` `writable` ¶

formula: str

The formula string in the cell (e.g. "=SUM(A1:A5)").

Returns an empty string for cells with no formula.

Returns:

Name	Type	Description
`str`	`str`	Formula string, or empty string if none.

RangeProxy ¶

RangeProxy(sheet: SheetProxy, ref: str)

COM proxy for a rectangular range of cells in a worksheet.

Instances are created by SheetProxy.range() or accessed via SheetProxy.used_range. Do not instantiate directly.

Parameters:

Name	Type	Description	Default
`sheet`	`SheetProxy`	The parent `SheetProxy`.	required
`ref`	`str`	Range address in A1 notation (e.g. `"A1:D10"`).	required

Example

rng = ws.range("A1:C3") data = rng.values # list[list[Any]] rng.values = [[1, 2, 3], ... [4, 5, 6], ... [7, 8, 9]]

address `property` ¶

address: str

The address of this range (e.g. "A1:D10").

Returns:

Name	Type	Description
`str`	`str`	Range address.

values `property` `writable` ¶

values: list[list[Any]]

All cell values in the range as a list of rows.

Single-row or single-column ranges are normalised to a 2D list-of-lists for a consistent return type. COM dates are converted to datetime; error cells return None.

Returns:

Type	Description
`list[list[Any]]`	list[list[Any]]: Row-major 2D list of cell values.

Example

data = ws.range("A1:C3").values first_row = next(iter(data)) first_value = next(iter(first_row))

SheetProxy ¶

SheetProxy(workbook: WorkbookProxy, name: str)

COM proxy for a single Excel Worksheet.

Instances are created by WorkbookProxy.sheet(). Do not instantiate directly.

Parameters:

Name	Type	Description	Default
`workbook`	`WorkbookProxy`	The parent `WorkbookProxy`.	required
`name`	`str`	The worksheet name (as shown on the tab).	required

Example

ws = wb.sheet("Data") ws.cell("A1").value = "Hello" ws.calculate()

name `property` ¶

name: str

The worksheet name as shown on the tab.

Returns:

Name	Type	Description
`str`	`str`	Sheet name.

used_range `property` ¶

used_range: RangeProxy

The smallest rectangle that contains all used cells.

Returns:

Name	Type	Description
`RangeProxy`	`RangeProxy`	Proxy over the `Worksheet.UsedRange` COM range.

Raises:

Type	Description
`SheetNotFoundError`	If the sheet is no longer available.

cell ¶

cell(ref: str) -> CellProxy

Return a proxy for a single cell.

Parameters:

Name	Type	Description	Default
`ref`	`str`	Cell address in A1 notation (e.g. `"B3"`).	required

Returns:

Name	Type	Description
`CellProxy`	`CellProxy`	A proxy bound to the cell.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`SheetNotFoundError`	If the sheet is no longer available.

Example

ws.cell("A1").value = 42

range ¶

range(ref: str) -> RangeProxy

Return a proxy for a cell range.

Parameters:

Name	Type	Description	Default
`ref`	`str`	Range address in A1 notation (e.g. `"A1:D10"`).	required

Returns:

Name	Type	Description
`RangeProxy`	`RangeProxy`	A proxy bound to the range.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`SheetNotFoundError`	If the sheet is no longer available.

Example

rng = ws.range("A1:C5") data = rng.values

calculate ¶

calculate() -> None

Trigger recalculation of all formulas on this sheet.

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`SheetNotFoundError`	If the sheet is no longer available.

Example

ws.calculate()

WorkbookProxy ¶

WorkbookProxy(app: ExcelApp, name: str)

COM proxy for a single Excel Workbook.

Instances are created by ExcelApp.open() or ExcelApp.workbook(). Do not instantiate directly.

All methods enforce COM thread safety by delegating to the parent ExcelApp's thread identity.

Parameters:

Name	Type	Description	Default
`app`	`ExcelApp`	The `ExcelApp` that owns this session.	required
`name`	`str`	The workbook name as shown in Excel's title bar (e.g. `"budget.xlsx"`).	required

Example

with ExcelApp() as xl: ... wb = xl.open("C:/data/report.xlsx") ... print(wb.name) ... wb.save() ... wb.close()

name `property` ¶

name: str

The workbook filename as shown in Excel's title bar.

Returns:

Name	Type	Description
`str`	`str`	Workbook name (e.g. `"report.xlsx"`).

sheets `property` ¶

sheets: list[str]

List of all worksheet names in this workbook.

Returns:

Type	Description
`list[str]`	list[str]: Sheet names in tab order.

Raises:

Type	Description
`WorkbookNotFoundError`	If the workbook is no longer open.

sheet ¶

sheet(name: str) -> SheetProxy

Return a proxy for a named worksheet.

Parameters:

Name	Type	Description	Default
`name`	`str`	The worksheet name (case-sensitive, as shown on the tab).	required

Returns:

Name	Type	Description
`SheetProxy`	`SheetProxy`	A proxy bound to the named worksheet.

Raises:

Type	Description
`SheetNotFoundError`	If no sheet with that name exists.
`WorkbookNotFoundError`	If the workbook is no longer open.

Example

ws = wb.sheet("Summary")

save ¶

save() -> None

Save the workbook in place (equivalent to Ctrl+S).

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`WorkbookNotFoundError`	If the workbook is no longer open.
`COMOperationError`	If the save fails.

Example

wb.save()

save_as ¶

save_as(path: str | Path, fmt: str | None = None) -> None

Save the workbook to a new path, optionally changing its format.

Uses COM Workbook.SaveAs which keeps Excel open. Suitable for format conversion (e.g. xlsx → csv) via an active Excel session.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Destination file path. The extension determines the format when `fmt` is `None`.	required
`fmt`	`str \| None`	Explicit format override. Must be a key from the internal format map (e.g. `".csv"`, `".xlsx"`). If omitted the extension of `path` is used.	`None`

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`WorkbookNotFoundError`	If the workbook is no longer open.
`COMOperationError`	If SaveAs fails.
`ValueError`	If the file extension cannot be mapped to a COM format.

Example

wb.save_as("C:/output/report.csv") wb.save_as("C:/output/report_backup.xlsx", fmt=".xlsx")

close ¶

close(save: bool = False) -> None

Close the workbook.

Parameters:

Name	Type	Description	Default
`save`	`bool`	If `True`, save changes before closing. Defaults to `False` (discard unsaved changes).	`False`

Raises:

Type	Description
`ExcelThreadViolationError`	If called from the wrong thread.
`WorkbookNotFoundError`	If the workbook is no longer open.
`COMOperationError`	If the close operation fails.

Example

wb.close(save=True)

GUIProxy ¶

GUIProxy(app: ExcelAppLike, ribbon: AbstractRibbonBackend | None = None, menu: AbstractMenuBackend | None = None, dialog: AbstractDialogBackend | None = None, keys: AbstractKeysBackend | None = None, backstage: AbstractBackstageFileOps | None = None, backstage_nav: AbstractBackstageNavigator | None = None)

Unified facade for GUI-level Excel interaction.

Instantiated by ExcelApp.gui and bundles all six automation surfaces (ribbon, menu, dialog, keys, backstage, backstage_nav) under a single object.

Backend injection¶

Each surface can be replaced at construction time by passing an alternative implementation that satisfies the corresponding abstract protocol. This is the primary extension point for non-COM backends such as pywinauto. Passing None (the default) selects the standard COM implementation for that surface — except for backstage_nav, which defaults to None (no UIA navigator).

The backstage and backstage_nav surfaces are intentionally separate:

backstage (AbstractBackstageFileOps) — file I/O operations via COM. Focus-independent, locale-independent. Always present.
backstage_nav (AbstractBackstageNavigator | None) — visual panel navigation via UIA. Required for open_options and open_save_as_panel. Inject explicitly when needed.

Parameters:

Name	Type	Description	Default
`app`	`ExcelAppLike`	The active `ExcelApp` instance that owns this proxy.	required
`ribbon`	`AbstractRibbonBackend \| None`	Optional ribbon backend. Defaults to :class:`~ezxl.gui.RibbonProxy` when `None`.	`None`
`menu`	`AbstractMenuBackend \| None`	Optional menu backend. Defaults to :class:`~ezxl.gui.MenuProxy` when `None`.	`None`
`dialog`	`AbstractDialogBackend \| None`	Optional dialog backend. Defaults to :class:`~ezxl.gui.DialogProxy` when `None`.	`None`
`keys`	`AbstractKeysBackend \| None`	Optional keys backend. Defaults to :class:`~ezxl.gui._gui_proxy._COMKeysBackend` when `None`.	`None`
`backstage`	`AbstractBackstageFileOps \| None`	Optional Backstage file-ops backend. Defaults to :class:`~ezxl.gui.win32com._backstage.COMBackstageBackend` when `None`.	`None`
`backstage_nav`	`AbstractBackstageNavigator \| None`	Optional Backstage UIA navigator. Defaults to `None` (no UIA navigator). Pass a :class:`~ezxl.gui.pywinauto.PywinautoBackstageBackend` to enable `open_options` and `open_save_as_panel`.	`None`

Security note

When injecting pywinauto backends, always pass hwnd=app.hwnd to bind the backend to the exact Excel window managed by this session. Omitting hwnd causes pywinauto to attach to the first Excel window it finds, which may not be the correct one when multiple Excel instances are running.

Example

with ExcelApp(mode="attach") as xl: ... xl.gui.ribbon.execute("FileSave") ... xl.gui.backstage.save() ... path = xl.gui.dialog.get_file_open() ... xl.gui.send_keys("^{HOME}")

Example — with UIA navigator::

gui = GUIProxy(
    xl,
    backstage=COMBackstageBackend(xl),
    backstage_nav=PywinautoBackstageBackend(hwnd=xl.hwnd, locale="fr"),
)
gui.backstage.save()                        # COM: direct save
gui.backstage.save_as(path="out.xlsx")      # COM: format-aware save
gui.backstage_nav.open_options()            # UIA: opens Options panel
gui.backstage_nav.open_save_as_panel()      # UIA: opens panel only

ribbon `property` ¶

ribbon: AbstractRibbonBackend

Return the ribbon backend for MSO ribbon command interaction.

Returns:

Name	Type	Description
`AbstractRibbonBackend`	`AbstractRibbonBackend`	The configured ribbon backend (default: :class:`~ezxl.gui.RibbonProxy`).

Example

xl.gui.ribbon.execute("FileSave") xl.gui.ribbon.is_enabled("Copy") True

menu `property` ¶

menu: AbstractMenuBackend

Return the menu backend for legacy CommandBar interaction.

Returns:

Name	Type	Description
`AbstractMenuBackend`	`AbstractMenuBackend`	The configured menu backend (default: :class:`~ezxl.gui.MenuProxy`).

Example

xl.gui.menu.list_bars() ['Standard', 'Formatting', ...]

dialog `property` ¶

dialog: AbstractDialogBackend

Return the dialog backend for file picker and alert dialogs.

Returns:

Name	Type	Description
`AbstractDialogBackend`	`AbstractDialogBackend`	The configured dialog backend (default: :class:`~ezxl.gui.DialogProxy`).

Example

path = xl.gui.dialog.get_file_open(title="Select report")

backstage `property` ¶

backstage: AbstractBackstageFileOps

Return the Backstage file-ops backend.

Handles save, save_as, open_file, and close_workbook via the COM object model — focus-independent and locale-independent.

The default backend is :class:~ezxl.gui.win32com._backstage.COMBackstageBackend. Replace it at construction time to swap the implementation::

gui = GUIProxy(xl, backstage=MyCustomFileOpsBackend(xl))

Returns:

Name	Type	Description
`AbstractBackstageFileOps`	`AbstractBackstageFileOps`	The configured file-ops backend.

Example

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

backstage_nav `property` ¶

backstage_nav: AbstractBackstageNavigator | None

Return the Backstage UIA navigator, or None if not injected.

Handles open_options, open_save_as_panel, open_file, and close_workbook via UIA direct click. This backend must be injected explicitly — there is no COM default::

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

Returns:

Type	Description
`AbstractBackstageNavigator \| None`	AbstractBackstageNavigator \| None: The configured UIA navigator, or `None` if none was provided.

Example

if xl.gui.backstage_nav is not None: ... xl.gui.backstage_nav.open_options()

send_keys ¶

send_keys(keys: str, wait: bool = True) -> None

Send a keystroke sequence to the Excel Application window.

Delegates to the configured :class:~ezxl.gui._protocols.AbstractKeysBackend. The keys string must use standard VBA SendKeys notation (e.g. "{ENTER}", "^s" for Ctrl+S).

Parameters:

Name	Type	Description	Default
`keys`	`str`	Keystroke string in VBA SendKeys notation.	required
`wait`	`bool`	If `True`, block until Excel processes the keystrokes before returning. Defaults to `True`.	`True`

Raises:

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

Example

xl.gui.send_keys("^s") # Ctrl+S xl.gui.send_keys("{ESCAPE}")

PywinautoBackstageBackend ¶

PywinautoBackstageBackend(hwnd: int | None = None, locale: str = 'en')

Bases: AbstractBackstageNavigator

Excel Backstage visual navigation via UIA direct click with Alt-sequence fallback.

Implements :class:~ezxl.gui._protocols.AbstractBackstageNavigator using pywinauto. The primary strategy for every action is a UIA direct click — the backend opens the Backstage via Button "Onglet Fichier" (or locale equivalent), then clicks the target ListItem by its localised UIA Name. This approach is focus-independent.

An Alt-sequence fallback is attempted only when the UIA click fails and the element spec carries a non-empty alt_sequence.

This backend does not perform file I/O. Operations that write to disk (save, save_as with an explicit path) belong to :class:~ezxl.gui.win32com.COMBackstageBackend and are exposed through GUIProxy.backstage. This backend is composed alongside it via GUIProxy.backstage_nav.

Parameters:

Name	Type	Description	Default
`hwnd`	`int \| None`	Win32 window handle for the Excel main window. Pass `None` to auto-detect the first visible Excel instance. Always pass `xl.hwnd` in production to avoid targeting the wrong window when multiple Excel instances are open.	`None`
`locale`	`str`	Locale code used for UIA `Name`-based searches. Accepted values: `"en"` (default), `"fr"`.	`'en'`

Example

backend = PywinautoBackstageBackend(hwnd=xl.hwnd, locale="fr") backend.open_options() # UIA: opens Options panel backend.open_save_as_panel() # UIA: opens Save As panel, leaves open backend.open_file() # UIA: opens Open panel backend.close_workbook() # UIA: clicks Close in Backstage

open_options ¶

open_options() -> None

Navigate to the Excel Options panel via the Backstage.

Raises:

Type	Description
`GUIOperationError`	If the Options panel cannot be reached.

Example

backend.open_options()

open_save_as_panel ¶

open_save_as_panel() -> None

Open the Save As panel in the Backstage without confirming a save.

Clicks the "Enregistrer sous" (or locale equivalent) ListItem and leaves the panel open. Does not write to disk — use GUIProxy.backstage.save_as(path=...) for programmatic saves.

Raises:

Type	Description
`GUIOperationError`	If the panel cannot be reached.

Example

backend.open_save_as_panel()

open_file ¶

open_file() -> None

Open the Open panel via the Backstage.

Raises:

Type	Description
`GUIOperationError`	If the panel cannot be reached.

Example

backend.open_file()

close_workbook ¶

close_workbook() -> None

Close the active workbook via a Backstage UIA click.

Raises:

Type	Description
`GUIOperationError`	If the action cannot be completed.

Example

backend.close_workbook()

PywinautoKeysBackend ¶

PywinautoKeysBackend(hwnd: int | None = None)

Bases: AbstractKeysBackend

Keystroke injection via pywinauto.keyboard.send_keys.

Translates VBA SendKeys notation to pywinauto notation using :func:_translate_keys, then delegates to pywinauto.keyboard.send_keys.

This backend is a standalone alternative to the COM-based _COMKeysBackend. It does not require an :class:~ezxl.core.ExcelApp instance and carries no COM STA thread constraint.

Parameters:

Name	Type	Description	Default
`hwnd`	`int \| None`	Win32 window handle for the Excel main window. Currently unused — `pywinauto.keyboard.send_keys` injects keystrokes into the currently focused window. Ensure the Excel window has focus before calling :meth:`send_keys`. The parameter is accepted for API consistency with the other pywinauto backends and reserved for future use.	`None`

Example

from ezxl.gui.pywinauto import PywinautoKeysBackend keys = PywinautoKeysBackend() keys.send_keys("^s") # Ctrl+S keys.send_keys("{ESCAPE}") # maps to {ESC} internally keys.send_keys("^{HOME}")

Inject into GUIProxy:¶

from ezxl import ExcelApp, GUIProxy with ExcelApp(mode="attach") as xl: ... gui = GUIProxy(xl, keys=PywinautoKeysBackend()) ... gui.send_keys("^{HOME}")

send_keys ¶

send_keys(keys: str, wait: bool = True) -> None

Send a keystroke sequence using pywinauto.keyboard.

Translates keys from VBA SendKeys notation to pywinauto notation via :func:_translate_keys, then calls pywinauto.keyboard.send_keys. If wait is True, a brief pause of 50 ms is inserted after injection as a best-effort approximation of the VBA wait=True semantics.

Note

pywinauto.keyboard.send_keys injects keystrokes into the currently focused window. Call window.set_focus() on the Excel window before using this backend if focus cannot be guaranteed.

Parameters:

Name	Type	Description	Default
`keys`	`str`	Keystroke string in VBA SendKeys notation (e.g. `"{ENTER}"`, `"^s"` for Ctrl+S, `"{ESCAPE}"` for Escape).	required
`wait`	`bool`	If `True`, insert a 50 ms pause after sending. This is a best-effort approximation; it does not guarantee Excel has finished processing. Defaults to `True`.	`True`

Raises:

Type	Description
`GUIOperationError`	If the pywinauto keystroke injection raises an unexpected error.

Example

backend.send_keys("^s") # Ctrl+S backend.send_keys("{ESCAPE}") # → {ESC} internally backend.send_keys("%{F4}", wait=False) # Alt+F4, no pause

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()

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")

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', ...]

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

csv_to_xlsx ¶

csv_to_xlsx(source: str | Path, dest: str | Path, sheet_name: str = 'Sheet1', *pl_write_args: Any, **pl_write_kwargs: Any) -> None

Convert a CSV file to an Excel workbook using polars.

Reads the CSV with polars and writes it as an .xlsx file. polars delegates the Excel write step to xlsxwriter or openpyxl depending on which is installed; no additional configuration is required.

Parameters:

Name	Type	Description	Default
`source`	`str \| Path`	Path to the source `.csv` file.	required
`dest`	`str \| Path`	Destination `.xlsx` file path. Parent directories must exist.	required
`sheet_name`	`str`	Name of the worksheet to create in the output workbook. Defaults to `"Sheet1"`.	`'Sheet1'`
`*pl_write_args`	`Any`	Positional arguments forwarded to `DataFrame.write_excel`.	`()`
`**pl_write_kwargs`	`Any`	Keyword arguments forwarded to `DataFrame.write_excel`. `worksheet` is only applied when it is not already present.	`{}`

Raises:

Type	Description
`FileNotFoundError`	If `source` does not exist.

Example

csv_to_xlsx("transactions.csv", "transactions.xlsx", sheet_name="Data")

read_csv ¶

read_csv(source: str | Path, separator: str = ',', encoding: str = 'utf-8', *pl_args: Any, **pl_kwargs: Any) -> DataFrame

Read a CSV file into a polars DataFrame.

Parameters:

Name	Type	Description	Default
`source`	`str \| Path`	Path to the source `.csv` file.	required
`separator`	`str`	Column delimiter character. Defaults to `","` (standard CSV). Use `"\t"` for TSV files.	`','`
`encoding`	`str`	File encoding passed through to polars. Defaults to `"utf-8"`.	`'utf-8'`
`*pl_args`	`Any`	Positional arguments forwarded to `polars.read_csv`.	`()`
`**pl_kwargs`	`Any`	Keyword arguments forwarded to `polars.read_csv`. `separator` and `encoding` are applied only when these keys are not already present in `pl_kwargs`.	`{}`

Returns:

Type	Description
`DataFrame`	pl.DataFrame: Parsed contents of the CSV file.

Raises:

Type	Description
`FileNotFoundError`	If `source` does not exist.

Example

df = read_csv("transactions.csv", separator=";") print(df.schema)

read_excel ¶

read_excel(source: str | Path, sheet: str | None = None, *pl_args: Any, **pl_kwargs: Any) -> DataFrame

Read an Excel workbook sheet into a polars DataFrame.

Delegates to polars.read_excel which uses fastexcel (Rust) under the hood. No running Excel process is required.

Parameters:

Name	Type	Description	Default
`source`	`str \| Path`	Path to the source `.xlsx` / `.xlsm` file.	required
`sheet`	`str \| None`	Worksheet name to read. Pass `None` to read the first sheet (polars default when `sheet_name` is omitted).	`None`
`*pl_args`	`Any`	Positional arguments forwarded to `polars.read_excel`.	`()`
`**pl_kwargs`	`Any`	Keyword arguments forwarded to `polars.read_excel`. If `sheet` is provided and `sheet_name` is not set, this function injects `sheet_name=sheet` for compatibility.	`{}`

Returns:

Type	Description
`DataFrame`	pl.DataFrame: Contents of the requested sheet as a polars
`DataFrame`	DataFrame, with the first row used as column headers.

Raises:

Type	Description
`FileNotFoundError`	If `source` does not exist.
`ImportError`	If polars (or its `fastexcel` extra) is not installed.

Example

df = read_excel("report.xlsx", sheet="Data") print(df.head())

read_sheet ¶

read_sheet(source: str | Path, sheet: str | None = None, *pl_args: Any, **pl_kwargs: Any) -> list[list[Any]]

Read a worksheet into a row-major list of lists (compatibility shim).

Wraps read_excel and converts the resulting polars DataFrame to a list[list[Any]] via DataFrame.rows(). The first row contains the column headers as extracted by polars.

This function exists for backwards compatibility with callers that pre-date the polars migration. New code should use read_excel directly to benefit from the full polars API.

Parameters:

Name	Type	Description	Default
`source`	`str \| Path`	Path to the source `.xlsx` / `.xlsm` file.	required
`sheet`	`str \| None`	Worksheet name to read. Pass `None` to use the first sheet.	`None`
`*pl_args`	`Any`	Positional arguments forwarded to `read_excel`.	`()`
`**pl_kwargs`	`Any`	Keyword arguments forwarded to `read_excel`.	`{}`

Returns:

Type	Description
`list[list[Any]]`	list[list[Any]]: Row-major 2D list of cell values. The first
`list[list[Any]]`	row contains column headers; subsequent rows contain data
`list[list[Any]]`	values. Empty cells are represented as `None`.

Raises:

Type	Description
`FileNotFoundError`	If `source` does not exist.

Example

data = read_sheet("report.xlsx", sheet="Data") headers = data[0] rows = data[1:]

xlsx_to_csv ¶

xlsx_to_csv(source: str | Path, dest: str | Path, sheet: str | None = None, separator: str = ',', *pl_write_args: Any, **pl_write_kwargs: Any) -> None

Convert an Excel workbook sheet to a CSV file using polars.

Supersedes both the former xlsx_to_csv (openpyxl) and xlsx_to_csv_fast (python-calamine) functions. polars uses fastexcel (Rust) for the read step, providing the same high-throughput characteristics as the former fast path.

Parameters:

Name	Type	Description	Default
`source`	`str \| Path`	Path to the source `.xlsx` / `.xlsm` file.	required
`dest`	`str \| Path`	Destination `.csv` file path. Parent directories must exist.	required
`sheet`	`str \| None`	Worksheet name to export. Pass `None` to use the first sheet.	`None`
`separator`	`str`	Column delimiter for the CSV output. Defaults to `","` (standard CSV).	`','`
`*pl_write_args`	`Any`	Positional arguments forwarded to `DataFrame.write_csv`.	`()`
`**pl_write_kwargs`	`Any`	Keyword arguments forwarded to `DataFrame.write_csv`. `separator` is only applied when it is not already present.	`{}`

Raises:

Type	Description
`FileNotFoundError`	If `source` does not exist.

Example

xlsx_to_csv("data.xlsx", "data.csv", sheet="Transactions") xlsx_to_csv("data.xlsx", "data.tsv", separator="\t")

Full API reference¶

🔍 Top-level package¶

ezxl ¶

COMOperationError ¶

ExcelNotAvailableError ¶

ExcelSessionLostError ¶

ExcelThreadViolationError ¶

EzXlError ¶

FormatterError ¶

GUIOperationError ¶

SheetNotFoundError ¶

WorkbookNotFoundError ¶

AbstractBackstageFileOps ¶

save abstractmethod ¶

save_as abstractmethod ¶

open_file abstractmethod ¶

close_workbook abstractmethod ¶

AbstractBackstageNavigator ¶

open_options abstractmethod ¶

open_save_as_panel abstractmethod ¶

open_file abstractmethod ¶

close_workbook abstractmethod ¶

AbstractDialogBackend ¶

get_file_open abstractmethod ¶

get_file_save abstractmethod ¶

alert abstractmethod ¶

AbstractKeysBackend ¶

send_keys abstractmethod ¶

AbstractMenuBackend ¶

click abstractmethod ¶

list_bars abstractmethod ¶

list_controls abstractmethod ¶

AbstractRibbonBackend ¶

execute abstractmethod ¶

is_enabled abstractmethod ¶

is_pressed abstractmethod ¶

is_visible abstractmethod ¶

ExcelFormatter ¶

column_width ¶

row_height ¶

font ¶

fill ¶

border ¶

align ¶

save ¶

ExcelApp ¶

Lifecycle¶

gui property ¶

hwnd property ¶

open ¶

workbook ¶

run_macro ¶

execute_ribbon ¶

wait_ready ¶

quit ¶

CellProxy ¶

address property ¶

value property writable ¶

formula property writable ¶

RangeProxy ¶

address property ¶

values property writable ¶

SheetProxy ¶

name property ¶

used_range property ¶

cell ¶

range ¶

calculate ¶

WorkbookProxy ¶

name property ¶

sheets property ¶

sheet ¶

save ¶

save_as ¶

close ¶

GUIProxy ¶

Backend injection¶

ribbon property ¶

menu property ¶

dialog property ¶

save `abstractmethod` ¶

save_as `abstractmethod` ¶

open_file `abstractmethod` ¶

close_workbook `abstractmethod` ¶

open_options `abstractmethod` ¶

open_save_as_panel `abstractmethod` ¶

open_file `abstractmethod` ¶

close_workbook `abstractmethod` ¶

get_file_open `abstractmethod` ¶

get_file_save `abstractmethod` ¶

alert `abstractmethod` ¶

send_keys `abstractmethod` ¶

click `abstractmethod` ¶

list_bars `abstractmethod` ¶

list_controls `abstractmethod` ¶

execute `abstractmethod` ¶

is_enabled `abstractmethod` ¶

is_pressed `abstractmethod` ¶

is_visible `abstractmethod` ¶

gui `property` ¶

hwnd `property` ¶

address `property` ¶

value `property` `writable` ¶

formula `property` `writable` ¶

address `property` ¶

values `property` `writable` ¶

name `property` ¶

used_range `property` ¶

name `property` ¶

sheets `property` ¶

ribbon `property` ¶

menu `property` ¶

dialog `property` ¶

backstage `property` ¶

backstage_nav `property` ¶