wohlganger | 58fc71c | 2017-09-10 16:19:47 -0500 | [diff] [blame] | 1 | """Pop up a reminder of how to call a function. |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 2 | |
Kurt B. Kaiser | e54710b | 2002-12-12 19:15:39 +0000 | [diff] [blame] | 3 | Call Tips are floating windows which display function, class, and method |
| 4 | parameter and docstring information when you type an opening parenthesis, and |
| 5 | which disappear when you type a closing parenthesis. |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 6 | """ |
Terry Jan Reedy | 0fe4513 | 2019-03-24 17:12:28 -0400 | [diff] [blame] | 7 | import __main__ |
Terry Jan Reedy | a0f1e22 | 2014-01-26 19:55:34 -0500 | [diff] [blame] | 8 | import inspect |
Thomas Wouters | cf297e4 | 2007-02-23 15:07:44 +0000 | [diff] [blame] | 9 | import re |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 10 | import sys |
Terry Jan Reedy | a0f1e22 | 2014-01-26 19:55:34 -0500 | [diff] [blame] | 11 | import textwrap |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 12 | import types |
| 13 | |
Terry Jan Reedy | 6fa5bdc | 2016-05-28 13:22:31 -0400 | [diff] [blame] | 14 | from idlelib import calltip_w |
| 15 | from idlelib.hyperparser import HyperParser |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 16 | |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 17 | |
Terry Jan Reedy | 06e2029 | 2018-06-19 23:00:35 -0400 | [diff] [blame] | 18 | class Calltip: |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 19 | |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 20 | def __init__(self, editwin=None): |
Raymond Hettinger | c5e378d | 2004-05-04 08:34:56 +0000 | [diff] [blame] | 21 | if editwin is None: # subprocess and test |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 22 | self.editwin = None |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 23 | else: |
| 24 | self.editwin = editwin |
| 25 | self.text = editwin.text |
| 26 | self.active_calltip = None |
| 27 | self._calltip_window = self._make_tk_calltip_window |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 28 | |
| 29 | def close(self): |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 30 | self._calltip_window = None |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 31 | |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 32 | def _make_tk_calltip_window(self): |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 33 | # See __init__ for usage |
Terry Jan Reedy | 9af1836 | 2018-06-20 02:18:49 -0400 | [diff] [blame] | 34 | return calltip_w.CalltipWindow(self.text) |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 35 | |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 36 | def _remove_calltip_window(self, event=None): |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 37 | if self.active_calltip: |
| 38 | self.active_calltip.hidetip() |
| 39 | self.active_calltip = None |
Kurt B. Kaiser | ae67647 | 2001-07-12 23:10:35 +0000 | [diff] [blame] | 40 | |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 41 | def force_open_calltip_event(self, event): |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 42 | "The user selected the menu entry or hotkey, open the tip." |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 43 | self.open_calltip(True) |
Serhiy Storchaka | 213ce12 | 2017-06-27 07:02:32 +0300 | [diff] [blame] | 44 | return "break" |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 45 | |
| 46 | def try_open_calltip_event(self, event): |
Terry Jan Reedy | 9af1836 | 2018-06-20 02:18:49 -0400 | [diff] [blame] | 47 | """Happens when it would be nice to open a calltip, but not really |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 48 | necessary, for example after an opening bracket, so function calls |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 49 | won't be made. |
| 50 | """ |
| 51 | self.open_calltip(False) |
| 52 | |
| 53 | def refresh_calltip_event(self, event): |
Tal Einat | 87e59ac | 2018-08-05 09:21:08 +0300 | [diff] [blame] | 54 | if self.active_calltip and self.active_calltip.tipwindow: |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 55 | self.open_calltip(False) |
| 56 | |
| 57 | def open_calltip(self, evalfuncs): |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 58 | self._remove_calltip_window() |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 59 | |
| 60 | hp = HyperParser(self.editwin, "insert") |
| 61 | sur_paren = hp.get_surrounding_brackets('(') |
| 62 | if not sur_paren: |
| 63 | return |
| 64 | hp.set_index(sur_paren[0]) |
Terry Jan Reedy | e606e23 | 2012-06-03 00:27:54 -0400 | [diff] [blame] | 65 | expression = hp.get_expression() |
| 66 | if not expression: |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 67 | return |
Terry Jan Reedy | e606e23 | 2012-06-03 00:27:54 -0400 | [diff] [blame] | 68 | if not evalfuncs and (expression.find('(') != -1): |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 69 | return |
Terry Jan Reedy | e606e23 | 2012-06-03 00:27:54 -0400 | [diff] [blame] | 70 | argspec = self.fetch_tip(expression) |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 71 | if not argspec: |
| 72 | return |
| 73 | self.active_calltip = self._calltip_window() |
| 74 | self.active_calltip.showtip(argspec, sur_paren[0], sur_paren[1]) |
Kurt B. Kaiser | 6655e4b | 2002-12-31 16:03:23 +0000 | [diff] [blame] | 75 | |
Terry Jan Reedy | e606e23 | 2012-06-03 00:27:54 -0400 | [diff] [blame] | 76 | def fetch_tip(self, expression): |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 77 | """Return the argument list and docstring of a function or class. |
Kurt B. Kaiser | 6655e4b | 2002-12-31 16:03:23 +0000 | [diff] [blame] | 78 | |
Kurt B. Kaiser | e54710b | 2002-12-12 19:15:39 +0000 | [diff] [blame] | 79 | If there is a Python subprocess, get the calltip there. Otherwise, |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 80 | either this fetch_tip() is running in the subprocess or it was |
| 81 | called in an IDLE running without the subprocess. |
Kurt B. Kaiser | e54710b | 2002-12-12 19:15:39 +0000 | [diff] [blame] | 82 | |
| 83 | The subprocess environment is that of the most recently run script. If |
| 84 | two unrelated modules are being edited some calltips in the current |
| 85 | module may be inoperative if the module was not the last to run. |
| 86 | |
Thomas Wouters | cf297e4 | 2007-02-23 15:07:44 +0000 | [diff] [blame] | 87 | To find methods, fetch_tip must be fed a fully qualified name. |
| 88 | |
Kurt B. Kaiser | 6655e4b | 2002-12-31 16:03:23 +0000 | [diff] [blame] | 89 | """ |
Kurt B. Kaiser | e54710b | 2002-12-12 19:15:39 +0000 | [diff] [blame] | 90 | try: |
| 91 | rpcclt = self.editwin.flist.pyshell.interp.rpcclt |
Terry Jan Reedy | e606e23 | 2012-06-03 00:27:54 -0400 | [diff] [blame] | 92 | except AttributeError: |
Kurt B. Kaiser | e54710b | 2002-12-12 19:15:39 +0000 | [diff] [blame] | 93 | rpcclt = None |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 94 | if rpcclt: |
| 95 | return rpcclt.remotecall("exec", "get_the_calltip", |
Terry Jan Reedy | e606e23 | 2012-06-03 00:27:54 -0400 | [diff] [blame] | 96 | (expression,), {}) |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 97 | else: |
Terry Jan Reedy | 2a2ce4f | 2012-06-07 19:41:04 -0400 | [diff] [blame] | 98 | return get_argspec(get_entity(expression)) |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 99 | |
wohlganger | 58fc71c | 2017-09-10 16:19:47 -0500 | [diff] [blame] | 100 | |
Terry Jan Reedy | 2a2ce4f | 2012-06-07 19:41:04 -0400 | [diff] [blame] | 101 | def get_entity(expression): |
| 102 | """Return the object corresponding to expression evaluated |
Terry Jan Reedy | 0fe4513 | 2019-03-24 17:12:28 -0400 | [diff] [blame] | 103 | in a namespace spanning sys.modules and __main.dict__. |
Terry Jan Reedy | 2a2ce4f | 2012-06-07 19:41:04 -0400 | [diff] [blame] | 104 | """ |
| 105 | if expression: |
Terry Jan Reedy | 0fe4513 | 2019-03-24 17:12:28 -0400 | [diff] [blame] | 106 | namespace = {**sys.modules, **__main__.__dict__} |
Terry Jan Reedy | 2a2ce4f | 2012-06-07 19:41:04 -0400 | [diff] [blame] | 107 | try: |
Terry Jan Reedy | 2b75155 | 2019-03-23 03:50:15 -0400 | [diff] [blame] | 108 | return eval(expression, namespace) # Only protect user code. |
Terry Jan Reedy | 2a2ce4f | 2012-06-07 19:41:04 -0400 | [diff] [blame] | 109 | except BaseException: |
| 110 | # An uncaught exception closes idle, and eval can raise any |
| 111 | # exception, especially if user classes are involved. |
| 112 | return None |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 113 | |
Terry Jan Reedy | d5710f8 | 2014-01-21 20:45:17 -0500 | [diff] [blame] | 114 | # The following are used in get_argspec and some in tests |
Terry Jan Reedy | a0f1e22 | 2014-01-26 19:55:34 -0500 | [diff] [blame] | 115 | _MAX_COLS = 85 |
Terry Jan Reedy | d5710f8 | 2014-01-21 20:45:17 -0500 | [diff] [blame] | 116 | _MAX_LINES = 5 # enough for bytes |
Terry Jan Reedy | a0f1e22 | 2014-01-26 19:55:34 -0500 | [diff] [blame] | 117 | _INDENT = ' '*4 # for wrapped signatures |
R David Murray | 44b548d | 2016-09-08 13:59:53 -0400 | [diff] [blame] | 118 | _first_param = re.compile(r'(?<=\()\w*\,?\s*') |
Terry Jan Reedy | 715476d | 2014-01-21 15:36:51 -0500 | [diff] [blame] | 119 | _default_callable_argspec = "See source or doc" |
Louie Lu | 3b0f620 | 2017-08-10 08:58:13 +0800 | [diff] [blame] | 120 | _invalid_method = "invalid method signature" |
Miss Islington (bot) | 39346ff | 2019-06-04 19:11:42 -0700 | [diff] [blame] | 121 | _argument_positional = " # '/' marks preceding args as positional-only." |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 122 | |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 123 | def get_argspec(ob): |
Terry Jan Reedy | 715476d | 2014-01-21 15:36:51 -0500 | [diff] [blame] | 124 | '''Return a string describing the signature of a callable object, or ''. |
Terry Jan Reedy | 2a2ce4f | 2012-06-07 19:41:04 -0400 | [diff] [blame] | 125 | |
| 126 | For Python-coded functions and methods, the first line is introspected. |
| 127 | Delete 'self' parameter for classes (.__init__) and bound methods. |
Terry Jan Reedy | d5710f8 | 2014-01-21 20:45:17 -0500 | [diff] [blame] | 128 | The next lines are the first lines of the doc string up to the first |
| 129 | empty line or _MAX_LINES. For builtins, this typically includes |
| 130 | the arguments in addition to the return value. |
Terry Jan Reedy | 2a2ce4f | 2012-06-07 19:41:04 -0400 | [diff] [blame] | 131 | ''' |
Louie Lu | 3b0f620 | 2017-08-10 08:58:13 +0800 | [diff] [blame] | 132 | argspec = default = "" |
Terry Jan Reedy | 715476d | 2014-01-21 15:36:51 -0500 | [diff] [blame] | 133 | try: |
| 134 | ob_call = ob.__call__ |
| 135 | except BaseException: |
Louie Lu | 3b0f620 | 2017-08-10 08:58:13 +0800 | [diff] [blame] | 136 | return default |
| 137 | |
| 138 | fob = ob_call if isinstance(ob_call, types.MethodType) else ob |
| 139 | |
| 140 | try: |
| 141 | argspec = str(inspect.signature(fob)) |
| 142 | except ValueError as err: |
| 143 | msg = str(err) |
| 144 | if msg.startswith(_invalid_method): |
| 145 | return _invalid_method |
| 146 | |
Miss Islington (bot) | 39346ff | 2019-06-04 19:11:42 -0700 | [diff] [blame] | 147 | if '/' in argspec and len(argspec) < _MAX_COLS - len(_argument_positional): |
| 148 | # Add explanation TODO remove after 3.7, before 3.9. |
Louie Lu | 3b0f620 | 2017-08-10 08:58:13 +0800 | [diff] [blame] | 149 | argspec += _argument_positional |
| 150 | if isinstance(fob, type) and argspec == '()': |
Miss Islington (bot) | 39346ff | 2019-06-04 19:11:42 -0700 | [diff] [blame] | 151 | # If fob has no argument, use default callable argspec. |
Louie Lu | 3b0f620 | 2017-08-10 08:58:13 +0800 | [diff] [blame] | 152 | argspec = _default_callable_argspec |
Terry Jan Reedy | 2a2ce4f | 2012-06-07 19:41:04 -0400 | [diff] [blame] | 153 | |
Terry Jan Reedy | a0f1e22 | 2014-01-26 19:55:34 -0500 | [diff] [blame] | 154 | lines = (textwrap.wrap(argspec, _MAX_COLS, subsequent_indent=_INDENT) |
Louie Lu | 3b0f620 | 2017-08-10 08:58:13 +0800 | [diff] [blame] | 155 | if len(argspec) > _MAX_COLS else [argspec] if argspec else []) |
Terry Jan Reedy | a0f1e22 | 2014-01-26 19:55:34 -0500 | [diff] [blame] | 156 | |
Terry Jan Reedy | 715476d | 2014-01-21 15:36:51 -0500 | [diff] [blame] | 157 | if isinstance(ob_call, types.MethodType): |
| 158 | doc = ob_call.__doc__ |
| 159 | else: |
| 160 | doc = getattr(ob, "__doc__", "") |
| 161 | if doc: |
Terry Jan Reedy | a0f1e22 | 2014-01-26 19:55:34 -0500 | [diff] [blame] | 162 | for line in doc.split('\n', _MAX_LINES)[:_MAX_LINES]: |
Terry Jan Reedy | d5710f8 | 2014-01-21 20:45:17 -0500 | [diff] [blame] | 163 | line = line.strip() |
| 164 | if not line: |
| 165 | break |
| 166 | if len(line) > _MAX_COLS: |
| 167 | line = line[: _MAX_COLS - 3] + '...' |
| 168 | lines.append(line) |
Emmanuel Arias | ab54b9a | 2019-01-03 04:47:58 -0300 | [diff] [blame] | 169 | argspec = '\n'.join(lines) |
Terry Jan Reedy | 715476d | 2014-01-21 15:36:51 -0500 | [diff] [blame] | 170 | if not argspec: |
| 171 | argspec = _default_callable_argspec |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 172 | return argspec |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 173 | |
Louie Lu | 3b0f620 | 2017-08-10 08:58:13 +0800 | [diff] [blame] | 174 | |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 175 | if __name__ == '__main__': |
Terry Jan Reedy | db4e5c5 | 2013-05-27 21:32:03 -0400 | [diff] [blame] | 176 | from unittest import main |
Terry Jan Reedy | 06e2029 | 2018-06-19 23:00:35 -0400 | [diff] [blame] | 177 | main('idlelib.idle_test.test_calltip', verbosity=2) |