Excel Objects

Work with Excel workbooks, worksheets, ranges, and cells using the xpycode module in Python.

The xpycode Module

The xpycode module provides embedded objects that mirror Office.js objects, enabling seamless Excel integration from Python.

Users can directly access:

• xpycode.context: A RequestContext object, the foundation for Office.js interaction with Excel. Note that there is no need to use context.sync() or .load() methods—synchronization is handled automatically.
• xpycode.workbook: The workbook object containing the Python module. Unlike COM objects, Office.js only provides access to the current workbook.
• xpycode.worksheets: The worksheet collection of the workbook.

For detailed information on available methods and properties, refer to the Excel JavaScript API documentation.

Win32 COM Access (Windows Only)

For advanced scenarios where Office.js doesn't provide the functionality you need, xpycode provides direct access to the Excel Win32 COM API through xpycode.win32. This allows you to use the full power of Excel's native COM automation interface alongside the standard Office.js-based API.

Windows Only

xpycode.win32 is only available on Windows and requires the pywin32 package to be installed. Accessing this property on other platforms will raise an EnvironmentError.

When to Use Win32 COM

Use xpycode.win32 when you need:

• Application-level access - Control Excel settings, manage multiple workbooks, or access application properties not available in Office.js
• Advanced formatting - Apply complex formatting using VBA-style constants (e.g., xlCenter, xlEdgeBottom)
• Legacy compatibility - Work with existing VBA/COM code patterns
• Features not in Office.js - Access Excel features that aren't exposed through the Office.js API

For most use cases, prefer the standard xpycode.workbook and Office.js API, as it's cross-platform and simpler to use.

Properties

xpycode.win32 provides three properties:

Property	Type	Description
application	xpycode.ExcelComObjects.Application	The Win32 COM Application object representing the running Excel instance
workbook	xpycode.ExcelComObjects.Workbook	The Win32 COM Workbook object for the current workbook (matched via xpycode_id custom property)
constants	xpycode.ExcelComObjects.constants	Classic Excel VBA constants (e.g., xlCenter, xlEdgeBottom, xlSolid)

Type Hints

For IDE autocompletion with Win32 COM objects, use xpycode.ExcelComObjects:

import xpycode

def format_with_com():
    # Type hints for IDE support
    app: xpycode.ExcelComObjects.Application = xpycode.win32.application
    wb: xpycode.ExcelComObjects.Workbook = xpycode.win32.workbook

    # Access COM properties and methods
    print(f"Excel version: {app.Version}")

Office.js vs Win32 COM Comparison

Aspect	Office.js (xpycode.workbook)	Win32 COM (xpycode.win32.workbook)
Platform	Cross-platform (Windows, Mac, Web)	Windows only
Scope	Current workbook only	All open workbooks + application
API Style	Modern async-style (auto-synced)	Traditional COM/VBA style
Type Hints	xpycode.Excel.Workbook	xpycode.ExcelComObjects.Workbook
Use Case	Standard Excel operations	Advanced features, app control

Code Examples

Basic Access Pattern

import xpycode

# Access Win32 COM objects
win32 = xpycode.win32

# Get application-level information
print(f"Excel version: {win32.application.Version}")
print(f"Workbook name: {win32.workbook.Name}")
print(f"Workbook path: {win32.workbook.FullName}")

Using Constants for Formatting

import xpycode

# Access COM objects and constants
win32 = xpycode.win32
xl = win32.constants

# Get the active sheet via COM
ws = win32.workbook.ActiveSheet

# Apply formatting with VBA-style constants
cell_range = ws.Range("A1:C1")

# Set horizontal alignment to center
cell_range.HorizontalAlignment = xl.xlCenter

# Add borders
cell_range.Borders(xl.xlEdgeBottom).LineStyle = xl.xlContinuous
cell_range.Borders(xl.xlEdgeBottom).Weight = xl.xlMedium

Accessing Application-Level Properties

import xpycode

win32 = xpycode.win32

# Control Excel application settings
win32.application.ScreenUpdating = False  # Disable screen updates for performance
win32.application.DisplayAlerts = False   # Suppress alerts

try:
    # Perform operations...
    win32.workbook.ActiveSheet.Range("A1").Value = "Hello from COM!"
finally:
    # Restore settings
    win32.application.ScreenUpdating = True
    win32.application.DisplayAlerts = True

Type Hints Example

import xpycode

def get_workbook_info() -> dict:
    """Get workbook information using Win32 COM with type hints."""
    # Type hints enable IDE autocompletion
    app: xpycode.ExcelComObjects.Application = xpycode.win32.application
    wb: xpycode.ExcelComObjects.Workbook = xpycode.win32.workbook

    return {
        "name": wb.Name,
        "path": wb.FullName,
        "sheets": wb.Worksheets.Count,
        "excel_version": app.Version,
    }

Mixing Office.js and COM

import xpycode

# Use Office.js for standard operations (cross-platform)
ws_officejs = xpycode.workbook.worksheets.getActiveWorksheet()
ws_officejs.getRange("A1").values = "Office.js data"

# Use COM for advanced features (Windows only)
win32 = xpycode.win32
ws_com = win32.workbook.ActiveSheet

# Apply complex formatting via COM
ws_com.Range("A1").Font.Bold = True
ws_com.Range("A1").Interior.Color = 0xFFFF00  # Yellow background

Choosing the Right API

• Start with Office.js (xpycode.workbook) for standard operations
• Switch to Win32 COM (xpycode.win32) only when you need features not available in Office.js
• Remember: xpycode.workbook is a proxy object, while xpycode.win32.workbook is a native COM object

Next Steps

• Custom Functions - Publish functions to Excel
• Events - Handle Excel events
• Data Analysis Tutorial - Practical examples

---

Office.js Reference

For more details on available methods and properties, see the Excel JavaScript API Reference. Remember: xpycode mirrors Office.js, and you don't need to call context.sync()!