classification
Title: inspect.currentframe documentation omits optional depth parameter
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: benjamin.peterson, docs@python, georg.brandl, llimllib, terry.reedy
Priority: normal Keywords: patch

Created on 2009-08-10 18:25 by llimllib, last changed 2010-08-09 22:03 by terry.reedy. This issue is now closed.

Files
File name Uploaded Description Edit
currentframe.diff llimllib, 2010-08-09 01:05 Version 2 of my patch to implement Terry's suggested wording
Messages (15)
msg91459 - (view) Author: William Mill (llimllib) Date: 2009-08-10 18:24
help(inspect.currentframe) reads:

---------------------------------
_getframe(...)
    _getframe([depth]) -> frameobject

Return a frame object from the call stack.  If optional integer depth is
given, return the frame object that many calls below the top of the
stack. If that is deeper than the call stack, ValueError is raised.  The
default for depth is zero, returning the frame at the top of the call stack.
        
This function should be used for internal and specialized
purposes only.
-------------------------------

The python library documentation, however, doesn't mention the optional
depth parameter:

-------------------------------
inspect.currentframe()
    Return the frame object for the caller’s stack frame.
-------------------------------

I think substituting the help() text for the library documentation's
text would be an improvement.
msg109675 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-07-09 03:59
The doc string seems correct, so I agree. A condensed and improved version of the docstring (with *depth* italicized as usual) might be

inspect.currentframe(depth=0) 
  Return the frame object depth calls below the top of the stack. If there is none, raise ValueError.

I do not think the internal comment is correct when it is exposed like this. Everything in inspect is specialized.

The doc string could be similarly condensed.
msg113327 - (view) Author: William Mill (llimllib) Date: 2010-08-08 21:26
This patch is built against trunk, because I'm not sure what branch I should build it against. If that's the wrong branch, I'd be happy to figure it out against the right branch.

I tested both the help() and the doc build, both worked as expected.

I will happily do anything more I can to help.
msg113341 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-08 22:17
Parameter 'depth' needs to be italicized in the function signature also.

The old 'trunk' is now frozen with the release of 2.7. The py3k branch is now the actual trunk. Please edit, build against that, and retest. I think the word 'trunk' will go away with the switch to hg planned for a few months from now.
msg113356 - (view) Author: William Mill (llimllib) Date: 2010-08-09 01:05
I've updated the patch to be based on the py3k branch, and updated the sys module's documentation for _getframe, since inspect just aliases sys._getframe to currentframe().

I've updated the argument list of both inspect.currentframe and sys._getframe to reflect that depth isn't an optional argument, but one with a default value; this matches more closely with the other documentation in those two modules.

Also, the function signature is automatically italicized; here's a screenshot of what it looks like: http://img.skitch.com/20100809-xddf43hy2ifxc3b2an4ae85fre.jpg
msg113360 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-09 03:03
A parameter with a default is very much optional. Makes no sense otherwise. In 3.x docs, the square brackets that were used in 2.x and are still used for optional args without default are left off because they are redundant. So in the example you depict, context is optional with a default of 1, and 'depth=0' is correct and means that is it optional with default 0.

I just realized that I removed the info that depth must me an integer.
>>> inspect.currentframe(0.0)
Traceback (most recent call last):
  File "<pyshell#2>", line 1, in <module>
    inspect.currentframe(0.0)
TypeError: integer argument expected, got float

Although it seems obvious, it also seems that the context count in the preceding 3 funcs does not have to be an int, at least not always,
>>> inspect.getframeinfo(inspect.currentframe(0), context=1.0)
Traceback(filename='<pyshell#3>', lineno=1, function='<module>', code_context=None, index=None)

which surprised me, so I think we should insert 'an integer ' before 'depth'.

