ctypes: Make COMError, mentioned in the "Function prototypes" section of documentation, public.

[junkmd]

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.

cpython/Doc/library/ctypes.rst

Lines 1793 to 1800 in 6293d00

	.. function:: prototype(vtbl_index, name[, paramflags[, iid]])
	:noindex:
	:module:
	Returns a foreign function that will call a COM method. *vtbl_index* is
	the index into the virtual function table, a small non-negative
	integer. *name* is name of the COM method. *iid* is an optional pointer to
	the interface identifier which is used in extended error reporting.

• 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