# Python XPCOM Package Architecture

## Architecture

Much of the design for the Python XPCOM Package has been borrowed from the Python MS-COM extensions in win32com. Most of the major limitations and drawbacks in the win32com design have been addressed, mainly "auto-wrapping" of interface objects, which is not supported by win32com.

Like win32com, this architecture includes the concept of client COM and server COM.

Client COM:

- calls other interfaces
- is supported by PyInterfaces implemented in C++, which assists in making the COM calls
- is supported by PyGateways, which assists in receiving external COM calls and dispatching them to the correct Python object
- is supported in the xpcom/client package

Server COM:

- implements interfaces for use by other XPCOM applications or components
- is supported in the xpcom/server package

The XPConnect framework is very powerful, and far exceeds what COM's IDispatch can offer. Thus, we are able to get by with far fewer interfaces supported in the C++ level, and defer most things to the Python code that uses XPConnect. As a result, the requirement for a huge number of interfaces to exist in the .pyd does not exist. There are, however, a number of interfaces that do require native C++ support: these are interfaces required to "boot" the XPConnect support (i.e., the interfaces that are used to get information about interfaces), and also two gateways that need to work without interface information available. This last requirement is due to the XPCOM shutdown-ordering - it may be a bug, but is not an unreasonable amount of code anyway.

Auto-wrapping of COM objects is supported by both client COM and server COM. For client COM, auto-wrapping means that the Python programmer always sees Python "component" objects, rather than raw C++ interface objects; to the user, it all appears to "just work". This is a major source of frustration in the win32com framework.

For server COM, auto-wrapping means that you can pass Python instances wherever a COM object is expected. If the Python instance supports COM interfaces, by virtue of having a _com_interfaces_ attribute that lists the interface requested, it will be automatically wrapped in the correct COM object.

Error Handling: The C++ framework has good error handling support, and uses the XPCOM console service to log debug messages, Python exceptions and tracebacks. win32com does not have good exception/traceback support at the C++ level, mainly because COM does not define a service like the console where debug messages can go. This does mean that in Mozilla release builds, these debug messages are likely to be lost, but the --console command line option to a release Mozilla will get them back. Therefore, the other error-support utilities, such as the error callbacks made on the policy object, may be used.

Component Loader, Modules and Factories: XPCOM has the concept of a component loader - a module used to load all components of a particular type. For example, the moz.jsloader.1 component loads all the JavaScript components. Similarly, the moz.pyloader.1 component loads all Python components. However, unlike JavaScript, the Python component loader is actually implemented in Python itself! Since the Python component loader can not be used to load itself, this component has some special code, pyloader.dll, to boot-strap itself.

This means is that all XPCOM components, including the Python loader itself and all XPCOM module and factory interfaces, are implemented in Python. There are no components or interfaces implemented purely in C++ in this entire package!