From 292b2447284947b84f290435f58c79cb2e52cdef Mon Sep 17 00:00:00 2001 From: Jun Komoda <45822440+junkmd@users.noreply.github.com> Date: Mon, 25 Nov 2024 23:29:59 +0000 Subject: [PATCH 1/7] Make `CopyComPointer` public. --- Lib/ctypes/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/ctypes/__init__.py b/Lib/ctypes/__init__.py index ac6493892068e9..2f2b0ca9f38633 100644 --- a/Lib/ctypes/__init__.py +++ b/Lib/ctypes/__init__.py @@ -19,7 +19,7 @@ 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": From 3b1aac29654dd1dd3215c462027f46c7cff61958 Mon Sep 17 00:00:00 2001 From: Jun Komoda <45822440+junkmd@users.noreply.github.com> Date: Mon, 25 Nov 2024 23:29:59 +0000 Subject: [PATCH 2/7] Change import sources. --- Lib/test/test_ctypes/test_win32_com_foreign_func.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 8d217fc17efa02..7e54f8f6c31d33 100644 --- 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 @@ raise unittest.SkipTest("Windows-specific test") -from _ctypes import COMError, CopyComPointer -from ctypes import HRESULT +from ctypes import COMError, CopyComPointer, HRESULT COINIT_APARTMENTTHREADED = 0x2 From d6cabaa02a2f02c9acfff17fc4a9393c50009e1e Mon Sep 17 00:00:00 2001 From: Jun Komoda <45822440+junkmd@users.noreply.github.com> Date: Mon, 25 Nov 2024 23:41:29 +0000 Subject: [PATCH 3/7] Add `CopyComPointer` to `ctypes` doc. --- Doc/library/ctypes.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index f490f7563b58a5..2c4173030f9a37 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1949,6 +1949,23 @@ 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, even if *dst* is not ``NULL``, its reference count will not be + decremented before assigning the new value. You need to call its ``Release`` + to free it appropriately. + + .. availability:: Windows + + .. versionadded:: next + + .. function:: cast(obj, type) This function is similar to the cast operator in C. It returns a new instance From e742f17a0610103eda3cc8ab0805a6f0a5102d65 Mon Sep 17 00:00:00 2001 From: Jun Komoda <45822440+junkmd@users.noreply.github.com> Date: Mon, 25 Nov 2024 23:41:39 +0000 Subject: [PATCH 4/7] Add NEWS. --- .../next/Library/2024-11-25-15-02-44.gh-issue-127255.UXeljc.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 Misc/NEWS.d/next/Library/2024-11-25-15-02-44.gh-issue-127255.UXeljc.rst 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 index 00000000000000..9fe7815e93cf4f --- /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``. From df91824d1107b3b2563afcb4e0bc8d15f29ab949 Mon Sep 17 00:00:00 2001 From: Jun Komoda <45822440+junkmd@users.noreply.github.com> Date: Mon, 25 Nov 2024 23:41:47 +0000 Subject: [PATCH 5/7] Update `3.14.rst`. --- Doc/whatsnew/3.14.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index 0e4b9eb0cf0b9c..7b9a8a9bcb0fb7 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -312,6 +312,9 @@ ctypes * The :exc:`~ctypes.COMError` exception is now public. (Contributed by Jun Komoda in :gh:`126686`.) +* The :func:`~ctypes.CopyComPointer` function is now public. + (Contributed by Jun Komoda in :gh:`127275`.) + datetime -------- From 4f6b8c817e12af4f69b331bfdd6bd77daa0fd5c6 Mon Sep 17 00:00:00 2001 From: Jun Komoda <45822440+junkmd@users.noreply.github.com> Date: Sat, 30 Nov 2024 09:02:49 +0000 Subject: [PATCH 6/7] Update `CopyComPointer` section. --- Doc/library/ctypes.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 2c4173030f9a37..90e4af13c5f841 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1957,9 +1957,10 @@ Utility functions If *src* is not ``NULL``, its ``AddRef`` method is called, incrementing the reference count. - In contrast, even if *dst* is not ``NULL``, its reference count will not be - decremented before assigning the new value. You need to call its ``Release`` - to free it appropriately. + 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 From 0449742dc905de1ee1395b0cc3ac273437a87932 Mon Sep 17 00:00:00 2001 From: Jun Komoda <45822440+junkmd@users.noreply.github.com> Date: Sat, 30 Nov 2024 09:02:49 +0000 Subject: [PATCH 7/7] Add mentions of the platform to `3.14.rst`. --- Doc/whatsnew/3.14.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index 7b9a8a9bcb0fb7..10cd4f6ed1ecb1 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -309,10 +309,10 @@ 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`.) -* The :func:`~ctypes.CopyComPointer` function is now public. +* On Windows, the :func:`~ctypes.CopyComPointer` function is now public. (Contributed by Jun Komoda in :gh:`127275`.) datetime