classification
Title: support multi-line docstring signatures in IDLE calltips
Type: behavior Stage: resolved
Components: IDLE Versions: Python 2.7
process
Status: closed Resolution: fixed
Dependencies: 20122 Superseder:
Assigned To: Nosy List: cheryl.sabella, chris.jerdonek, python-dev, rhettinger, roger.serwy, serhiy.storchaka, terry.reedy
Priority: high Keywords: patch

Created on 2012-12-07 19:49 by chris.jerdonek, last changed 2019-01-17 20:29 by terry.reedy. This issue is now closed.

Files
File name Uploaded Description Edit
idle_calltips_multiline_4.patch serhiy.storchaka, 2013-12-09 14:48 review
Messages (12)
msg177118 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-12-07 19:49
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.
msg177126 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-12-07 20:28
[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.
msg177128 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-12-07 20:35
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.
msg177131 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-12-07 20:53
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')))"
msg205698 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-12-09 14:48
The patch is synchronized with tip.
msg208719 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-01-21 23:27
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.
msg208732 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-01-22 01:46
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
msg208733 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-01-22 01:48
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.
msg219196 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-05-27 02:00
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.
msg219204 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-05-27 06:05
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.
msg333873 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-01-17 14:26
Since many of the criteria mentioned in msg219204 are now implemented or out of date, should this issue now be re-closed?
msg333900 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-01-17 20:29
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.
History
Date User Action Args
2019-01-17 20:29:44terry.reedysetstatus: open -> closed
type: enhancement -> behavior
messages: + msg333900
2019-01-17 14:26:45cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg333873
2014-05-27 06:05:53terry.reedysetassignee: terry.reedy ->
type: behavior -> enhancement
messages: + msg219204
versions: - Python 3.3, Python 3.4
2014-05-27 02:00:59rhettingersetstatus: closed -> open
priority: normal -> high

nosy: + rhettinger
messages: + msg219196
2014-01-22 01:48:43terry.reedysetstatus: open -> closed
resolution: fixed
messages: + msg208733

stage: patch review -> resolved
2014-01-22 01:46:00python-devsetnosy: + python-dev
messages: + msg208732
2014-01-21 23:27:13terry.reedysetassignee: serhiy.storchaka -> terry.reedy
messages: + msg208719
2014-01-04 16:48:09serhiy.storchakasetdependencies: + Move CallTips tests to idle_tests
2013-12-09 14:49:10serhiy.storchakasetfiles: - idle_calltips_multiline_3.patch
2013-12-09 14:48:01serhiy.storchakasetfiles: + idle_calltips_multiline_4.patch

messages: + msg205698
versions: - Python 3.2
2012-12-29 22:00:42serhiy.storchakasetassignee: serhiy.storchaka
2012-12-07 20:53:40serhiy.storchakasetmessages: + msg177131
2012-12-07 20:35:22serhiy.storchakasetfiles: + idle_calltips_multiline_3.patch
versions: + Python 2.7, Python 3.2, Python 3.3, Python 3.4
messages: + msg177128

keywords: + patch
type: enhancement -> behavior
stage: patch review
2012-12-07 20:28:10chris.jerdoneksetmessages: + msg177126
2012-12-07 19:49:36chris.jerdonekcreate