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.

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.

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.

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.

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

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.

Technically, inspect.currentframe() doesn't have a depth parameter. It's just implemented by aliasing to sys._getframe() which does.

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.

r83890 no longer produces the extra argument in help().

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.

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.

You ignored my question: why did you change the argument passed on to sys._getframe?

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.

Terry: due to the additional indirection by making currentframe() a separate function, _getframe(0) would return the frame in currentframe().

Thank you both. I had missed the subtle difference between aliasing and wrapping in this particular case.