gh-127369: Deprecate ctypes.DllGetClassObject and ctypes.DllCanUnloadNow

Doc/deprecations/pending-removal-in-3.19.rst

@@ -0,0 +1,9 @@
+Pending removal in Python 3.19
+------------------------------
+
+* :mod:`ctypes`:
+
+  * :func:`~ctypes.DllGetClassObject` and :func:`~ctypes.DllCanUnloadNow`
+    are deprecated and will be removed in Python 3.19.
+    Their use for implementing in-process COM servers is unclear;
+    discussion about replacements and use cases is welcome in :gh:`127369`.

Doc/library/ctypes.rst

@@ -2008,24 +2008,6 @@ Utility functions
    .. audit-event:: ctypes.create_unicode_buffer init,size ctypes.create_unicode_buffer
 
 
-.. function:: DllCanUnloadNow()
-
-   This function is a hook which allows implementing in-process
-   COM servers with ctypes.  It is called from the DllCanUnloadNow function that
-   the _ctypes extension dll exports.
-
-   .. availability:: Windows
-
-
-.. function:: DllGetClassObject()
-
-   This function is a hook which allows implementing in-process
-   COM servers with ctypes.  It is called from the DllGetClassObject function
-   that the ``_ctypes`` extension dll exports.
-
-   .. availability:: Windows
-
-
 .. function:: find_library(name)
    :module: ctypes.util
 
@@ -2826,3 +2808,25 @@ Exceptions
    .. availability:: Windows
 
    .. versionadded:: next
+
+
+Deprecated API
+^^^^^^^^^^^^^^
+
+.. function:: DllCanUnloadNow()
+              DllGetClassObject()
+
+   These functions are hooks which allowed implementing in-process
+   COM servers with ctypes.
+   To function, they required a third-party library, such as ``comtypes``,
+   along with third-party build/release tooling.
+
+   As of 2024, the state of tooling for in-process COM servers is unclear,
+   and is being discussed at :gh:`127369`.
+
+   Note that these functions will import and use the ``comtypes``
+   library, if it is installed.
+
+   .. availability:: Windows
+
+   .. deprecated-removed:: next 3.19

Doc/whatsnew/3.14.rst

@@ -708,6 +708,8 @@ Deprecated
 
 .. include:: ../deprecations/pending-removal-in-3.16.rst
 
+.. include:: ../deprecations/pending-removal-in-3.19.rst
+
 .. include:: ../deprecations/pending-removal-in-future.rst
 
 Removed

Lib/ctypes/__init__.py

@@ -2,6 +2,7 @@
 
 import os as _os, sys as _sys
 import types as _types
+import warnings
 
 __version__ = "1.1.0"
 
@@ -564,6 +565,7 @@ def wstring_at(ptr, size=-1):
 
 if _os.name == "nt": # COM stuff
     def DllGetClassObject(rclsid, riid, ppv):
+        warnings._deprecated("ctypes.DllGetClassObject", remove=(3, 19))
         try:
             ccom = __import__("comtypes.server.inprocserver", globals(), locals(), ['*'])
         except ImportError:
@@ -572,12 +574,14 @@ def DllGetClassObject(rclsid, riid, ppv):
             return ccom.DllGetClassObject(rclsid, riid, ppv)
 
     def DllCanUnloadNow():
+        warnings._deprecated("ctypes.DllCanUnloadNow", remove=(3, 19))
         try:
             ccom = __import__("comtypes.server.inprocserver", globals(), locals(), ['*'])
         except ImportError:
             return 0 # S_OK
         return ccom.DllCanUnloadNow()
 
+
 from ctypes._endian import BigEndianStructure, LittleEndianStructure
 from ctypes._endian import BigEndianUnion, LittleEndianUnion
 

Lib/test/test_ctypes/test_win32.py

@@ -7,8 +7,10 @@
 from ctypes import (CDLL, Structure, POINTER, pointer, sizeof, byref,
                     _pointer_type_cache,
                     c_void_p, c_char, c_int, c_long)
