Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

support multi-line docstring signatures in IDLE calltips #60842

Closed
cjerdonek opened this issue Dec 7, 2012 · 12 comments
Closed

support multi-line docstring signatures in IDLE calltips #60842

cjerdonek opened this issue Dec 7, 2012 · 12 comments
Labels
topic-IDLE type-bug An unexpected behavior, bug, or error

Comments

@cjerdonek
Copy link
Member

BPO 16638
Nosy @rhettinger, @terryjreedy, @serwy, @cjerdonek, @serhiy-storchaka, @csabella
Dependencies
  • bpo-20122: Move CallTips tests to idle_tests
  • Files
  • idle_calltips_multiline_4.patch
  • Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
    closed_at = <Date 2019-01-17.20:29:44.344>
    created_at = <Date 2012-12-07.19:49:36.078>
    labels = ['expert-IDLE', 'type-bug']
    title = 'support multi-line docstring signatures in IDLE calltips'
    updated_at = <Date 2019-01-17.20:29:44.342>
    user = 'https://github.com/cjerdonek'

    bugs.python.org fields:

    activity = <Date 2019-01-17.20:29:44.342>
    actor = 'terry.reedy'
    assignee = 'none'
    closed = True
    closed_date = <Date 2019-01-17.20:29:44.344>
    closer = 'terry.reedy'
    components = ['IDLE']
    creation = <Date 2012-12-07.19:49:36.078>
    creator = 'chris.jerdonek'
    dependencies = ['20122']
    files = ['33059']
    hgrepos = []
    issue_num = 16638
    keywords = ['patch']
    message_count = 12.0
    messages = ['177118', '177126', '177128', '177131', '205698', '208719', '208732', '208733', '219196', '219204', '333873', '333900']
    nosy_count = 7.0
    nosy_names = ['rhettinger', 'terry.reedy', 'roger.serwy', 'chris.jerdonek', 'python-dev', 'serhiy.storchaka', 'cheryl.sabella']
    pr_nums = []
    priority = 'high'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = 'behavior'
    url = 'https://bugs.python.org/issue16638'
    versions = ['Python 2.7']

    @cjerdonek
    Copy link
    Member Author

    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 bpo-16629.

    @cjerdonek cjerdonek added type-feature A feature request or enhancement topic-IDLE labels Dec 7, 2012
    @cjerdonek
    Copy link
    Member Author

    [Continuing a discussion/question from the bpo-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.

    @serhiy-storchaka
    Copy link
    Member

    Here is a patch moved from bpo-16629.

    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.

    @serhiy-storchaka serhiy-storchaka added type-bug An unexpected behavior, bug, or error and removed type-feature A feature request or enhancement labels Dec 7, 2012
    @serhiy-storchaka
    Copy link
    Member

    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')))"

    @serhiy-storchaka serhiy-storchaka self-assigned this Dec 29, 2012
    @serhiy-storchaka
    Copy link
    Member

    The patch is synchronized with tip.

    @terryjreedy
    Copy link
    Member

    See bpo-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.

    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Jan 22, 2014

    New changeset 6b62c923c0ef by Terry Jan Reedy in branch '2.7':
    Issue bpo-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 bpo-16638: Include up to 5 docstring header lines (before first blank) in
    http://hg.python.org/cpython/rev/5b6c3760714e

    @terryjreedy
    Copy link
    Member

    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.

    @rhettinger
    Copy link
    Contributor

    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.

    @rhettinger rhettinger reopened this May 27, 2014
    @terryjreedy
    Copy link
    Member

    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 bpo-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 bpo-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.

    @terryjreedy terryjreedy added type-feature A feature request or enhancement and removed type-bug An unexpected behavior, bug, or error labels May 27, 2014
    @terryjreedy terryjreedy removed their assignment May 27, 2014
    @csabella
    Copy link
    Contributor

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

    @terryjreedy
    Copy link
    Member

    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.

    bpo-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 bpo-35763 to revisit and revise this behavior.

    @terryjreedy terryjreedy added type-bug An unexpected behavior, bug, or error and removed type-feature A feature request or enhancement labels Jan 17, 2019
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    topic-IDLE type-bug An unexpected behavior, bug, or error
    Projects
    None yet
    Development

    No branches or pull requests

    5 participants