BUG: Fix help() formatting for deprecated functions. #8131
Conversation
|
I think the numpy import time golfing some time ago removed all imports
of `inspect`. It's probably ~20% increase? This reintroduces the import
--- could be a reason to copypaste cleandoc() since it's not that long.
|
ffe05bf to
db6459c
Compare
|
Thanks, now that I've found For reference, the commits series that introduced |
|
Yes, in tests is fine. Those are not imported when you |
numpy/compat/_inspect.py
Outdated
| """Clean up indentation from docstrings. | ||
|
|
||
| Any whitespace that can be uniformly removed from the second line | ||
| onwards is removed.""" |
There was a problem hiding this comment.
Hmm, can be uniformly removed isn't very informative as to which whitespace is removed. Also, the closing """ should follow a blank line.
There was a problem hiding this comment.
That's a straight copy from https://hg.python.org/cpython/file/tip/Lib/inspect.py#l579. Should we reformat it anyway?
By the way, I wasn't able to reproduce the import inspect slowdown (that's the reason for copying the function), but on the other hand, can't find anything in CPython's logs that would imply that something has changed in this respect.
There was a problem hiding this comment.
Sure, cpython isn't always the best for documentation. If inspect imports are no longer a problem we could simplify things in the future. IIRC, @rkern had the concern.
|
$ time python -c 'import numpy, os' |
1b25efb to
aa55941
Compare
|
Rebased for another try. With a fresh look I've noticed one more aspect of the issue, namely that cleaning the original docstring upfront may not be such a good idea. For example, imagine a style-enforcement tool that detects whitespace-only lines in docstrings by looking at Taking scenarios such as the above into account costs ~15 lines of code looking suspiciously similar to |
aa55941 to
95bab2c
Compare
numpy/lib/tests/test_utils.py
Outdated
| @@ -51,6 +78,23 @@ def test_deprecate_fn(): | |||
| assert_('new_func3' in new_func3.__doc__) | |||
|
|
|||
|
|
|||
| def test_deprecate_help_indentation(): | |||
| assert_(' ' not in inspect.getdoc(old_func4)) | |||
| assert_(' ' not in inspect.getdoc(old_func5)) | |||
There was a problem hiding this comment.
Wait, isn't this expected before "Bizarre indentation"?
There was a problem hiding this comment.
As far as I remember, we are trying to make the indentation in help() the same with and without deprecation. The output of help is processed by cleandoc(), which dedents all lines except the first one by as much as it can.
There was a problem hiding this comment.
Got it. Would be nice if the test could be more obviously comparing the deprecated and non-deprecated docstrings, but that's probably not worth the effort to change now.
|
@wrwrwr feel like finishing this up? |
95bab2c to
19208f0
Compare
numpy/lib/utils.py
Outdated
| indent = len(line) - content | ||
| margin = min(margin, indent) | ||
| if margin == sys.maxsize: | ||
| margin = 0 |
There was a problem hiding this comment.
nit: could extra lines 112 through 119 as a helper function _get_indent(lines[1:])
There was a problem hiding this comment.
Thanks for the review. I've cleaned up the code and the tests a bit further.
19208f0 to
25117d0
Compare
25117d0 to
af8dda1
Compare
|
Thanks @wrwrwr |
Please see the description in #8058.
The change also remedies the double blank line between the deprecation note and the summary appearing when the summary is not on the same line as the opening quotes.
Trying to handle all cases without resorting to
inspectresulted in nearly duplicatingcleandoc(), so I've decided to actually call on it.