Terry J. Reedy added the comment:
1. For multiple reasons, I want to at least start with only wrapping the
signature string.
I want to keep the code as simple and fast as possible, and not worry much
about rare oddball or PEP8-violating cases. I want to only do what is needed
for the purpose of calltips, which is to remind one of the call sequence.
Adding more detracts from that purpose. Tips are not intended to replace using
the doc or help(f) to learn about f.
As it is, I am not happy about possibly including more than 1 or 2 lines of a
docstring for Python-coded functions. I intend to revisit that when the dust
settles with Clinic and inspect. That fact that another patch *will* be needed,
almost certainly, is another reason to not do too much now.
Wrapping overly long docstrings should not needed. Even if the initial _MAX_COL
slice of the first line of the docstring of a Python-coded function fails to
say enough about the return value, there is help(f) to get full details.
I reread PEP 8 and, contrary to what I (mis) remembered, it says that
docstrings should remain limited to 72 (or 79) chars *even if* a project
increases the limit for *code* lines up to say, 100. The reason for this is
precisely because other software, like help, Idle, and others, read, process,
and display docstrings. If docstrings violate this, I think they should be
changed, and not accomadated (except as suggested below).
So I want to add, before the docstring fetch, only this:
if len(argspec) > _MAX_COLS:
argspec = textwrap.wrap(argspec, _MAX_COLS,
subsequent_indent=' ')
dict is definitely an oddball and I do not want to include it in a test at this
time. I do not mind suggesting help(dict), though the current docstring is
incomplete. Here is the real signature and description, which I verified from
the examples below. The multiple example lines should follow a condensed
summary.
def dict([map_or_it,] **kwds)
'''Return new dictionary initialized from pairs of positional-only
map_or_it, if present, and updated with kwds, if present.
<start current docstring with specifics>
'''
>>> dict({'a':1}, b=2)
{'b': 2, 'a': 1}
>>> dict({'a':1}, a=2)
{'a': 2}
2. For two reasons, I want to increase _MAX_COLS a bit, say to 85.
First, when wrapping a signature, the 'words' after the first few typically
have the form 'name=value'. They will average much longer than the average
English word (4, I think). The average wrapped line length will be _MAX_COLS -
half the average 'word' length. For example (one which should become a test):
>>> for line in textwrap.wrap(str(signature(textwrap.TextWrapper)),
width = 85, subsequent_indent=' '):
print(line)
(width=70, initial_indent='', subsequent_indent='', expand_tabs=True,
replace_whitespace=True, fix_sentence_endings=False, break_long_words=True,
drop_whitespace=True, break_on_hyphens=True, tabsize=8, *, max_lines=None,
placeholder=' [...]')
The lengths, including indents, are 69, 78, 77, and 24, all <= 79. Very few
signature lines, wrapped or not, will fall in [80-85].
Second, PEP 8 allows initial summary lines to be 79 chars, as they are not
"flowing long blocks of text". (I verified this with Guido.) Some docstrings in
the stdlib 'cheat' a few chars, and 85 will accommodate those without ever
being excessively long.
----------
_______________________________________
Python tracker <[email protected]>
<http://bugs.python.org/issue20338>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
