classification
Title: Document PyEval_Call* functions
Type: Stage: needs patch
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, inada.naoki, lemburg, ncoghlan, pitrou, robquad, serhiy.storchaka
Priority: normal Keywords: easy

Created on 2011-02-09 22:56 by ncoghlan, last changed 2017-02-15 10:11 by inada.naoki.

Messages (9)
msg128248 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-02-09 22:56
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).
msg128249 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-02-09 22:57
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.
msg130839 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-03-14 16:01
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?
msg130965 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-03-15 12:16
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.
msg221759 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-06-28 01:01
@Nick I assume that this still needs doing.  msg128249 says you've removed the easy tag but it still shows in the keywords list.
msg287755 - (view) Author: Marc-Andre Lemburg (lemburg) * (Python committer) Date: 2017-02-14 10:03
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.
msg287835 - (view) Author: INADA Naoki (inada.naoki) * (Python committer) Date: 2017-02-15 10:03
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?
msg287836 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-02-15 10:09
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.
msg287838 - (view) Author: INADA Naoki (inada.naoki) * (Python committer) Date: 2017-02-15 10:11
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-da3df9def5eca3595399b0a5a7698eac
History
Date User Action Args
2017-02-15 10:11:54inada.naokisetmessages: + msg287838
2017-02-15 10:09:31serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg287836
2017-02-15 10:03:25inada.naokisetnosy: + inada.naoki
messages: + msg287835
2017-02-15 10:01:06serhiy.storchakalinkissue29548 dependencies
2017-02-14 20:13:10BreamoreBoysetnosy: - BreamoreBoy
2017-02-14 10:03:38lemburgsetnosy: + lemburg
messages: + msg287755
2014-06-28 01:01:47BreamoreBoysetnosy: + BreamoreBoy
messages: + msg221759
2011-03-15 12:16:36ncoghlansetnosy: ncoghlan, pitrou, docs@python, robquad
messages: + msg130965
2011-03-14 16:01:14pitrousetnosy: + pitrou
messages: + msg130839
2011-03-14 13:24:10robquadsetnosy: + robquad
2011-02-09 22:57:51ncoghlansetnosy: ncoghlan, docs@python
messages: + msg128249
2011-02-09 22:56:09ncoghlancreate