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

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 99909de20ef439e98efdb34b5e42b1c1322d3670..8ed75d9b7560b9d54236be3d2ee6389a2174e718 100644 (file)
--- a/Doc/library/ctypes.rst
+++ b/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

diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
index cddcaafc461b20320754f79d6f7de0b3899b21dc..1f0b2454c0e8121d5e25f19da80b25e9759660d2 100644 (file)
--- a/Doc/whatsnew/3.14.rst
+++ b/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
 --------
 

diff --git a/Lib/ctypes/__init__.py b/Lib/ctypes/__init__.py
index 4a368f02d851c599c75d829913ffa9d95d6b76ed..ac6493892068e9109e39d7a16958af149378d88a 100644 (file)
--- a/Lib/ctypes/__init__.py
+++ b/Lib/ctypes/__init__.py
@@ -19,7 +19,7 @@ if __version__ != _ctypes_version:
     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":

diff --git a/Lib/test/test_ctypes/test_win32.py b/Lib/test/test_ctypes/test_win32.py
index 31919118670613e17da43463c11b8e8841093009..54b47dc28fbc735be12bde618f74d53d62217dc5 100644 (file)
--- a/Lib/test/test_ctypes/test_win32.py
+++ b/Lib/test/test_ctypes/test_win32.py
@@ -65,15 +65,16 @@ class TestWintypes(unittest.TestCase):
                              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])

diff --git a/Misc/NEWS.d/next/Library/2024-11-19-14-34-05.gh-issue-126615.LOskwi.rst b/Misc/NEWS.d/next/Library/2024-11-19-14-34-05.gh-issue-126615.LOskwi.rst
new file mode 100644 (file)
index 0000000..8c7a2ad
--- /dev/null
+++ b/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``.