classification
Title: Document PyFrame_FastToLocals() and PyFrame_FastToLocalsWithError()
Type: Stage:
Components: Documentation Versions: Python 3.3, Python 3.4
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: csabella, docs@python, georg.brandl, pitrou, serhiy.storchaka, vstinner
Priority: normal Keywords: patch

Created on 2013-10-29 09:55 by vstinner, last changed 2017-12-12 13:12 by vstinner.

Files
File name Uploaded Description Edit
c_api_frame.patch vstinner, 2013-11-07 21:34 review
Messages (12)
msg201618 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2013-10-29 09:55
(Copy of an email) Georg Brandl via python.org 
	
Am 29.10.2013 01:19, schrieb victor.stinner:
> http://hg.python.org/cpython/rev/4ef4578db38a
> changeset:   86715:4ef4578db38a
> user:        Victor Stinner <victor.stinner@gmail.com>
> date:        Tue Oct 29 01:19:37 2013 +0100
> summary:
>   Issue #18408: Add a new PyFrame_FastToLocalsWithError() function to handle
> exceptions when merging fast locals into f_locals of a frame.
> PyEval_GetLocals() now raises an exception and return NULL on failure.

You'll have to either make this private or document it.
msg202387 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2013-11-07 21:34
c_api_frame.patch: document some C functions of the frame object in the C API.
msg300917 - (view) Author: Cheryl Sabella (csabella) * Date: 2017-08-27 13:54
Victor,

Should there be a PR for this?
msg300941 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-08-28 06:57
PyFrameObject already is documented in Doc/c-api/veryhigh.rst.
PyFrame_GetLineNumber() already is documented in Doc/c-api/reflection.rst.

PyFrame_FastToLocals() and PyFrame_LocalsToFast() are not documented and have weird interface. I think the use of them should be discouraged.
msg308053 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2017-12-11 15:44
> Should there be a PR for this?

Feel free to create a PR from my old (4 years old) patch. Just mention my name in the commit message please.
msg308054 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2017-12-11 15:44
> PyFrame_FastToLocals() and PyFrame_LocalsToFast() are not documented and have weird interface. I think the use of them should be discouraged.

I suggest to document them, but explain in the documentation that they must not be used :-)
msg308055 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2017-12-11 15:46
Ah, PyFrame_GetLineNumber is now documented at Doc/c-api/reflection.rst. But PyFrame_New() is still not documented. So my patch is not completely useful.

@Cheryl: Maybe convert the PR without PyFrame_FastToLocals() and PyFrame_FastToLocalsWithError().
msg308077 - (view) Author: Cheryl Sabella (csabella) * Date: 2017-12-11 23:12
Thanks Victor and Serhiy.

>> @Cheryl: Maybe convert the PR without PyFrame_FastToLocals() and PyFrame_FastToLocalsWithError().

If I only convert PyFrame_New() then I would need to add it to as existing page since the patch created a new page for Frame Objects.  I think the right place would be under the current PyFrameObject in Doc/c-api/veryhigh.rst?

Thanks!
msg308112 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2017-12-12 11:02
> If I only convert PyFrame_New() then I would need to add it to as existing page since the patch created a new page for Frame Objects.  I think the right place would be under the current PyFrameObject in Doc/c-api/veryhigh.rst?

Not, it's a very high level API, it's a low level API which should be referenced in the concrete.rst page, as I didn in my patch.

I think it's ok to have a page with only two functions: PyFrame_New() and  PyFrame_GetLineNumber().

Move https://docs.python.org/dev/c-api/reflection.html#c.PyFrame_GetLineNumber into your new doc, but leave something like "See also :c:func:`PyFrame_GetLineNumber`." there.
msg308113 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2017-12-12 11:04
Serhiy: how are you supposed to modify local variables of a frame when these variables are stored in "fast locals"? Even if it's a rare useful, I think that it's ok to expose PyFrame_FastToLocalsWithError(), and maybe also PyFrame_FastToLocals().

It is useful you want write a debugger in pure C, and don't want to bother with fast locals special case.
msg308118 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-12-12 11:53
frameobject.h is not included in any header file. Some effort was spent for avoiding including it in ceval.h, genobject.h, pystate.h and traceback.h. The whole content of frameobject.h is not available in the limited API. I'm not sure about the status of this API. This is not a very hight level API, but rather a very low level API. If document it, it should be documented on a separate page or on a page together with other low-level API.

> Serhiy: how are you supposed to modify local variables of a frame when these variables are stored in "fast locals"?

Currently you should call PyFrame_FastToLocalsWithError(), modify directly f_locals, and call PyFrame_LocalsToFast(). This is very low-level manipulation. It exposes implementation details (at least you need to access PyFrameObject attributes directly). It should be documented that the most of PyFrame_* API is low-level and implementation specific. PyFrame_GetLineNumber() is an exception.
msg308128 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2017-12-12 13:12
> Currently you should call PyFrame_FastToLocalsWithError(), modify directly f_locals, and call PyFrame_LocalsToFast().

When happens if PyFrame_LocalsToFast() isn't called? Does it crash or is it just slower?
History
Date User Action Args
2017-12-12 13:12:33vstinnersetmessages: + msg308128
2017-12-12 11:53:25serhiy.storchakasetmessages: + msg308118
2017-12-12 11:04:51vstinnersetmessages: + msg308113
2017-12-12 11:02:40vstinnersetmessages: + msg308112
2017-12-11 23:12:36csabellasetmessages: + msg308077
2017-12-11 15:46:54vstinnersetmessages: + msg308055
2017-12-11 15:44:45vstinnersetmessages: + msg308054
2017-12-11 15:44:08vstinnersetmessages: + msg308053
2017-08-28 06:57:16serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg300941
2017-08-27 13:54:50csabellasetnosy: + csabella
messages: + msg300917
2013-11-07 21:34:52vstinnersetfiles: + c_api_frame.patch
keywords: + patch
messages: + msg202387
2013-10-29 09:55:35vstinnercreate