[New-bugs-announce] [issue35763] IDLE calltips: make positional note less obtrusive

[Terry J. Reedy]

New submission from Terry J. Reedy <tjreedy at udel.edu>:

#19903 made calltip.getargspec use inspect.signature.  The latter may include '/' following positional-only arguments.  Slashes are possible for the growing number of C-coded functions processed with Argument Clinic.  They appear in both help output and IDLE calltips, but not yet in the regular docs, let alone Python code.  The result, for instance, is 'float([x])' in the docs and 'float(x=0, /)' in help() and calltips.

Since '/' is effectively undocumented, especially in anything beginners would see, and since there have been questions from beginners as to its meaning, the following note is added to calltips on a new line followed by a blank line:

  ['/' marks preceding arguments as positional-only]

The negative effect is somewhat obtrusively expanding what would typically be 2 lines to 4 in order to say something that hopefully becomes useless.  Raymond's #16638 comment about big tips being distracting prompted me to consider some possible (non-exclusive) changes to reduce the impact.

0. Omit the blank line.  We added the blank line to make it clearer that the comment is not part of the docstring.  This can be done otherwise.

1. Change the font to something like smaller, red, italic characters.  Issue: the tip string is computed as a whole in the user execution process and inserted in the tip window in the IDLE process.  

2. Shorten and move the comment and mark it with '#'. Most builtins have short signatures, so a short enough comment could be appended to the signature line as a comment.  In combination with 0. (and 1., but not visible here), the float tip would shrink from the current

  float(x=0, /)
  ['/' marks preceding arguments as positional-only]

  Convert a string or number to a floating point number, if possible.

back down to

  float(x=0, /)  # / means positional-only
  Convert a string or number to a floating point number, if possible.

3. Limit the number of appearances in a particular session.  The following should work.

slash_comments = 3
...  
    if '/' in sig:
        if slash_comments:
            slash_comments -= 1
            <add slash comment>

I think 3 would be about enough.  I don't want to make it configurable.

Issue: restarting the user execution process would restart the count in that process, where the addition is currently made.


If the proposal to use '/' in the regular docs were ever accepted, I would remove the special calltip comment.

----------
assignee: terry.reedy
components: IDLE
messages: 333897
nosy: rhettinger, terry.reedy
priority: normal
severity: normal
stage: test needed
status: open
title: IDLE calltips: make positional note less obtrusive
type: enhancement
versions: Python 3.7, Python 3.8

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue35763>
_______________________________________