+import _ctypes
 from test import support
 from test.support import import_helper
+from test.support import warnings_helper
 from ._support import Py_TPFLAGS_DISALLOW_INSTANTIATION, Py_TPFLAGS_IMMUTABLETYPE
 
 
@@ -148,6 +150,28 @@ class RECT(Structure):
         # to not leak references, we must clean _pointer_type_cache
         del _pointer_type_cache[RECT]
 
+@unittest.skipUnless(sys.platform == "win32", 'Windows-specific test')
+class InprocessCallbacks(unittest.TestCase):
+    def test_deprecated_py_functions(self):
+        with import_helper.isolated_modules():
+            sys.modules['comtypes'] = None
+            with warnings_helper.check_warnings((".*3.19", DeprecationWarning)):
+                self.assertEqual(ctypes.DllCanUnloadNow(), 0)
+            with warnings_helper.check_warnings((".*3.19", DeprecationWarning)):
+                self.assertLess(ctypes.DllGetClassObject(0, 0, 0), 0)
+
+    def test_deprecated_dll_functions(self):
+        """C wrappers should warn, even with replaced hooks"""
+        support.patch(self, ctypes, 'DllCanUnloadNow', lambda: 1234)
+        support.patch(self, ctypes, 'DllGetClassObject', lambda *args: 1234)
+        with import_helper.isolated_modules():
+            sys.modules['comtypes'] = None
+            ctypes_dll = ctypes.WinDLL(_ctypes.__file__)
+            with warnings_helper.check_warnings((".*3.19", DeprecationWarning)):
+                self.assertEqual(ctypes_dll.DllCanUnloadNow(), 1234)
+            with warnings_helper.check_warnings((".*3.19", DeprecationWarning)):
+                self.assertEqual(ctypes_dll.DllGetClassObject(0, 0, 0), 1234)
+
 
 if __name__ == '__main__':
     unittest.main()

Misc/NEWS.d/next/Library/2024-12-10-15-43-51.gh-issue-127369.OAU_1d.rst

@@ -0,0 +1,2 @@
+Deprecate the functions :func:`ctypes.DllGetClassObject` and
+:func:`ctypes.DllCanUnloadNow`; plan their removal for Python 3.19.

Modules/_ctypes/callbacks.c

@@ -489,8 +489,22 @@ long Call_GetClassObject(REFCLSID rclsid, REFIID riid, LPVOID *ppv)
     long retval;
     static PyObject *context;
 
-    if (context == NULL)
+    if (context == NULL) {
         context = PyUnicode_InternFromString("_ctypes.DllGetClassObject");
+    }
+    if (!context) {
+        PyErr_WriteUnraisable(NULL);
+        return E_FAIL;
+    }
+
+    if (PyErr_WarnEx(
+        PyExc_DeprecationWarning,
+        "GetClassObject from _ctypes is deprecated and will be removed in Python 3.19",
+        1) < 0)
+    {
+        PyErr_WriteUnraisable(context);
+        return E_FAIL;
+    }
 
     func = _PyImport_GetModuleAttrString("ctypes", "DllGetClassObject");
     if (!func) {
@@ -565,8 +579,22 @@ long Call_CanUnloadNow(void)
     long retval;
     static PyObject *context;
 
-    if (context == NULL)
+    if (context == NULL) {
         context = PyUnicode_InternFromString("_ctypes.DllCanUnloadNow");
+    }
+    if (!context) {
+        PyErr_WriteUnraisable(NULL);
+        return E_FAIL;
+    }
+
+    if (PyErr_WarnEx(
+        PyExc_DeprecationWarning,
+        "DllCanUnloadNow from _ctypes is deprecated and will be removed in Python 3.19",
+        1) < 0)
+    {
+        PyErr_WriteUnraisable(context);
+        return E_FAIL;
+    }
 
     mod = PyImport_ImportModule("ctypes");
     if (!mod) {