bpo-17972: Document findsource in inspect.rst#6992
Conversation
From the discussion in bpo-1792, it seem that findsource is mostly low level, while getsource is higher level. This does not completely fix bpo-17972 as many methonds need to be marked either private, or documented
JulienPalard
left a comment
JulienPalard
left a comment
There was a problem hiding this comment.
LGTM with nits.
You could maybe also state that findsource does not unwraps?
|
|
||
| If *object* is a wrapper function (that is to say has a :attr:`__wrapped__` | ||
| field, :func:`getsource` will follows the chain of :attr:`__wrapped__` | ||
| attributes returning the last object in the chain using :func:`unwrap` |
There was a problem hiding this comment.
Missing a dot at end of sentence:
| attributes returning the last object in the chain using :func:`unwrap` | |
| attributes returning the last object in the chain using :func:`unwrap`. |
|
|
||
| .. function:: findsource(object) | ||
|
|
||
| Return the entire source file and starting line number for an object. |
There was a problem hiding this comment.
I'd be explicit that the function is returning a tuple, maybe by starting like this and describing both elements:
Return a tuple ``(lines, lnum)`` where *lines* is ...
| Return the entire source file and starting line number for an object. | ||
|
|
||
| The argument may be a module, class, method, function, traceback, frame, | ||
| or code object. The source code is returned as a list of all the lines |
There was a problem hiding this comment.
The sentence starting here may be redundent if you fix the previous comment.
|
|
||
| The argument may be a module, class, method, function, traceback, frame, | ||
| or code object. The source code is returned as a list of all the lines | ||
| in the file and the line number indexes a line in that list. An OSError |
There was a problem hiding this comment.
Please link to the actual exception, at least as a visual hint while reading (this make it rendered differently in HTML):
| in the file and the line number indexes a line in that list. An OSError | |
| in the file and the line number indexes a line in that list. An :exc:`OSError` |
|
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
5 participants
From the discussion in bpo-1792, it seem that findsource is mostly low
level, while getsource is higher level.
This does not completely fix bpo-17972 as many methonds need to be
marked either private, or documented
https://bugs.python.org/issue17972