Title: Output of help(...) is wider than 80 characters
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.5
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: amaury.forgeotdarc, casevh, docs@python, giampaolo.rodola, terry.reedy
Priority: normal Keywords: patch

Created on 2010-09-02 05:01 by casevh, last changed 2019-03-15 23:35 by BreamoreBoy.

File name Uploaded Description Edit
doc_width1.diff casevh, 2010-09-02 05:01 Patch for math, cmath, tuple, datetime, and time. review
math_docstring.diff casevh, 2010-09-05 16:47 Correct doc strings for math module. review
Messages (7)
msg115359 - (view) Author: Case Van Horsen (casevh) Date: 2010-09-02 05:01
In several modules, the output of help(some_module) is wider than 80 characters. This results in extra line wrapping and incorrect formatting of the help text.

I've attached a single patch (doc_width1.diff) that corrects the issue for math, cmath, tuple, datetime, and time modules. I can continue to create patches for a few modules at a time, or I can create patches for individual modules.

I'm not changing any text, only adding \n as needed.
msg115361 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2010-09-02 06:50
Aren't there tools that extract only the first line of help?
msg115415 - (view) Author: Case Van Horsen (casevh) Date: 2010-09-03 03:25
According to PEP 7, the first line of the doc string should contain the signature of the function, then there should be a blank line, and then the rest of the doc string. There may be tools that extract the signature line. The patch just decreases the line length of the remaining lines of the doc string so they don't wrap when displayed on an 80 character wide terminal window.

For an example, look at the text for modf(...) in help(math).

I just noticed that the math module uses "modf(x)" for the signature line but PEP 7 recommends including the return type, say "modf(x) -> (frac, int)".

The simplest change would be to fix the wrapping issue and leave the signature line alone. It would be more effort to make all the doc strings PEP 7 compliant by standardizing the signature line to include the return type.

I'm willing to work through the standard library and create patches for either option.
msg115519 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-09-03 22:21
Although this is not a problem in IDLE where the window can easily be expanded beyond 80 chars, I am in favor of the idea for other uses. The command line interpreter on Windows defaults to 80 chars and is not so easy to change, and one must be admin to make the change 'permanent' (until the next install reverts the change). In particular, the 82 char line for math.trun results in 'd.' of 'method.' wrapped to a line by itself with no indent. Pretty ugly.

However, I am puzzled why you edited the 74 char line for math.modf, which displays as 78 chars with a 4 char indent. This
    Return the fractional and integer parts of x.  Both results carry the sign'''
displays fine on one line as is. The tracker, unfortunately, displays
123456789012345678901234567890123456789012345678901234567890123456789012 only 72 chars.
    of x and are floats.

I agree that
    trunc(x:Real) -> Integral
is more helpful (and therefore better) than

For something like
-"T.index(value, [start, [stop]]) -> integer -- return first index of value.\n"

I personally think '->' and 'return are redundant, so I would argue that this could be shortened to
-"T.index(value, [start, [stop]]) -> integer (first index of value).\n"
instead of by wrapping.

Since I am not yet in a position to apply patches, I am not (yet) in a position to tell you whether or how to produce more patches.
msg115655 - (view) Author: Case Van Horsen (casevh) Date: 2010-09-05 16:47
I edited the doc string for math.modf since an indent of 8 spaces is used for the doc string with help(math). An indent of 4 spaces is used with help(math.modf).

I've attached a new patch for just the math module that includes the return type as part of signature line, corrects the width issues, and uses a consistent format for defining the doc strings.
msg220984 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-06-19 14:33
@Terry is this something you could take on?
msg221058 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-06-20 01:20
Perhaps after the Google Summer of Code project is done (mid-August).
Date User Action Args
2019-03-15 23:35:14BreamoreBoysetnosy: - BreamoreBoy
2014-06-20 01:20:14terry.reedysetmessages: + msg221058
2014-06-19 14:33:37BreamoreBoysetnosy: + BreamoreBoy

messages: + msg220984
versions: + Python 3.5, - Python 3.2
2010-09-05 16:47:38casevhsetfiles: + math_docstring.diff

messages: + msg115655
2010-09-03 22:21:03terry.reedysetversions: + Python 3.2
nosy: + terry.reedy

messages: + msg115519

stage: patch review
2010-09-03 03:25:48casevhsetmessages: + msg115415
2010-09-02 08:55:15giampaolo.rodolasetnosy: + giampaolo.rodola
2010-09-02 06:50:59amaury.forgeotdarcsetnosy: + amaury.forgeotdarc, docs@python
messages: + msg115361

assignee: docs@python
components: + Documentation, - Extension Modules
2010-09-02 05:01:38casevhcreate