classification
Title: IDLE calltips: make positional note less obtrusive
Type: behavior Stage: resolved
Components: IDLE Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: miss-islington, rhettinger, terry.reedy
Priority: normal Keywords: patch

Created on 2019-01-17 20:01 by terry.reedy, last changed 2019-06-05 04:01 by terry.reedy. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 13791 merged terry.reedy, 2019-06-03 23:08
PR 13830 merged miss-islington, 2019-06-05 01:56
PR 13831 merged miss-islington, 2019-06-05 01:56
Messages (5)
msg333897 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-01-17 20:01
#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.
msg333899 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-01-17 20:22
#35764 is about revising the calltip doc, including adding something about '/' in signatures.
msg344662 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-06-05 01:55
New changeset 949fe976d5c62ae63ed505ecf729f815d0baccfc by Terry Jan Reedy in branch 'master':
 bpo-35763: Make IDLE calltip note about '/' less obtrusive (GH-13791)
https://github.com/python/cpython/commit/949fe976d5c62ae63ed505ecf729f815d0baccfc
msg344663 - (view) Author: miss-islington (miss-islington) Date: 2019-06-05 02:11
New changeset 39346ff60ac14bb83521c7e4f87304d0ad6478c2 by Miss Islington (bot) in branch '3.8':
bpo-35763: Make IDLE calltip note about '/' less obtrusive (GH-13791)
https://github.com/python/cpython/commit/39346ff60ac14bb83521c7e4f87304d0ad6478c2
msg344664 - (view) Author: miss-islington (miss-islington) Date: 2019-06-05 02:15
New changeset 3d75bd15ac82575967db367c517d7e6e703a6de3 by Miss Islington (bot) in branch '3.7':
bpo-35763: Make IDLE calltip note about '/' less obtrusive (GH-13791)
https://github.com/python/cpython/commit/3d75bd15ac82575967db367c517d7e6e703a6de3
History
Date User Action Args
2019-06-05 04:01:19terry.reedysetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-06-05 02:15:54miss-islingtonsetmessages: + msg344664
2019-06-05 02:11:47miss-islingtonsetnosy: + miss-islington
messages: + msg344663
2019-06-05 01:56:09miss-islingtonsetpull_requests: + pull_request13710
2019-06-05 01:56:01miss-islingtonsetpull_requests: + pull_request13709
2019-06-05 01:55:41terry.reedysetmessages: + msg344662
2019-06-05 00:26:26terry.reedysettype: enhancement -> behavior
versions: + Python 3.9
2019-06-03 23:08:50terry.reedysetkeywords: + patch
stage: test needed -> patch review
pull_requests: + pull_request13675
2019-01-17 20:22:42terry.reedysetmessages: + msg333899
2019-01-17 20:01:28terry.reedycreate