0
# Client API
1
2
High-level functions for consuming COM objects and services. Provides convenient wrappers around low-level COM operations, automatic type library processing, event handling, and support for both early-bound and late-bound programming models.
3
4
## Capabilities
5
6
### Object Creation
7
8
High-level functions for creating and accessing COM objects with automatic interface detection and type library integration.
9
10
```python { .api }
11
def CreateObject(progid, clsctx=None, machine=None, interface=None, dynamic=False):
12
"""
13
Create COM object from ProgID with automatic wrapper generation.
14
15
Args:
16
progid (str): Programmatic identifier (e.g., "Excel.Application")
17
clsctx (int, optional): Class context (defaults to CLSCTX_ALL)
18
machine (str, optional): Remote machine name for DCOM
19
interface (type, optional): Specific interface to query for
20
dynamic (bool): Use dynamic dispatch wrapper if True
21
22
Returns:
23
COM object wrapper with strongly-typed methods and properties
24
or Dispatch wrapper if dynamic=True
25
26
Raises:
27
COMError: If object creation fails
28
"""
29
30
def GetActiveObject(progid, interface=None, dynamic=False):
31
"""
32
Get existing active COM object by ProgID.
33
34
Args:
35
progid (str): Programmatic identifier
36
interface (type, optional): Specific interface to query for
37
dynamic (bool): Use dynamic dispatch wrapper if True
38
39
Returns:
40
Active COM object wrapper
41
42
Raises:
43
COMError: If no active object found
44
"""
45
46
def CoGetObject(displayname, interface=None, dynamic=False):
47
"""
48
Create object from moniker display name.
49
50
Args:
51
displayname (str): Moniker display name (e.g., file path, URL)
52
interface (type, optional): Specific interface to query for
53
dynamic (bool): Use dynamic dispatch wrapper if True
54
55
Returns:
56
COM object from moniker
57
"""
58
59
def GetClassObject(clsid, clsctx=None, machine=None):
60
"""
61
Get class factory object for COM class.
62
63
Args:
64
clsid (GUID or str): Class identifier
65
clsctx (int, optional): Class context
66
machine (str, optional): Remote machine name
67
68
Returns:
69
IClassFactory interface for creating object instances
70
"""
71
```
72
73
### Interface Management
74
75
Functions for working with COM interfaces and automatic interface detection.
76
77
```python { .api }
78
def GetBestInterface(punk):
79
"""
80
Get the most specific interface for a COM object.
81
Attempts to find strongly-typed interface wrapper.
82
83
Args:
84
punk (IUnknown): COM object
85
86
Returns:
87
Most specific interface wrapper available
88
"""
89
90
# Alias for GetBestInterface
91
wrap = GetBestInterface
92
93
def _manage(obj, clsid, interface):
94
"""
95
Internal function for COM object lifecycle management.
96
97
Args:
98
obj: COM object to manage
99
clsid (GUID): Class identifier
100
interface (type): Interface type
101
102
Returns:
103
Managed COM object
104
"""
105
```
106
107
### Type Library Processing
108
109
Generate and manage Python wrapper modules from COM type libraries.
110
111
```python { .api }
112
def GetModule(tlib):
113
"""
114
Generate or retrieve Python wrapper module for type library.
115
116
Args:
117
tlib (str or ITypeLib): Type library path, ProgID, or ITypeLib interface
118
119
Returns:
120
Python module containing strongly-typed interface wrappers
121
122
Raises:
123
COMError: If type library cannot be loaded or processed
124
"""
125
```
126
127
### Constants Access
128
129
Access to type library constants through a convenient interface.
130
131
```python { .api }
132
class Constants:
133
"""Provides access to constants defined in type libraries."""
134
135
def __init__(self, obj):
136
"""
137
Create constants accessor for COM object.
138
139
Args:
140
obj: COM object with type library information
141
"""
142
143
def __getattr__(self, name):
144
"""
145
Get constant value by name.
146
147
Args:
148
name (str): Constant name
149
150
Returns:
151
Constant value
152
153
Raises:
154
AttributeError: If constant not found
155
"""
156
```
157
158
### Event Handling
159
160
Support for COM events and connection points with automatic event interface discovery.
161
162
```python { .api }
163
def GetEvents(obj, sink, interface=None):
164
"""
165
Set up COM event handling with connection points.
166
167
Args:
168
obj: COM object that fires events
169
sink: Event handler object with methods matching event signatures
170
interface (type, optional): Specific event interface (auto-detected if None)
171
172
Returns:
173
Connection point cookie for later disconnection
174
175
Raises:
176
COMError: If object doesn't support events or connection fails
177
"""
178
179
def ShowEvents(obj, interface=None):
180
"""
181
Display available events for debugging and development.
182
183
Args:
184
obj: COM object
185
interface (type, optional): Specific event interface
186
187
Prints event interface information to console
188
"""
189
190
def PumpEvents(timeout):
191
"""
192
Process pending COM events.
193
194
Args:
195
timeout (float): Maximum time to process events (seconds)
196
197
Returns:
198
None
199
"""
200
```
201
202
### Dynamic Dispatch
203
204
Late-bound COM object access through IDispatch interface with attribute-style syntax.
205
206
```python { .api }
207
class Dispatch:
208
"""Dynamic dispatch wrapper for late-bound COM object access."""
209
210
def __init__(self, obj):
211
"""
212
Create dynamic wrapper for COM object.
213
214
Args:
215
obj: COM object implementing IDispatch
216
"""
217
218
def __getattr__(self, name):
219
"""
220
Get property or method by name.
221
222
Args:
223
name (str): Property or method name
224
225
Returns:
226
Property value or callable method wrapper
227
"""
228
229
def __setattr__(self, name, value):
230
"""
231
Set property value by name.
232
233
Args:
234
name (str): Property name
235
value: New property value
236
"""
237
238
def __call__(self, *args, **kwargs):
239
"""
240
Invoke default method if object is callable.
241
242
Args:
243
*args: Method arguments
244
**kwargs: Named method arguments
245
246
Returns:
247
Method result
248
"""
249
```
250
251
### Parameter Wrapping
252
253
Utilities for handling output parameters and reference parameters in COM method calls.
254
255
```python { .api }
256
def wrap_outparam(obj):
257
"""
258
Wrap object for use as output parameter.
259
260
Args:
261
obj: Object to wrap
262
263
Returns:
264
Wrapped object suitable for output parameter
265
"""
266
```
267
268
## Usage Examples
269
270
### Basic Object Creation
271
272
```python
273
import comtypes.client
274
275
# Create Excel application
276
excel = comtypes.client.CreateObject("Excel.Application")
277
excel.Visible = True
278
279
# Create Word application with dynamic dispatch
280
word = comtypes.client.CreateObject("Word.Application", dynamic=True)
281
word.Visible = True
282
283
# Get active Excel instance if available
284
try:
285
active_excel = comtypes.client.GetActiveObject("Excel.Application")
286
print("Found active Excel instance")
287
except comtypes.COMError:
288
print("No active Excel instance")
289
```
290
291
### Working with Type Libraries
292
293
```python
294
import comtypes.client
295
296
# Generate wrapper module for Excel type library
297
xl = comtypes.client.GetModule("Excel.Application")
298
299
# Access Excel constants
300
print(xl.xlWorksheet) # Worksheet type constant
301
print(xl.xlChart) # Chart type constant
302
303
# Create strongly-typed Excel application
304
app = comtypes.client.CreateObject("Excel.Application", interface=xl.Application)
305
```
306
307
### Event Handling
308
309
```python
310
import comtypes.client
311
312
class ExcelEvents:
313
"""Event handler for Excel application events."""
314
315
def OnWorkbookOpen(self, workbook):
316
print(f"Workbook opened: {workbook.Name}")
317
318
def OnWorkbookBeforeClose(self, workbook, cancel):
319
print(f"Workbook closing: {workbook.Name}")
320
321
# Create Excel and set up events
322
excel = comtypes.client.CreateObject("Excel.Application")
323
handler = ExcelEvents()
324
325
# Connect event handler
326
connection = comtypes.client.GetEvents(excel, handler)
327
328
# Excel will now fire events to our handler
329
excel.Visible = True
330
wb = excel.Workbooks.Add()
331
```
332
333
### Dynamic vs Static Binding
334
335
```python
336
import comtypes.client
337
338
# Static binding - strongly typed, faster, IntelliSense support
339
excel_static = comtypes.client.CreateObject("Excel.Application")
340
excel_static.Visible = True
341
workbook = excel_static.Workbooks.Add() # Strongly typed
342
343
# Dynamic binding - flexible, slower, runtime resolution
344
excel_dynamic = comtypes.client.CreateObject("Excel.Application", dynamic=True)
345
excel_dynamic.Visible = True
346
workbook = excel_dynamic.Workbooks.Add() # Dynamic dispatch
347
```
348
349
### Working with Remote Objects
350
351
```python
352
import comtypes.client
353
354
# Create object on remote machine
355
remote_excel = comtypes.client.CreateObject(
356
"Excel.Application",
357
machine="remote-server.domain.com"
358
)
359
remote_excel.Visible = True
360
```
361
362
### Interface Wrapping
363
364
```python
365
import comtypes.client
366
367
# Get best interface for object
368
com_obj = some_com_object # Raw COM object
369
wrapped = comtypes.client.wrap(com_obj) # Get best wrapper
370
371
# Manual interface specification
372
specific_interface = comtypes.client.GetBestInterface(com_obj)
373
```
374
375
### Constants Access
376
377
```python
378
import comtypes.client
379
380
# Get Office constants
381
office = comtypes.client.GetModule("Microsoft Office 16.0 Object Library")
382
constants = comtypes.client.Constants(office)
383
384
# Access constants
385
print(constants.msoShapeRectangle)
386
print(constants.msoTextOrientationHorizontal)
387
388
# Or access directly from module
389
print(office.msoShapeRectangle)
390
```