[issue20338] Idle: increase max calltip width

[Terry J. Reedy]

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 <report at bugs.python.org>
<http://bugs.python.org/issue20338>
_______________________________________