EzXl

EzXl is a lightweight Python library for Excel automation via COM (win32com) on Windows — open workbooks, manipulate sheets, interact with the ribbon, and convert between formats, all from a clean Python API.

📦 Installation

Standard

# Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate

# Install in development mode with the `dev` dependency group
uv sync --group dev

pywin32 post-install step (mandatory)

Warning: pywin32 requires a post-install script to register COM components. This step is mandatory and must be run once after installation. Skipping it will cause COM dispatch to fail.

python .venv/Scripts/pywin32_postinstall.py -install

Corporate offline environment

In restricted environments without PyPI access, install from local wheel files only. No network requests are made during installation. Configure your pip to point to a local wheel directory:

pip install --no-index --find-links=\\share\wheels -e . --group dev

Optional pywinauto backend

To enable the pywinauto GUI automation backend (UIA-based, locale-independent):

pip install -e ".[pywinauto]"

Note: Ensure your Python interpreter bitness (32-bit or 64-bit) matches the installed Excel. COM dispatch will fail on a mismatch. Verify with:

python -c "import struct; print(struct.calcsize('P') * 8)"

🚀 Quick Start

from ezxl import ExcelApp

# Open a workbook and read from a sheet
with ExcelApp(mode="dispatch", visible=True) as xl:
    wb = xl.open("C:/reports/budget.xlsx")
    sheet = wb.sheet("Summary")
    value = sheet.cell("B2").value
    print(value)
    wb.save()

# Attach to a running Excel instance (left running on exit)
with ExcelApp(mode="attach") as xl:
    xl.gui.ribbon.execute("FileSave")

# Attach if Excel is open, start a private instance otherwise.
# Excel is only quit on exit when ezxl started it.
with ExcelApp(mode="auto") as xl:
    wb = xl.workbook()

🎯 Key Features

• ✅ COM Automation: open, attach, navigate Excel via win32com
• ✅ GUI Interaction: ribbon, menus, dialogs, and SendKeys via win32com
• ✅ Swappable GUI Backends: COM or pywinauto, injected via protocol ABCs
• ✅ File I/O: xlsx↔csv conversion via polars+fastexcel (no Excel required)
• ✅ Closed-file Formatting: colors, fonts, and borders via openpyxl
• ✅ Thread Safety: COM STA model enforced, thread identity checked at construction
• ✅ Full Type Hints: complete typing for IDEs and linters
• ✅ Corporate Ready: offline wheel install, proxy support

📚 Documentation

Full documentation is available online: neuraaak.github.io/ezxl

• 📖 Getting Started – Installation, first steps, and environment setup
• 🎯 API Reference – Complete class and function reference (auto-generated)
• 🏗️ Architecture – Design decisions and component overview
• 💡 Examples – Usage examples for common scenarios
• 🔧 Development – Environment setup and contribution guide
• 🧪 Testing – Test suite documentation (coming in next sprint)

🧪 Testing

# Install dev dependencies
uv sync --group dev

# Run unit tests (no Excel required) - what CI runs
uv run poe test-ci

# Run the whole suite, integration tests included (requires local Excel)
uv run poe test

Note: Integration tests marked with @pytest.mark.excel require a locally installed Excel instance. They are excluded from CI/CD pipelines and are intended for local verification only.

🛠️ Development Setup

# Clone the repository
git clone https://github.com/neuraaak/ezxl.git
cd ezxl

# Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate

# Install in development mode with all dev dependencies
uv sync --group dev

# Mandatory: register pywin32 COM components
python .venv/Scripts/pywin32_postinstall.py -install

# Set up git hooks
git config core.hooksPath .hooks

See the Development Guide for detailed setup instructions.

🔌 API Overview

🖥️ COM Automation (5)

🎛️ GUI Interaction (4)

🔌 GUI Backends — pywinauto (4)

📂 File I/O (5)

📦 Dependencies

• pywin32>=306 — COM driver (win32com.client), Windows-only
• polars>=1.0.0 — DataFrame I/O engine
• fastexcel>=0.11.0 — Fast xlsx reader (Rust binding)
• xlsxwriter>=3.0.0 — xlsx write backend for polars
• openpyxl>=3.1.0 — Closed-file formatting
• ezplog>=2.0.0 — Structured logging

Optional:

• pywinauto>=0.6.8 — UI Automation backend (locale-independent GUI interaction)

📄 License

MIT License – See LICENSE file for details.

🔗 Links

• Repository: https://github.com/neuraaak/ezxl
• Issues: GitHub Issues
• Documentation: neuraaak.github.io/ezxl
• Changelog: docs/changelog.md

ezxl — Excel automation made simple, reliable, and Pythonic. 🐍