Call the revision currentframe_2.diff. Some reviewers prefer unique names for uploaded files, and I think the current one should be left in case whichever doc person who grabs this prefers it.
msg113361 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2010-08-09 03:05
Technically, inspect.currentframe() doesn't have a depth parameter. It's just implemented by aliasing to sys._getframe() which does.
msg113365 - (view) Author: William Mill (llimllib) Date: 2010-08-09 03:28
Terry: fair enough, I'll add that it's required to be an integer. 

I just meant that the brackets seemed not to be around other keyword arguments, not that it's not optional, sorry for being unclear.

Ben and/or Terry: Would you prefer the inspect.currentframe docs to say something like:

Returns an alias to :func:`sys._getframe` if it exists, otherwise returns a function which always returns ``None``

? I see that as more accurate, but perhaps not as useful to a user of the library who then has to go read the documentation for sys._getframe to find out what the function does.
msg113413 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2010-08-09 13:05
r83890 no longer produces the extra argument in help().
msg113423 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-09 16:19
Benjamin: Previously, .currentframe() == sys._getframe() == sys._getframe(0) but you redefined it as sys._getframe(1), which is a change in semantics. Is this intentional (ie, was it buggy before)?

William: Benjamin's point was that the bug was not the doc but the implementation of .currentframe, so we were making the wrong fix relative to the intention of .currentframe.
msg113424 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2010-08-09 16:22
2010/8/9 Terry J. Reedy <report@bugs.python.org>:
>
> Terry J. Reedy <tjreedy@udel.edu> added the comment:
>
> Benjamin: Previously, .currentframe() == sys._getframe() == sys._getframe(0) but you redefined it as sys._getframe(1), which is a change in semantics. Is this intentional (ie, was it buggy before)?

Yes, currentframe() doesn't take an argument. Whether it should or not
is a feature request.
msg113432 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-09 17:52
You ignored my question: why did you change the argument passed on to sys._getframe?
msg113433 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2010-08-09 17:56
2010/8/9 Terry J. Reedy <report@bugs.python.org>:
>
> Terry J. Reedy <tjreedy@udel.edu> added the comment:
>
> You ignored my question: why did you change the argument passed on to sys._getframe?

Ah, so that the caller's frame is returned and not currentframe's.
msg113449 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-08-09 18:48
Terry: due to the additional indirection by making currentframe() a separate function, _getframe(0) would return the frame in currentframe().
msg113487 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-09 22:03
Thank you both. I had missed the subtle difference between aliasing and wrapping in this particular case.
History
Date User Action Args
2010-08-09 22:03:39terry.reedysetmessages: + msg113487
2010-08-09 18:48:30georg.brandlsetmessages: + msg113449
2010-08-09 17:56:59benjamin.petersonsetmessages: + msg113433
2010-08-09 17:52:52terry.reedysetmessages: + msg113432
2010-08-09 16:22:21benjamin.petersonsetmessages: + msg113424
2010-08-09 16:19:44terry.reedysetmessages: + msg113423
2010-08-09 13:05:59benjamin.petersonsetstatus: open -> closed
resolution: fixed
messages: + msg113413
2010-08-09 03:28:07llimllibsetmessages: + msg113365
2010-08-09 03:06:00benjamin.petersonsetnosy: + benjamin.peterson
messages: + msg113361
2010-08-09 03:03:58terry.reedysetmessages: + msg113360
2010-08-09 02:43:46terry.reedysetfiles: - currentframe.diff
2010-08-09 01:05:30llimllibsetfiles: + currentframe.diff

messages: + msg113356
2010-08-08 22:17:04terry.reedysetmessages: + msg113341
stage: needs patch -> patch review
2010-08-08 21:26:19llimllibsetfiles: + currentframe.diff

messages: + msg113327
2010-08-07 18:32:26terry.reedysetstage: needs patch
versions: - Python 2.6
2010-07-09 03:59:42terry.reedysetversions: - Python 2.5, Python 2.4, Python 3.0
nosy: + terry.reedy, docs@python

messages: + msg109675

assignee: georg.brandl -> docs@python
keywords: + patch
2009-08-10 18:25:00llimllibcreate