---
name: advanced-com-api
description: Excel COM API reference for win32com/pywin32 automation.
---

# Excel COM API via win32com (pywin32)

`app = xl_app()` returns `win32com.client.CDispatch` wrapping `Excel.Application`. The full VBA/COM object model is available — every property, method, and event. Nothing is neutered.

## Type Libraries

Two auto-generated type stubs from the actual Excel type library (`EXCEL.EXE`) via [pyxll/exceltypes](https://github.com/pyxll/exceltypes). These are `typing.Protocol` classes with full method signatures, return types, and enum definitions.

- **`excel-type-library.py`** (~27,800 lines) — Microsoft Excel 16.0 Object Library. All Excel classes: Application, Workbook, Worksheet, Range, Chart, PivotTable, Shape, Style, etc. Plus all `Xl*` enums (XlChartType, XlFileFormat, XlBorderWeight, etc.) and the master `Constants` enum.

- **`office-type-library.py`** (~10,900 lines) — Microsoft Office 16.0 Object Library. Shared Office types: CommandBar, Shape (Office-level), FileDialog, DocumentProperties, Ribbon/IRibbonUI, plus all `Mso*` enums (MsoAutoShapeType, MsoThemeColor, etc.).

## Searching the API

```bash
# Find a class and its methods
grep -n "class Range" excel-type-library.py
grep -n "class Range" excel-type-library.py -A 200 | head -100

# Search for method/property names
grep -n "def AutoFilter\|def Sort\|def Find" excel-type-library.py

# Find enums and their values
grep -n "^class Xl" excel-type-library.py | head -50
grep -n "class XlChartType" excel-type-library.py -A 60

# Search for constants by name
grep -in "xlUp\|xlDown\|xlToLeft\|xlToRight" excel-type-library.py

# Find all properties on a class (properties are defined as methods with @property)
grep -n "class _Worksheet" excel-type-library.py -A 500 | grep "def \|@property" | head -80

# Search Office shared types (shapes, command bars, etc.)
grep -n "class CommandBar\|class Shape" office-type-library.py
```

## Key Classes (line references for excel-type-library.py)

Use `grep -n "class ClassName"` to find exact locations. Key Protocol classes:

- `_Application` — app-level settings, calculation, display, macros
- `_Workbook` — workbook operations, save, protect, connections
- `_Worksheet` — sheet operations, ranges, charts, pivot tables
- `Range` — cell operations, values, formulas, formatting, find/replace
- `_Chart` — chart type, series, axes, title, legend, export
- `PivotTable` — pivot cache, fields, calculated fields, refresh
- `ListObject` — structured tables, columns, rows, totals
- `Shape` — shapes, images, text frames, fills, lines
- `Style` — named styles, font, borders, interior
- `FormatCondition` — conditional formatting rules
- `Validation` — data validation rules
- `Comment` / `CommentThreaded` — cell comments
- `AutoFilter` — column filters
- `PageSetup` — print settings, margins, headers/footers
- `Name` — named ranges and formulas
- `Hyperlink` — cell hyperlinks

CoClasses (the actual dispatchable COM objects) are at the bottom of the file:
- `Application(_Application)` — line ~27746
- `Workbook(_Workbook)` — line ~27762
- `Worksheet(_Worksheet)` — line ~27766

## Python ↔ COM Notes

- COM collections are **1-based**: `ws.Cells(1,1)` is A1, `wb.Sheets(1)` is first sheet
- `.Value` returns **tuples of tuples** (0-based): `data[0][0]` is first cell
- Colors use **BGR order**: `r + (g << 8) + (b << 16)` — NOT RGB
- Dates come back as `pywintypes.datetime`, not Python `datetime`
- Constants can be used as raw integers (always works with late binding)
