This issue is to add support for rendering multi-line docstring signatures in IDLE calltips (e.g. iter(), min(), int(), etc).  This was suggested by Serhiy in the comments to issue 16629.

[Continuing a discussion/question from the issue 16629 comments]

> > For example, why not be smarter about detecting the end of the signature (e.g. first line not having "->")?
> The objection is that there are such signatures:
>     foo(a, b, c,
          e, f, g) -> some result

I meant the first line after the first line without a "->", but good point.

What are some examples of "false positives" that we would want to exclude?  If there are examples of docstrings beginning with large amounts of text and no signature, we could look for a string of the form "func(" at the beginning of a line to know whether a signature has actually begun.

Here is a patch moved from issue16629.

I think this is a bugfix, because current behavior is wrong. Many functions (i.e. int, str, list, dict) have multiline signatures and IDLE shows only first line in a tip. I.e. "int(x=0) -> integer" showed for int(), but int() accepts up to two arguments. This is a regression comparing with times when the signature was oneline.

I think we should add empty lines after signatures in all docstrings where it needed (i.e. for super()).

Here is a command which shows calltips for all builtins:

./python -c "from idlelib.CallTips import get_argspec, get_entity; import builtins
for name in sorted(builtins.__dict__):
  print('%s:\t%s' % (name, get_argspec(get_entity(name)).replace('\n', '\n\t')))"

And for dict methods:

./python -c "from idlelib.CallTips import get_argspec, get_entity; import builtins;^Mfor name in sorted(vars(dict)):^M  print('%s:\t%s' % (name, get_argspec(get_entity('{}.'+name)).replace('\n', '\n\t')))"

The patch is synchronized with tip.

See #20338 for why I think 70 (or even 79, the limit in CallTipWindow) is too low a limit.

The purpose of grabbing multiple lines is to get the signature lines of builtins. I believe the max number of lines needed is 5, for bytes. however, identifying likely builtins by the absence of a signature from inspect, which works now, will not work when Clinic and inspect start giving us such. Even when if Clinic produces a signature string for bytes, it will probably be opaque and the doc lines would still be helpful. So I think we can try up to 5 lines from the docstring for any object. I am working on a revision of the patch.

New changeset 6b62c923c0ef by Terry Jan Reedy in branch '2.7':
Issue #16638: Include up to 5 docstring header lines (before first blank) in
http://hg.python.org/cpython/rev/6b62c923c0ef

New changeset 5b6c3760714e by Terry Jan Reedy in branch '3.3':
Issue #16638: Include up to 5 docstring header lines (before first blank) in
http://hg.python.org/cpython/rev/5b6c3760714e

Main change is using a custom function (2.7) or bytes instead of int for test and using maxsplit parameter to not needlessly split a 100-line docstring into 100 pieces.

Using Python 2.7.7 is a classroom setting revealed that this change is sometimes helpful and sometimes problematic.

The big tip windows are VERY distracting during live coding demos and learners are reporting that it breaks their concentration.  On the other hand, it is nice when a function is being encountered for the first time.

I recommend providing a way to turn this feature off or limit it to displaying a given function in full no more than once.

As I said previously, the only reason for the change was get all the docstring signature lines for builtins, after they were changed from 1 to many. I was not thrilled with having to do this. However, I felt that just presenting the arbitrary first of many lines was (and would be) a bug.

For 3.4+, this is a temporary measure until Argument Clinic is applied to enough builtins to make it sensible to switch calltips to using str(inspect.signature). See #19903. When A.C. is applied to a function, the signature is no longer in the docstring, which instead starts with 'Returns (or whatever) just as for python-coded functions.

Since A.C. and #19903 do not apply to 2.7, feel free to develop a more permanent alternative for 2.7. Perhaps just say <expand multiple line signature> and have a click on that line do the expansion instead of dismissing the box.

If you do, I can check whether the A.C conversion has been slow enough to make temporary application to 3.4 worthwhile, or if *really* slow, to 3.5. The click idea, while still needed, might be combined with using .signature, but I have to recheck its current behavior.

Since many of the criteria mentioned in msg219204 are now implemented or out of date, should this issue now be re-closed?

The standard calltip box is two lines: signature and docstring header.  In most cases, such as int, iter, and min, the effect of this patch is to get both lines of a docstring signature, so the result is not abnormally big.  And I agree with Serhiy that getting even more lines, when needed, is a bug fix.  (My change to 'enhancement' was in respect to Raymond's proposal, hence the reversion.)

Bytes is one of the very few functions with more than two header lines, and exceptional at 5.  It could be reduced to 4 if the first and last were combined as done for other functions.  I don't want to add an option or special code for this special case.

#19903 expands the calltip by 2 lines when the signature includes '/'.  This is increasingly common as more builtins get processed by Argument Clinic. I opened #35763 to revisit and revise this behavior.