From c58c3983535646b00cca3fc28285446392f5fe54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Delfino?= Date: Mon, 25 Jun 2018 23:14:18 -0300 Subject: [PATCH 1/4] bpo-4260: Document that ctypes.xFUNCTYPE are decorators --- Doc/library/ctypes.rst | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index edec764d640ed6..0687b3da4829e8 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1025,6 +1025,23 @@ As we can easily check, our array is sorted now:: 1 5 7 33 99 >>> +The function factories can be used as decorator factories, so we may as well +write:: + + >>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int)) + ... def py_cmp_func(*args): + ... (a, b,) = (t[0] for t in args) + ... print("py_cmp_func", a, b) + ... return a - b + ... + >>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func) + py_cmp_func 5 1 + py_cmp_func 33 99 + py_cmp_func 7 33 + py_cmp_func 1 7 + py_cmp_func 5 7 + >>> + .. note:: Make sure you keep references to :func:`CFUNCTYPE` objects as long as they @@ -1582,7 +1599,7 @@ type and the argument types of the function. .. function:: CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False) - The returned function prototype creates functions that use the standard C + Returns a function prototype which creates functions that use the standard C calling convention. The function will release the GIL during the call. If *use_errno* is set to true, the ctypes private copy of the system :data:`errno` variable is exchanged with the real :data:`errno` value before @@ -1592,7 +1609,7 @@ type and the argument types of the function. .. function:: WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False) - Windows only: The returned function prototype creates functions that use the + Windows only: Returns a function prototype which creates functions that use the ``stdcall`` calling convention, except on Windows CE where :func:`WINFUNCTYPE` is the same as :func:`CFUNCTYPE`. The function will release the GIL during the call. *use_errno* and *use_last_error* have the @@ -1601,9 +1618,12 @@ type and the argument types of the function. .. function:: PYFUNCTYPE(restype, *argtypes) - The returned function prototype creates functions that use the Python calling + Returns a function prototype which creates functions that use the Python calling convention. The function will *not* release the GIL during the call. +These factory functions can be used as decorator factories, and as such, be applied +to functions through the ``@wrapper`` syntax. + Function prototypes created by these factory functions can be instantiated in different ways, depending on the type and number of the parameters in the call: From 9a35dce3eab5b9ca84c1b3c38d693543f8ebcb25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Delfino?= Date: Tue, 26 Jun 2018 13:54:54 -0300 Subject: [PATCH 2/4] Fix indentation --- Doc/library/ctypes.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 0687b3da4829e8..970cb42e2fcacb 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1030,9 +1030,9 @@ write:: >>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int)) ... def py_cmp_func(*args): - ... (a, b,) = (t[0] for t in args) - ... print("py_cmp_func", a, b) - ... return a - b + ... (a, b,) = (t[0] for t in args) + ... print("py_cmp_func", a, b) + ... return a - b ... >>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func) py_cmp_func 5 1 From 4b297e96dddc9c755a4f6dcba7328c3255465f7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Delfino?= Date: Wed, 11 Jul 2018 09:44:55 -0300 Subject: [PATCH 3/4] Address Berker comments --- Doc/library/ctypes.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 970cb42e2fcacb..c8b35da9121691 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1029,10 +1029,9 @@ The function factories can be used as decorator factories, so we may as well write:: >>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int)) - ... def py_cmp_func(*args): - ... (a, b,) = (t[0] for t in args) - ... print("py_cmp_func", a, b) - ... return a - b + ... def py_cmp_func(a, b): + ... print("py_cmp_func", a[0], b[0]) + ... return a[0] - b[0] ... >>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func) py_cmp_func 5 1 @@ -1594,12 +1593,15 @@ Foreign functions can also be created by instantiating function prototypes. Function prototypes are similar to function prototypes in C; they describe a function (return type, argument types, calling convention) without defining an implementation. The factory functions must be called with the desired result -type and the argument types of the function. +type and the argument types of the function, and can be used as decorator +factories, and as such, be applied to functions through the ``@wrapper`` syntax. +See :ref:`ctypes-callback-functions` for examples. + .. function:: CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False) - Returns a function prototype which creates functions that use the standard C + The returned function prototype creates functions that use the standard C calling convention. The function will release the GIL during the call. If *use_errno* is set to true, the ctypes private copy of the system :data:`errno` variable is exchanged with the real :data:`errno` value before @@ -1609,7 +1611,7 @@ type and the argument types of the function. .. function:: WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False) - Windows only: Returns a function prototype which creates functions that use the + Windows only: The returned function prototype creates functions that use the ``stdcall`` calling convention, except on Windows CE where :func:`WINFUNCTYPE` is the same as :func:`CFUNCTYPE`. The function will release the GIL during the call. *use_errno* and *use_last_error* have the @@ -1618,12 +1620,9 @@ type and the argument types of the function. .. function:: PYFUNCTYPE(restype, *argtypes) - Returns a function prototype which creates functions that use the Python calling + The returned function prototype creates functions that use the Python calling convention. The function will *not* release the GIL during the call. -These factory functions can be used as decorator factories, and as such, be applied -to functions through the ``@wrapper`` syntax. - Function prototypes created by these factory functions can be instantiated in different ways, depending on the type and number of the parameters in the call: From c0e6de12e668e20f0917bf912f38a182e27c9e08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Delfino?= Date: Wed, 11 Jul 2018 10:09:10 -0300 Subject: [PATCH 4/4] Remove extra newline --- Doc/library/ctypes.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index c8b35da9121691..500aad8858f2ca 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1598,7 +1598,6 @@ factories, and as such, be applied to functions through the ``@wrapper`` syntax. See :ref:`ctypes-callback-functions` for examples. - .. function:: CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False) The returned function prototype creates functions that use the standard C