gh-127255: Make `CopyComPointer` public and add to `ctypes` doc. (GH-127275)

diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index bd9529db9ee65a0bdfd63ca08e87b17367172183..bd88fa377fb39d7033663864027e177aa0fb0060 100644 (file)
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -1949,6 +1949,24 @@ Utility functions
    It behaves similar to ``pointer(obj)``, but the construction is a lot faster.
 
 
+.. function:: CopyComPointer(src, dst)
+
+   Copies a COM pointer from *src* to *dst* and returns the Windows specific
+   :c:type:`!HRESULT` value.
+
+   If *src* is not ``NULL``, its ``AddRef`` method is called, incrementing the
+   reference count.
+
+   In contrast, the reference count of *dst* will not be decremented before
+   assigning the new value. Unless *dst* is ``NULL``, the caller is responsible
+   for decrementing the reference count by calling its ``Release`` method when
+   necessary.
+
+   .. availability:: Windows
+
+   .. versionadded:: next
+
+
 .. function:: cast(obj, type)
 
    This function is similar to the cast operator in C. It returns a new instance

diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
index 7bb9657e6ed9dad1ad3a4207cdbae97ee007acb4..52a6d6e43401940a0831296c2f17848b65315625 100644 (file)
--- a/Doc/whatsnew/3.14.rst
+++ b/Doc/whatsnew/3.14.rst
@@ -313,9 +313,12 @@ ctypes
   to help match a non-default ABI.
   (Contributed by Petr Viktorin in :gh:`97702`.)
 
-* The :exc:`~ctypes.COMError` exception is now public.
+* On Windows, the :exc:`~ctypes.COMError` exception is now public.
   (Contributed by Jun Komoda in :gh:`126686`.)
 
+* On Windows, the :func:`~ctypes.CopyComPointer` function is now public.
+  (Contributed by Jun Komoda in :gh:`127275`.)
+
 datetime
 --------
 

diff --git a/Lib/ctypes/__init__.py b/Lib/ctypes/__init__.py
index ac6493892068e9109e39d7a16958af149378d88a..2f2b0ca9f38633acd24ab803f5494d7f122745d6 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 COMError, FormatError
+    from _ctypes import COMError, CopyComPointer, FormatError
 
 DEFAULT_MODE = RTLD_LOCAL
 if _os.name == "posix" and _sys.platform == "darwin":

diff --git a/Lib/test/test_ctypes/test_win32_com_foreign_func.py b/Lib/test/test_ctypes/test_win32_com_foreign_func.py
index 8d217fc17efa02c50b59e1fad25bb8ebfce30171..7e54f8f6c31d33f9aa6288775498440cff3b8c01 100644 (file)
--- a/Lib/test/test_ctypes/test_win32_com_foreign_func.py
+++ b/Lib/test/test_ctypes/test_win32_com_foreign_func.py
@@ -9,8 +9,7 @@ if sys.platform != "win32":
     raise unittest.SkipTest("Windows-specific test")
 
 
-from _ctypes import COMError, CopyComPointer
-from ctypes import HRESULT
+from ctypes import COMError, CopyComPointer, HRESULT
 
 
 COINIT_APARTMENTTHREADED = 0x2

diff --git a/Misc/NEWS.d/next/Library/2024-11-25-15-02-44.gh-issue-127255.UXeljc.rst b/Misc/NEWS.d/next/Library/2024-11-25-15-02-44.gh-issue-127255.UXeljc.rst
new file mode 100644 (file)
index 0000000..9fe7815
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2024-11-25-15-02-44.gh-issue-127255.UXeljc.rst
@@ -0,0 +1,2 @@
+The :func:`~ctypes.CopyComPointer` function is now public.
+Previously, this was private and only available in ``_ctypes``.