Tuesday, 24 August 2010

COM / DCOM In Python : The comtypes library

There are all kinds of crazy reasons you might want to use COM in Python. There are two main libraries for doing so. If you can use pywin32, then do- its high level, Pythonic and relatively functional. If you want to instantiate Word, or Excel, call a few methods, pass some simple data in, get some simple data back, fill your boots:

For more hardcore COM stuff you need to use the much lower level and partly undocumented comtypes library. The following bullets define "hardcore":
  • Subscribing to a COM event notification sink.
  • Building your own COM server (are you mad?)
  • Sending and receiving more complex datatypes.
It was my strong desire to automate certain tasks my group is responsible for by creating a DCOM client to hook into our management agents on the several hundred servers in our datacenter. This required an event sink.

I don't want to be unfair to comtypes, it is a great library, and when it works is very satisfying and robust. The main problems are the gaps in documentation. So without further ado, here's my pointers on using comtypes.

Download it and give it a try. Python 3.0 is unsupported afaik.
Do read the existing documentation. Carefully, what exists is of good quality.
Use the mailing list archive. Seriously, its the only way forward.
Have the IDL handy. The IDL is the file which defines the COM interfaces for your object, which the TypeLib is generated from. Most likely, if you need to use comtypes this file will be available to you, and will be a vital reference.

Turn on logging. If you're having issues you can turn on comtypes logging.

Read the source of comtypes. Once nice thing about Python is the source code is very readable. There are some useful comments in there also. On my machine the source can be found:
  • C:\Python26\Lib\site-packages\comtypes
Files which I found of interest were __init__.py, automation.py (types) and client._events.py (for events stuff).

Understand the type coercion. Much of the work that comtypes does for you is in the type coercion. If you get stuck wondering why your specific type of VARIANT is not getting coerced quite how you expected then  take a look in automation.py, and read the following Mailing list post (which should really be in the docs):
Keep your Sink in scope. This may be because I'm an idiot, but I was declaring my "advise" object in a constructor and then not keeping it. Make sure your advise object is still in scope when you call PumpEvents().

Understand the domain. Chances are you are going to have to learn about the bizarre world of C++ and COM. Frankly COM could only ever have seemed to make sense to a C++ programmer. Make sure you at least have a hazy notion of the following concepts, ideally in their C++ sense:
  • Interface
  • Pointer
  • Structure
  • Array
Also, realize why COM came about. Back in the day Windows had "dll hell" so Microsoft wanted a "code registry" which allowed for multiple versions and implementations, rather than just a system folder full of DLLs. Java was on the horizon with the idea of the "component model" and "code reuse", and Microsoft needed to compete. RAD languages such as Delphi were getting big too - so Visual Basic compatibility was another talking point. Server side Software Engineering problems which Windows Server was being utilized to solve were getting larger than a single machine: so it made sense to whack a bit of RPC in the mix (DCOM).

Built on ctypes. Be mindful the comtypes is build upon ctypes, especially when you get into type based confusion the docs there can be very enlightening.


  1. Excellent summary !

  2. I have written a python script for event handling of Microsoft Outlook using comtypes library ...
    My code works fine for Outlook 2007.But for Outlook 2003 it giving some error in the python file C:\Python26\Lib\site-packages\comtypes\client\_events.py ....error can't determine source interface ..
    Please reply @ "usharma01@gmail.com" as soon as possible

  3. Thanks, very helpful.

  4. Although it didn't give code examples/tutorials (that we long for), the forewarning on this article about how to properly use/master comtypes are tremendously helpful