Documentation

I have been part of a project that handles COM with Python for several years now.

When I first joined the project, _ctypes.COMError was a "mysterious error" to me.

Over time, by implementing error handling within that project, contributing to comtypes, and adding _ctypes.pyi to typeshed, I deepened my understanding of this error.
Yet, I always wondered why ctypes documentation never mentioned COMError.

While reading through the function prototype section and working on gh-126384 and gh-126610, I realized that the section on "extended error reporting" may have implied COMError.

• If a foreign function generated from a function prototype without passing an iid fails to call a COM method, a WindowsError with the winerror attribute is raised.
• On the other hand, if the foreign function is generated with an iid and fails to call, a COMError is raised, providing more "extended error reporting" with the following attributes:
  • hresult: an HRESULT value indicating an error, with any integer other than S_OK = 0
  • text: an error message string
  • details: a tuple of length 5 representing Description, Source, HelpFile, HelpContext, and scode

Clearly mentioning this behavior would benefit not only those working with comtypes but also anyone involved in projects where COMError may arise.
At the very least, it would guide developers encountering this error to search hresult as a Windows error code.

Referring to the COMError exception type as a private element such as _CData and specific to Windows such as HRESULT could help prevent developers from feeling it’s a "mysterious error" as I once did.

Any opinions would be appreciated.

Linked PRs

• gh-126615: Make COMError public and add to ctypes doc. #126686