0
# comtypes
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: comtypes
7
- **Language**: Python
8
- **Platform**: Windows (COM technology specific)
9
- **Installation**: `pip install comtypes`
10

11
## Core Imports
12

13
```python
14
import comtypes
15
```
16

17
For high-level COM automation:
18

19
```python
20
from comtypes.client import CreateObject, GetActiveObject, GetEvents
21
```
22

23
For automation types and interfaces:
24

25
```python
26
from comtypes.automation import VARIANT, IDispatch
27
```
28

29
For server development:
30

31
```python
32
from comtypes.server import IClassFactory
33
```
34

35
## Basic Usage
36

37
```python
38
import comtypes.client
39

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

44
# Create a new workbook
45
wb = xl.Workbooks.Add()
46
ws = wb.ActiveSheet
47

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

52
# Save and close
53
wb.SaveAs("C:\\temp\\example.xlsx")
54
wb.Close()
55
xl.Quit()
56
```
57

58
```python
59
# Using dispatch for late binding
60
import comtypes.client
61

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

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

70
# Close without saving
71
doc.Close(SaveChanges=False)
72
word.Quit()
73
```
74

75
## Architecture
76

77
comtypes implements a comprehensive COM infrastructure with several key components:
78

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

87
## Capabilities
88

89
### Core COM Functionality
90

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

93
```python { .api }
94
def CoCreateInstance(clsid, interface=None, clsctx=None, machine=None): ...
95
def CoGetObject(displayname, interface=None): ...
96
def CoInitializeEx(flags=None): ...
97
def CoUninitialize(): ...
98
class GUID: ...
99
class IUnknown: ...
100
```
101

102
[Core COM](./core-com.md)
103

104
### Client API
105

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

108
```python { .api }
109
def CreateObject(progid, clsctx=None, machine=None, interface=None, dynamic=False): ...
110
def GetActiveObject(progid, interface=None, dynamic=False): ...
111
def GetEvents(obj, sink, interface=None): ...
112
def GetModule(tlib): ...
113
class Constants: ...
114
```
115

116
[Client API](./client-api.md)
117

118
### Automation and IDispatch
119

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

122
```python { .api }
123
class IDispatch: ...
124
class VARIANT: ...
125
def BSTR(value): ...
126
# VARIANT type constants
127
VT_EMPTY: int
128
VT_BSTR: int
129
VT_DISPATCH: int
130
```
131

132
[Automation](./automation.md)
133

134
### Server Development
135

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

138
```python { .api }
139
class IClassFactory: ...
140
def RegisterActiveObject(comobj, weak=True): ...
141
class COMObject: ...
142
class CoClass: ...
143
```
144

145
[Server Development](./server.md)
146

147
### Utilities and Support
148

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

151
```python { .api }
152
def byref_at(obj, offset): ...
153
def _midlSAFEARRAY(itemtype): ...
154
class IPersist: ...
155
class IShellLinkW: ...
156
```
157

158
[Utilities](./utilities.md)
159

160
## Types
161

162
### Core Types
163

164
```python { .api }
165
class GUID:
166
    """Globally unique identifier for COM interfaces and classes."""
167
    def __init__(self, name: str = None): ...
168
    def __str__(self) -> str: ...
169
    def __eq__(self, other) -> bool: ...
170
    @classmethod
171
    def from_progid(cls, progid: str) -> 'GUID': ...
172
    @classmethod
173
    def create_new(cls) -> 'GUID': ...
174
    def as_progid(self) -> str: ...
175

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

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

185
### COM Context Constants
186

187
```python { .api }
188
CLSCTX_INPROC_SERVER: int  # 1
189
CLSCTX_INPROC_HANDLER: int  # 2
190
CLSCTX_LOCAL_SERVER: int  # 4
191
CLSCTX_REMOTE_SERVER: int  # 16
192
CLSCTX_INPROC: int  # 3
193
CLSCTX_SERVER: int  # 5
194
CLSCTX_ALL: int  # 7
195
```
196

197
### COM Initialization Constants
198

199
```python { .api }
200
COINIT_APARTMENTTHREADED: int  # 2
201
COINIT_MULTITHREADED: int  # 0
202
COINIT_DISABLE_OLE1DDE: int  # 4
203
COINIT_SPEED_OVER_MEMORY: int  # 8
204
```