[issue15657] Error in Python 3 docs for PyMethodDef
In the Python 3.2.2 documentation (and earlier Python 3 versions), in
New submission from Sandro Tosi: Hello, it has been reported at http://mail.python.org/pipermail/docs/2012-April/008215.html but given it raises some question whether it's a bug in the doc or in the code, i'd rather report the issue here and hear what other think: the Python/C API Reference Manual, chapter Object Implementation Support, the documentation for PyMethodDef says: The ml_flags field is a bitfield which can include the following flags. The individual flags indicate either a calling convention or a binding convention. Of the calling convention flags, only METH_VARARGS and METH_KEYWORDS can be combined (but note that METH_KEYWORDS alone is equivalent to METH_VARARGS | METH_KEYWORDS). The bit in the parenthetical is incorrect. If you take a look at PyCFunction_Call in Objects/methodobject.c, you will find a switch for METH_VARARGS | METH_KEYWORDS, but no switch for METH_KEYWORDS. Hence, using METH_KEYWORDS will land you with a SystemError that complains about METH_OLDARGS. This is either a bug in the documentation, or a bug in Python. In this case, since the code has persisted through three major revisions of Python 3, I suggest that the bug _is_ in the documentation (whether it should be or not), since changing the code for this at this late date means a programmer has to use METH_VARARGS | METH_KEYWORDS anyway for compatibility. It may be work pointing out specifically in the documentation that just using METH_KEYWORDS will not work. <<< ---------- assignee: docs@python components: Documentation messages: 168226 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: patch review status: open title: Error in Python 3 docs for PyMethodDef versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Changes by Michael Welsh Duggan <mwd@sei.cmu.edu>: ---------- nosy: +md5i _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Changes by Jesús Cea Avión <jcea@jcea.es>: ---------- nosy: +jcea _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Changes by Andrew Svetlov <andrew.svetlov@gmail.com>: ---------- nosy: +asvetlov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Andrew Svetlov added the comment: I think we can change PyCFunction_Call to accept METH_KEYWORDS as alias for METH_VARARGS | METH_KEYWORDS. It cannot make incompatibility with existing code base. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Barry A. Warsaw added the comment: I just ran into this too. ---------- nosy: +barry _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Barry A. Warsaw added the comment: We should fix the code for 3.2 through 3.4, but change the docs for 3.2 and 3.3 to remove the parenthetical note. For 3.4 we can leave the parenthetical note but say this is new in 3.4 (or maybe, that it doesn't actually work in some versions < 3.4). I agree that for code to work consistently across all Python 3.2 and 3.3 microversions, extension code is going to have to include both flags anyway. ---------- versions: +Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Changes by Bohuslav "Slavek" Kabrda <bkabrda@redhat.com>: ---------- nosy: +bkabrda _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Cimarron Mittelsteadt added the comment: Appears to be a duplicate of issue 11587 but better explanation here ---------- nosy: +cimarron _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Berker Peksag added the comment: Here is a patch for Python 3.5. ---------- components: +Interpreter Core -Documentation keywords: +patch nosy: +berker.peksag, serhiy.storchaka type: -> behavior versions: +Python 3.5 -Python 3.2, Python 3.3 Added file: http://bugs.python.org/file39164/issue15657.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Serhiy Storchaka added the comment: In 3.5 it would be better to make METH_KEYWORDS == METH_VARARGS | METH_KEYWORDS. Current definition: #define METH_VARARGS 0x0001 #define METH_KEYWORDS 0x0002 Should be: #define METH_VARARGS 0x0001 #define METH_KEYWORDS 0x0003 But it can't be applied in maintained releases. In 3.4 and 2.7 we should add explicit test as in the patch or change the documentation. If fix the code rather than documentation in 3.4 and 2.7, then the versionchanged directive in 3.5 shouldn't be added. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Changes by Alexander Belopolsky <alexander.belopolsky@gmail.com>: ---------- nosy: +belopolsky _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Berker Peksag added the comment: I'm going to delete (but note that :const:`METH_KEYWORDS` alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``) from Doc/c-api/structures.rst in 3.5. Then change the value of METH_KEYWORDS from 0x0002 to 0x0003 in 3.6. Thanks for the review Serhiy. ---------- versions: +Python 3.6 -Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Roundup Robot added the comment: New changeset 367b3f41710a by Berker Peksag in branch '3.5': Issue #15657: Delete incorrect statement from PyMethodDef documentation https://hg.python.org/cpython/rev/367b3f41710a New changeset 7fa4986d8218 by Berker Peksag in branch 'default': Issue #15657: Null merge from 3.5 https://hg.python.org/cpython/rev/7fa4986d8218 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Roundup Robot added the comment: New changeset f520ae3b537b by Berker Peksag in branch '2.7': Issue #15657: Delete incorrect statement from PyMethodDef documentation https://hg.python.org/cpython/rev/f520ae3b537b ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Berker Peksag added the comment:
Then change the value of METH_KEYWORDS from 0x0002 to 0x0003 in 3.6.
Here is a patch. ---------- Added file: http://bugs.python.org/file43364/issue15657_36.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Martin Panter added the comment: . The documentation did not get merged properly into 3.6+. And even in 3.5, under METH_KEYWORDS, I propose to change “The flag is typically combined with METH_VARARGS” to “The flag must be combined . . .”. The remaining issue15657_36.diff patch looks out of date. There is a _PyCFunction_FastCallDict() function that appears to also need adjusting. But instead of changing the value of METH_KEYWORDS, wouldn’t it be safer to just accept METH_KEYWORDS (= 2) on its own as a valid value? This is what Python 2 does. Essentially, revert the first hunk of https://hg.python.org/cpython/diff/b7bfa780a882/Objects/methodobject.c but without METH_OLDARGS, whose value was zero anyway. BTW, the statement did not need to be removed in Python 2, but IMO it’s fine now without the statment. The statement was added in revision 1564c6839e6b. ---------- nosy: +martin.panter versions: +Python 3.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Roundup Robot added the comment: New changeset d7d2d24003f5 by Martin Panter in branch '3.5': Issue #15657: METH_KEYWORDS cannot be used alone in Python 3 https://hg.python.org/cpython/rev/d7d2d24003f5 New changeset c140e72492a4 by Martin Panter in branch '3.6': Issue #15657: Delete incorrect statement from PyMethodDef documentation https://hg.python.org/cpython/rev/c140e72492a4 New changeset 021fd2ff7ca4 by Martin Panter in branch '3.6': Issue #15657: Merge other doc fix from 3.5 https://hg.python.org/cpython/rev/021fd2ff7ca4 New changeset 1058e151049a by Martin Panter in branch 'default': Issue #15657: Merge METH_KEYWORDS doc from 3.6 https://hg.python.org/cpython/rev/1058e151049a ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
Barry A. Warsaw added the comment: I think this bug has been fixed. ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________
participants (12)
-
Alexander Belopolsky -
Andrew Svetlov
-
Barry A. Warsaw
-
Berker Peksag
-
Bohuslav "Slavek" Kabrda
-
Cimarron Mittelsteadt
-
Jesús Cea Avión
-
Martin Panter
-
Michael Welsh Duggan
-
Roundup Robot
-
Sandro Tosi
-
Serhiy Storchaka