[issue11165] Document PyEval_Call* functions
New submission from Nick Coghlan <ncoghlan@gmail.com>: There are currently undocumented PyEval_Call* equivalents to a number of the PyObject_Call* functions. Since there are resources out there on the web that direct people to use the currently undocumented PyEval functions, it would be good to document those properly, and recommend people typically use the PyObject_Call* variants instead (as the latter include all the stack and interpreter state integrity protection code, while the PyEval variants assume that has all already been handled). ---------- assignee: docs@python components: Documentation keywords: easy messages: 128248 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Document PyEval_Call* functions versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: Removed the easy tag, since this may involve some python-dev discussion as to where to put them in C API docs (they don't really fit in any of the current sections). Perhaps an "advanced APIs" section, for things that most C extensions or embedding applications really shouldn't be using. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________
Changes by Robbie Clemons <robclemons@gmail.com>: ---------- nosy: +robquad _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________
Antoine Pitrou <pitrou@free.fr> added the comment: IMO, it would probably have been better if these APIs had been private from the start. Is there any use case for calling them from 3rd-party code? ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: There may be some legitimate use cases when embedding Python and you *know* that the checks performed by the PyObject_* versions aren't needed. It may also be historical - the PyEval versions may predate the PyObject ones. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________
Mark Lawrence added the comment: @Nick I assume that this still needs doing. msg128249 says you've removed the easy tag but it still shows in the keywords list. ---------- nosy: +BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________
Marc-Andre Lemburg added the comment: The PyEval_Call*() APIs indeed predate the PyObject_Call*() ones. The PyObject_Call*() APIs came into existence when the abstract layer was added in Python 1.3. The PyObject_Call*() APIs lacked a way to call an object with keyword arguments for a long time. I guess that's what most people continued to use the PyEval_Call*() ones. The latter also provide better protection against wrong parameters. The interpreter itself used them interchangeably. ---------- nosy: +lemburg _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________
Changes by Mark Lawrence <breamoreboy@gmail.com>: ---------- nosy: -BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________
INADA Naoki added the comment: I think PyObject_Call* APIs should be preferred. As discussed in #29548, we can't remove or deprecate PyEval_Call*. But I don't think it's worth enough to document them. How about keep them undocumented? ---------- nosy: +inada.naoki _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________
Serhiy Storchaka added the comment: While they are undocumented there is no a place for adding the recommendation of using corresponding PyObject_Call* functions and describing the way of porting from PyEval_Call* functions to PyObject_Call* functions. ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________
INADA Naoki added the comment: In PR 75, I added a comment in Include/ceval.h, right before PyEval_Call* APIs. https://github.com/python/cpython/pull/75/files#diff-da3df9def5eca3595399b0a... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________
Jeroen Demeyer <jeroen.k.demeyer@gmail.com> added the comment: These functions are now officially deprecated, see PR 14804. So I think that this issue can be closed. ---------- nosy: +jdemeyer _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11165> _______________________________________
Change by Inada Naoki <songofacandy@gmail.com>: ---------- resolution: -> fixed stage: needs patch -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11165> _______________________________________
participants (9)
-
Antoine Pitrou -
Inada Naoki
-
INADA Naoki
-
Jeroen Demeyer
-
Marc-Andre Lemburg
-
Mark Lawrence
-
Nick Coghlan
-
Robbie Clemons
-
Serhiy Storchaka