Illustration by Lia Avant

Taking Advantage of COM with Python

Microsoft's Common Object Model (COM) implements a cross-language object model. Using COM, you can write code in one programming language, like C++, and use that code in another programming language, such as Visual Basic (VB) or Python.

Indeed, Python has excellent support for COM. In fact, Python's support for COM is so good that COM can be used to extend Python. Python can both use and create COM objects. If you need to write a Python extension exclusively for Windows, strongly consider using COM.

To use COM in Python, you must install the Python Win32 extensions, which can be downloaded from http://sourceforge.net/projects/pywin32/. The pywin32 package comes in a nice installer package, so compiling from source isn't necessary.

The steps to use a COM object in Python are the same as any other programming language that support COM. First, you instantiate an object. Once instantiated, you use the properties, fields and methods of the COM object just as if they were part of regular Python objects.

To use a COM object in your Python code, start by running the makepy utility on the COM component that you'd like to use. This isn't a mandatory step, but it has at least two advantages: named constants defined in the typelib are available to you when you import the constants class, and if you're using the PyWin IDE, you'll get intellisense for the properties and methods of the component. (If you don't run makepy, you'll have to use numeric values in place of the named constants that you'd normally use for parameters and such.)

The easiest way to run makepy is through the PyWin IDE. Launch PyWin, and under the tools menu, choose makepy. This opens a simple little dialog that list all of the registed COM components on the system. Just choose the component you want to use.

Using a COM component in Python is nearly as simple as using the component in VB. After running makepy, import the COM support module:

import win32com.client as w32c

If you ran the makepy utility on the component, then the constants class has all of the named constants defined in the typelib:

from win32com.client import constants

Once the module is imported, you can instantiate the COM component simply:

Obj = w32c.Dispatch(r"Object.name")

To instantiate a COM component, you need to know the class name of the component. You can find the component's class name in the documentation for the component or by looking at the registry entries for the object, if you know the Globally Unique ID (GUID). However, If you run the makepy utility on the component then both the name of the component and its GUID are listed in the generated Python file.

Once you've instantiated a component, you have access to all the properties and methods of that component. For example the following code calls the load and transform methods of the MSXML control:

xmldoc = w32c.Dispatch(r"Msxml2.DOMDocument")
rval = xmldoc.load(xml)
xmldoc.transformNode(xsldoc)

The file transform.py that accompanies this article is a complete example that demonstrates how to use the MSXML COM component. To use that example, you need to have the MSXML components installed. (MSXML is installed along with Internet Explorer, so it is usually present on most systems.)

Using COM, you can drive other applications such as Microsoft Office. For instance, Python can be combined with MS Word to create document management systems. Python COM integration is extremely powerful in this regard.

On most Windows systems there are numerous COM objects installed. You can browse through them using the makepy utility. Anything that shows up in the makepy utility can be used in Python.

Let's look now at what may be the coolest part of Python's COM integration.

Python comes with a large library of modules that often do not have equivalents in other languages. By using Python to create COM objects, it is easy to expose some of these modules to other languages.

Creating COM objects in other languages, such as C++, requires a lot of code and knowledge. It also requires that you be familiar with IDL, an entirely separate language. Contrast that to creating a COM object in Python:

class MD5Obj:
   _public_methods_ = ["Update", "Hash", "Hex"]
   _reg_progid_ = "Python.MD5"
   _reg_clsid_ = "{895E2BD0-0DA7-11D9-9669-0800200C9A66}"
   MD5 = None
   def __init__ (self):
      self.MD5 = md5.new()
      return
   def Update (self, val):
      self.MD5.update(val)
      return
      def Hash (self):
      return self.MD5.digest()
   def Hex (self):
      return self.MD5.hexdigest()

Notice, that there are no non-Python constructs, no IDL, and no funny preprocessor macros —just plain old Python. The code wraps the MD5 module and exposes the methods that it needs. Something else to notice is that this class does not inherit from some magical COM class.

What makes this a COM class are the three fields _public_methods_, _reg_progid_, and _reg_clsid_.

• _public_methods_ informs pyWin which methods you want publicly exposed. Usually you want only the methods that are part of your public interface listed in this field.
• _reg_progid_ is just a string that gives the object a semi-unique name, that can be used to instantiate the object.
• The _reg_clsid_ field is a GUID (Globally Unique ID) that is the actual unique name of the object. This is also called the class ID. The class ID can be used to instantiate an object but there are various reasons not to do this. It's better to use the program ID for this. There are a number of utilities to create GUIDs available on the Internet, as well as tools available in various development environments to create GUIDs.

To have the COM object available in Windows, you have to register it. The easiest way to do this is just create a little bit of code that registers the object when the script file runs:

if __name__ == '__main__':
   import win32com.server.register
   win32com.server.register.UseCommandLine(MD5Obj)

That's it. Just run the script and the object is registered. No separate utility (like regsrv32) to worry about. You can't get much simpler than that.

Using the Python COM object from another language is just like using any other COM object. Here is some Python code to instantiate and use the COM object above:

var md5 = new ActiveXObject("Python.md5");
md5.Update("This is a test");
WScript.Echo(md5.Hash());
Wscript.Echo(md5.Hex());

The full example is available in the MD5Obj.py script.

Even though this article presents a simple example, everything shown here holds true for complex object hierarchies. You have full access to COM's facilities. You can use attributes, read only attributes, methods, and so on. You've got access to it all, as well as the full power of Python. It's all as easy as (wait for it...) pie.

Consider using Python to prototype your objects before jumping into C++. This gives you the chance to evaluate your object interfaces without having to go through the build and register step each time you change something. Who knows, you may find that there is no reason to implement the objects in C++ after all.

 Py is committed to bringing you great Python Articles.