comtypes

The IUnknown metaclass automatically generates Python methods based on the _methods_ description in an interface. The behavior depends on how the method was described in the IDL:

• STDMETHOD: Only argument types and return types are known. The generated code performs basic type checking and returns the raw COM return value.
• COMMETHOD: Provides rich metadata including argument names and direction (in, out, or in/out).
  • For out parameters, the metaclass manages containers.
  • If a method has exactly one out parameter, the generated Python method returns that value directly.
  • If a method has multiple out parameters, the generated Python method returns them as a tuple.
  • Note: When out parameters are present, the native HRESULT is not returned by the generated method; instead, the values are returned.

To override a generated method while still accessing the underlying COM functionality, implement your custom method with the standard name (e.g., GetGUID) and call the automatically generated version using the _ prefix (e.g., self._GetGUID(...)).

class IProvideClassInfo2(IProvideClassInfo):
    # Manually implementing GetGUID to provide a default value
    def GetGUID(self, dwGuidKind=1):
        # Accessing the raw functionality generated by the metaclass
        return self._GetGUID(dwGuidKind)

You can implement COM methods using two different strategies. comtypes determines which strategy to use by inspecting the second parameter (immediately after self) of your Python method:

Low-level implementation

Trigger: The second parameter is named this.

• Arguments: (self, this, *args).
• this parameter: Receives None or the integer address of the COM object. Usually ignored.
• Parameters: [in] parameters are native Python objects; [out] or [out, retval] parameters are passed as ctypes pointers. You must write results into these pointers.
• Return value: Must return a numerical HRESULT (e.g., 0 for S_OK or None).

High-level implementation

Trigger: The second parameter is missing or is NOT named this.

• Arguments: (self, *args).
• Parameters: [in] parameters are native Python objects.
• Return value: If there is a single [out] or [out, retval] parameter, return the value directly. If there are multiple, return a tuple. If there are no [out] parameters, the return value is ignored.

Choosing a strategy: Use low-level if you need to return specific HRESULT error codes. Use high-level for standard Pythonic code and ease of use.

# Low-level example
class MyObjectImpl(MyObject):
    def MyMethod(self, this, a, b, presult):
        presult[0] = a + b
        return 0  # Returns HRESULT

# High-level example
class MyObjectImpl(MyObject):
    def MyMethod(self, a, b):
        return a + b  # Returns value directly

To define a COM interface in comtypes, create a Python class that derives from comtypes.IUnknown or one of its subclasses.

Important Rules:

• Do not instantiate interface classes directly. They are templates used to create pointer instances. To use methods, you must call them from a POINTER(InterfaceClass) instance.
• Inheritance: Methods from the superclass (like IUnknown) are inherited automatically and should not be listed in the _methods_ attribute.
• Circular References: If a method references the interface class itself, define the _methods_ attribute after the class definition.

Required Class Attributes:

• _iid_: A comtypes.GUID instance representing the interface identifier.
• _methods_: A sequence describing the methods in VTable order.

Optional Attributes:

• _idlflags_: A sequence containing IDL flags.
• _case_insensitive_: Set to True if the interface supports case-insensitive attribute access.

from ctypes import *
from comtypes import IUnknown, GUID, COMMETHOD

class IMyInterface(IUnknown):
    _iid_ = GUID("{YOUR-GUID-HERE}")
    _methods_ = [
        COMMETHOD([], HRESULT, "MyMethod", (['in'], c_int, "arg1")),
    ]

While comtypes handles most conversions, some COM servers require specific VARIANT typecodes (e.g., an array of integers instead of a generic array of variants).

To satisfy these requirements, pass a Python array.array object with the appropriate typecode. The mapping between array.array typecodes and comtypes.automation VARIANT typecodes is as follows:

Note: NumPy arrays can also be used for this purpose.

import array
import comtypes.client

# Example: Using array.array to pass specific types to AutoCAD
app = comtypes.client.GetActiveObject("AutoCAD.Application")
ms = app.ActiveDocument.ModelSpace

# Passing a double array (VT_R8)
pt = array.array('d', [0, 0, 0])
point = ms.AddPoint(pt)

# Passing a short array (VT_I2)
point.SetXData(array.array("h", [1001, 1070]), ['Test_Application1', 600])

COM properties can be read-write, read-only, or write-only. They may require arguments.

Properties with arguments

To access properties that require arguments (named properties), use index notation.

Properties with optional arguments

Because Python syntax does not allow empty brackets [] for indexing, use one of the following patterns to access or set properties that have optional arguments:

1. To GET a property:

   • Call the property as a function: obj.Property()
   • Use an empty slice: obj.Property[:]
   • Use an empty tuple: obj.Property[()]

2. To SET a property:

   • Use an empty slice: obj.Property[:] = value
   • Use an empty tuple: obj.Property[()] = value
   • Direct assignment (if supported): obj.Property = value

import comtypes.client
from comtypes.gen.Excel import xlRangeValueDefault

xl = comtypes.client.CreateObject('Excel.Application')
xl.Workbooks.Add()

# Accessing a property with arguments using index notation
xl.Range["A1", "C1"].Value[xlRangeValueDefault] = (10, '20', 31.4)

# Accessing an optional property using the function call pattern
print(xl.Range["A1", "C1"].Value())

# Accessing/Setting an optional property using empty slice/tuple
print(xl.Range["A1", "C1"].Value[:])
xl.Range["A1", "C1"].Value[()] = (3, 2, 1)

To implement a COM server in comtypes, you must follow a three-step process:

1. Define the COM interface: Create an IDL (Interface Definition Language) file describing the coclass, the interface(s) it implements, and optional event interfaces. It is recommended to use dual interfaces and automation-compatible data types. Compile this IDL with the Microsoft MIDL compiler to generate a .tlb type library file.

2. Implement the Python class: Generate a wrapper module from the .tlb file using GetModule, then create a subclass of the generated coclass. You must provide registration attributes like _reg_threading_, _reg_progid_, and _reg_clsctx_.

3. Register and run: Use comtypes.server.register.UseCommandLine within your script's entry point and run the script with the /regserver flag to write the object to the Windows registry.

import comtypes
import comtypes.server.localserver
from comtypes.client import GetModule

# 1. Generate wrapper from TLB
GetModule('path\\to\\mytypelib.tlb')
from comtypes.gen.MyTypeLib import MyObject

# 2. Implement the class
class MyObjectImpl(MyObject):
    _reg_threading_ = "Both"
    _reg_progid_ = "MyTypeLib.MyObject.1"
    _reg_novers_progid_ = "MyTypeLib.MyObject"
    _reg_desc_ = "Simple COM server for testing"
    _reg_clsctx_ = comtypes.CLSCTX_INPROC_SERVER | comtypes.CLSCTX_LOCAL_SERVER
    _regcls_ = comtypes.server.localserver.REGCLS_MULTIPLEUSE

if __name__ == "__main__":
    from comtypes.server.register import UseCommandLine
    UseCommandLine(MyObjectImpl)