Skip to content

bpo-4260: Document that ctypes.xFUNCTYPE are decorators #7924

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 13, 2018
Merged

bpo-4260: Document that ctypes.xFUNCTYPE are decorators #7924

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c58c398
bpo-4260: Document that ctypes.xFUNCTYPE are decorators
andresdelfino Jun 26, 2018
9a35dce
Fix indentation
andresdelfino Jun 26, 2018
4b297e9
Address Berker comments
andresdelfino Jul 11, 2018
c0e6de1
Remove extra newline
andresdelfino Jul 11, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 23 additions & 3 deletions Doc/library/ctypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why didn't you reuse the py_cmp_func function in line 1008? IMO, the following snippet should work:

@CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
def py_cmp_func(a, b):
    print("py_cmp_func", a[0], b[0])
    return a[0] - b[0]

There is even a test for that same function:

cpython/Lib/ctypes/test/test_callbacks.py

Lines 186 to 188 in b91a3a0

@CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
def cmp_func(a, b):
return a[0] - b[0]

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I followed the proposal from David W. Lambert in the issue, but you are right, I tested the decorator with the function from line 1008 and works as well.

... (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
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please don't make changes irrelevant to bpo-4260.

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
Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please don't make changes irrelevant to bpo-4260.

``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
Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please don't make changes irrelevant to bpo-4260.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can move this information to the first paragraph of the "Function prototypes" section to make it more discoverable.

Also, we can add a link to the examples from that paragraph.

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:

Expand Down