or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

automation.mdclient-api.mdcore-com.mdindex.mdserver.mdutilities.md
tile.json

tessl/pypi-comtypes

Pure Python COM package for Windows COM automation and interoperability

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/comtypes@1.4.x

To install, run

npx @tessl/cli install tessl/pypi-comtypes@1.4.0

index.mddocs/

comtypes

A pure Python COM (Component Object Model) package for Windows that enables Python applications to interact with COM objects, servers, and interfaces. Built on top of Python's ctypes foreign function interface, comtypes provides comprehensive COM functionality with zero additional dependencies, supporting both early-bound (strongly-typed) and late-bound (dispatch-based) programming models.

Package Information

  • Package Name: comtypes
  • Language: Python
  • Platform: Windows (COM technology specific)
  • Installation: pip install comtypes

Core Imports

import comtypes

For high-level COM automation:

from comtypes.client import CreateObject, GetActiveObject, GetEvents

For automation types and interfaces:

from comtypes.automation import VARIANT, IDispatch

For server development:

from comtypes.server import IClassFactory

Basic Usage

import comtypes.client

# Create a COM object (e.g., Excel application)
xl = comtypes.client.CreateObject("Excel.Application")
xl.Visible = True

# Create a new workbook
wb = xl.Workbooks.Add()
ws = wb.ActiveSheet

# Write data to cells
ws.Cells(1, 1).Value = "Hello"
ws.Cells(1, 2).Value = "World"

# Save and close
wb.SaveAs("C:\\temp\\example.xlsx")
wb.Close()
xl.Quit()
# Using dispatch for late binding
import comtypes.client

# Create object with dynamic dispatch
word = comtypes.client.CreateObject("Word.Application", dynamic=True)
word.Visible = True

# Create new document
doc = word.Documents.Add()
doc.Content.Text = "Hello from Python!"

# Close without saving
doc.Close(SaveChanges=False)
word.Quit()

Architecture

comtypes implements a comprehensive COM infrastructure with several key components:

  • COM Initialization: Automatic COM apartment initialization with configurable threading models
  • Object Creation: Multiple pathways for creating and accessing COM objects (ProgID, CLSID, moniker, active objects)
  • Interface Management: Type-safe interface definitions with automatic QueryInterface support
  • Type Library Integration: Automatic Python wrapper generation from COM type libraries
  • Event Handling: Connection point support for COM events and callbacks
  • Server Support: Framework for implementing COM servers in Python
  • Error Handling: Comprehensive HRESULT error code management and exception mapping

Capabilities

Core COM Functionality

Essential COM operations including object creation, interface management, apartment initialization, and GUID handling. Provides the foundation for all COM interactions.

def CoCreateInstance(clsid, interface=None, clsctx=None, machine=None): ...
def CoGetObject(displayname, interface=None): ...
def CoInitializeEx(flags=None): ...
def CoUninitialize(): ...
class GUID: ...
class IUnknown: ...

Core COM

Client API

High-level functions for consuming COM objects and services. Includes object creation, type library processing, event handling, and dynamic dispatch support.

def CreateObject(progid, clsctx=None, machine=None, interface=None, dynamic=False): ...
def GetActiveObject(progid, interface=None, dynamic=False): ...
def GetEvents(obj, sink, interface=None): ...
def GetModule(tlib): ...
class Constants: ...

Client API

Automation and IDispatch

COM automation support with VARIANT handling, dispatch interfaces, and type conversion. Enables interaction with automation servers like Microsoft Office applications.

class IDispatch: ...
class VARIANT: ...
def BSTR(value): ...
# VARIANT type constants
VT_EMPTY: int
VT_BSTR: int
VT_DISPATCH: int

Automation

Server Development

Framework for implementing COM servers in Python, including class factories, registration utilities, and connection point support for events.

class IClassFactory: ...
def RegisterActiveObject(comobj, weak=True): ...
class COMObject: ...
class CoClass: ...

Server Development

Utilities and Support

Helper functions, type conversion utilities, SafeArray support, and specialized interfaces for persistence, shell integration, and type library processing.

def byref_at(obj, offset): ...
def _midlSAFEARRAY(itemtype): ...
class IPersist: ...
class IShellLinkW: ...

Utilities

Types

Core Types

class GUID:
    """Globally unique identifier for COM interfaces and classes."""
    def __init__(self, name: str = None): ...
    def __str__(self) -> str: ...
    def __eq__(self, other) -> bool: ...
    @classmethod
    def from_progid(cls, progid: str) -> 'GUID': ...
    @classmethod
    def create_new(cls) -> 'GUID': ...
    def as_progid(self) -> str: ...

class COMError(Exception):
    """Exception raised for COM operation failures."""
    def __init__(self, hresult: int, text: str = None, details: tuple = None): ...

class ReturnHRESULT(Exception):
    """Exception for returning HRESULT codes from COM method implementations."""
    def __init__(self, hresult: int, text: str = None): ...

COM Context Constants

CLSCTX_INPROC_SERVER: int  # 1
CLSCTX_INPROC_HANDLER: int  # 2
CLSCTX_LOCAL_SERVER: int  # 4
CLSCTX_REMOTE_SERVER: int  # 16
CLSCTX_INPROC: int  # 3
CLSCTX_SERVER: int  # 5
CLSCTX_ALL: int  # 7

COM Initialization Constants

COINIT_APARTMENTTHREADED: int  # 2
COINIT_MULTITHREADED: int  # 0
COINIT_DISABLE_OLE1DDE: int  # 4
COINIT_SPEED_OVER_MEMORY: int  # 8