gh-126615: ctypes: Make COMError public (GH-126686)

Co-authored-by: Bénédikt Tran <[email protected]>

Author: junkmd

Doc/library/ctypes.rst

@@ -1707,12 +1707,6 @@ in :mod:`!ctypes`) which inherits from the private :class:`_CFuncPtr` class:
       and raise an exception if the foreign function call failed.
 
 
-.. exception:: ArgumentError
-
-   This exception is raised when a foreign function call cannot convert one of the
-   passed arguments.
-
-
 .. audit-event:: ctypes.set_exception code foreign-functions
 
    On Windows, when a foreign function call raises a system exception (for
@@ -1799,10 +1793,15 @@ different ways, depending on the type and number of the parameters in the call:
    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 *iid* is not specified, an :exc:`OSError` is raised if the COM method
+   call fails. If *iid* is specified, a :exc:`~ctypes.COMError` is raised
+   instead.
+
    COM methods use a special calling convention: They require a pointer to
    the COM interface as first argument, in addition to those parameters that
    are specified in the :attr:`!argtypes` tuple.
 
+
 The optional *paramflags* parameter creates foreign function wrappers with much
 more functionality than the features described above.
 
@@ -2741,3 +2740,39 @@ Arrays and pointers
 
         Returns the object to which to pointer points.  Assigning to this
         attribute changes the pointer to point to the assigned object.
+
+
+.. _ctypes-exceptions:
+
+Exceptions
+^^^^^^^^^^
+
+.. exception:: ArgumentError
+
+   This exception is raised when a foreign function call cannot convert one of the
+   passed arguments.
+
+
+.. exception:: COMError(hresult, text, details)
+
+   Windows only: This exception is raised when a COM method call failed.
+
+   .. attribute:: hresult
+
+      The integer value representing the error code.
+
+   .. attribute:: text
+
+      The error message.
+
+   .. attribute:: details
+
+      The 5-tuple ``(descr, source, helpfile, helpcontext, progid)``.
+
+      *descr* is the textual description.  *source* is the language-dependent
+      ``ProgID`` for the class or application that raised the error.  *helpfile*
+      is the path of the help file.  *helpcontext* is the help context
+      identifier.  *progid* is the ``ProgID`` of the interface that defined the
+      error.
+
+   .. versionadded:: next

Doc/whatsnew/3.14.rst

@@ -273,6 +273,9 @@ ctypes
   to help match a non-default ABI.
   (Contributed by Petr Viktorin in :gh:`97702`.)
 
+* The :exc:`~ctypes.COMError` exception is now public.
+  (Contributed by Jun Komoda in :gh:`126686`.)
+
 datetime
 --------
 

Lib/ctypes/__init__.py

@@ -19,7 +19,7 @@
     raise Exception("Version number mismatch", __version__, _ctypes_version)
 
 if _os.name == "nt":
-    from _ctypes import FormatError
+    from _ctypes import COMError, FormatError
 
 DEFAULT_MODE = RTLD_LOCAL
 if _os.name == "posix" and _sys.platform == "darwin":

Lib/test/test_ctypes/test_win32.py

@@ -65,15 +65,16 @@ def test_PARAM(self):
                              sizeof(c_void_p))
 
     def test_COMError(self):
-        from _ctypes import COMError
+        from ctypes import COMError
         if support.HAVE_DOCSTRINGS:
             self.assertEqual(COMError.__doc__,
                              "Raised when a COM method call failed.")
 
-        ex = COMError(-1, "text", ("details",))
+        ex = COMError(-1, "text", ("descr", "source", "helpfile", 0, "progid"))
         self.assertEqual(ex.hresult, -1)
         self.assertEqual(ex.text, "text")
-        self.assertEqual(ex.details, ("details",))
+        self.assertEqual(ex.details,
+                         ("descr", "source", "helpfile", 0, "progid"))
 
         self.assertEqual(COMError.mro(),
                          [COMError, Exception, BaseException, object])

Misc/NEWS.d/next/Library/2024-11-19-14-34-05.gh-issue-126615.LOskwi.rst

@@ -0,0 +1,2 @@
+The :exc:`~ctypes.COMError` exception is now public.
+Previously, this was private and only available in ``_ctypes``.