Terry Jan Reedy | 6fa5bdc | 2016-05-28 13:22:31 -0400 | [diff] [blame] | 1 | """calltips.py - An IDLE Extension to Jog Your Memory |
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. |
Thomas Wouters | cf297e4 | 2007-02-23 15:07:44 +0000 | [diff] [blame] | 6 | |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 7 | """ |
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 |
Terry Jan Reedy | bfbaa6b | 2016-08-31 00:50:55 -0400 | [diff] [blame] | 16 | import __main__ |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 17 | |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 18 | class CallTips: |
| 19 | |
| 20 | menudefs = [ |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 21 | ('edit', [ |
| 22 | ("Show call tip", "<<force-open-calltip>>"), |
| 23 | ]) |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 24 | ] |
| 25 | |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 26 | def __init__(self, editwin=None): |
Raymond Hettinger | c5e378d | 2004-05-04 08:34:56 +0000 | [diff] [blame] | 27 | if editwin is None: # subprocess and test |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 28 | self.editwin = None |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 29 | else: |
| 30 | self.editwin = editwin |
| 31 | self.text = editwin.text |
| 32 | self.active_calltip = None |
| 33 | self._calltip_window = self._make_tk_calltip_window |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 34 | |
| 35 | def close(self): |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 36 | self._calltip_window = None |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 37 | |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 38 | def _make_tk_calltip_window(self): |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 39 | # See __init__ for usage |
Terry Jan Reedy | 6fa5bdc | 2016-05-28 13:22:31 -0400 | [diff] [blame] | 40 | return calltip_w.CallTip(self.text) |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 41 | |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 42 | def _remove_calltip_window(self, event=None): |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 43 | if self.active_calltip: |
| 44 | self.active_calltip.hidetip() |
| 45 | self.active_calltip = None |
Kurt B. Kaiser | ae67647 | 2001-07-12 23:10:35 +0000 | [diff] [blame] | 46 | |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 47 | def force_open_calltip_event(self, event): |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 48 | "The user selected the menu entry or hotkey, open the tip." |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 49 | self.open_calltip(True) |
Serhiy Storchaka | 213ce12 | 2017-06-27 07:02:32 +0300 | [diff] [blame^] | 50 | return "break" |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 51 | |
| 52 | def try_open_calltip_event(self, event): |
| 53 | """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] | 54 | necessary, for example after an opening bracket, so function calls |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 55 | won't be made. |
| 56 | """ |
| 57 | self.open_calltip(False) |
| 58 | |
| 59 | def refresh_calltip_event(self, event): |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 60 | if self.active_calltip and self.active_calltip.is_active(): |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 61 | self.open_calltip(False) |
| 62 | |
| 63 | def open_calltip(self, evalfuncs): |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 64 | self._remove_calltip_window() |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 65 | |
| 66 | hp = HyperParser(self.editwin, "insert") |
| 67 | sur_paren = hp.get_surrounding_brackets('(') |
| 68 | if not sur_paren: |
| 69 | return |
| 70 | hp.set_index(sur_paren[0]) |
Terry Jan Reedy | e606e23 | 2012-06-03 00:27:54 -0400 | [diff] [blame] | 71 | expression = hp.get_expression() |
| 72 | if not expression: |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 73 | return |
Terry Jan Reedy | e606e23 | 2012-06-03 00:27:54 -0400 | [diff] [blame] | 74 | if not evalfuncs and (expression.find('(') != -1): |
Kurt B. Kaiser | b175445 | 2005-11-18 22:05:48 +0000 | [diff] [blame] | 75 | return |
Terry Jan Reedy | e606e23 | 2012-06-03 00:27:54 -0400 | [diff] [blame] | 76 | argspec = self.fetch_tip(expression) |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 77 | if not argspec: |
| 78 | return |
| 79 | self.active_calltip = self._calltip_window() |
| 80 | self.active_calltip.showtip(argspec, sur_paren[0], sur_paren[1]) |
Kurt B. Kaiser | 6655e4b | 2002-12-31 16:03:23 +0000 | [diff] [blame] | 81 | |
Terry Jan Reedy | e606e23 | 2012-06-03 00:27:54 -0400 | [diff] [blame] | 82 | def fetch_tip(self, expression): |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 83 | """Return the argument list and docstring of a function or class. |
Kurt B. Kaiser | 6655e4b | 2002-12-31 16:03:23 +0000 | [diff] [blame] | 84 | |
Kurt B. Kaiser | e54710b | 2002-12-12 19:15:39 +0000 | [diff] [blame] | 85 | If there is a Python subprocess, get the calltip there. Otherwise, |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 86 | either this fetch_tip() is running in the subprocess or it was |
| 87 | called in an IDLE running without the subprocess. |
Kurt B. Kaiser | e54710b | 2002-12-12 19:15:39 +0000 | [diff] [blame] | 88 | |
| 89 | The subprocess environment is that of the most recently run script. If |
| 90 | two unrelated modules are being edited some calltips in the current |
| 91 | module may be inoperative if the module was not the last to run. |
| 92 | |
Thomas Wouters | cf297e4 | 2007-02-23 15:07:44 +0000 | [diff] [blame] | 93 | To find methods, fetch_tip must be fed a fully qualified name. |
| 94 | |
Kurt B. Kaiser | 6655e4b | 2002-12-31 16:03:23 +0000 | [diff] [blame] | 95 | """ |
Kurt B. Kaiser | e54710b | 2002-12-12 19:15:39 +0000 | [diff] [blame] | 96 | try: |
| 97 | rpcclt = self.editwin.flist.pyshell.interp.rpcclt |
Terry Jan Reedy | e606e23 | 2012-06-03 00:27:54 -0400 | [diff] [blame] | 98 | except AttributeError: |
Kurt B. Kaiser | e54710b | 2002-12-12 19:15:39 +0000 | [diff] [blame] | 99 | rpcclt = None |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 100 | if rpcclt: |
| 101 | return rpcclt.remotecall("exec", "get_the_calltip", |
Terry Jan Reedy | e606e23 | 2012-06-03 00:27:54 -0400 | [diff] [blame] | 102 | (expression,), {}) |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 103 | else: |
Terry Jan Reedy | 2a2ce4f | 2012-06-07 19:41:04 -0400 | [diff] [blame] | 104 | return get_argspec(get_entity(expression)) |
Kurt B. Kaiser | 5afa1df | 2002-10-10 08:25:24 +0000 | [diff] [blame] | 105 | |
Terry Jan Reedy | 2a2ce4f | 2012-06-07 19:41:04 -0400 | [diff] [blame] | 106 | def get_entity(expression): |
| 107 | """Return the object corresponding to expression evaluated |
| 108 | in a namespace spanning sys.modules and __main.dict__. |
| 109 | """ |
| 110 | if expression: |
| 111 | namespace = sys.modules.copy() |
| 112 | namespace.update(__main__.__dict__) |
| 113 | try: |
| 114 | return eval(expression, namespace) |
| 115 | except BaseException: |
| 116 | # An uncaught exception closes idle, and eval can raise any |
| 117 | # exception, especially if user classes are involved. |
| 118 | return None |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 119 | |
Terry Jan Reedy | d5710f8 | 2014-01-21 20:45:17 -0500 | [diff] [blame] | 120 | # The following are used in get_argspec and some in tests |
Terry Jan Reedy | a0f1e22 | 2014-01-26 19:55:34 -0500 | [diff] [blame] | 121 | _MAX_COLS = 85 |
Terry Jan Reedy | d5710f8 | 2014-01-21 20:45:17 -0500 | [diff] [blame] | 122 | _MAX_LINES = 5 # enough for bytes |
Terry Jan Reedy | a0f1e22 | 2014-01-26 19:55:34 -0500 | [diff] [blame] | 123 | _INDENT = ' '*4 # for wrapped signatures |
R David Murray | 44b548d | 2016-09-08 13:59:53 -0400 | [diff] [blame] | 124 | _first_param = re.compile(r'(?<=\()\w*\,?\s*') |
Terry Jan Reedy | 715476d | 2014-01-21 15:36:51 -0500 | [diff] [blame] | 125 | _default_callable_argspec = "See source or doc" |
David Scherer | 7aced17 | 2000-08-15 01:13:23 +0000 | [diff] [blame] | 126 | |
Terry Jan Reedy | d5710f8 | 2014-01-21 20:45:17 -0500 | [diff] [blame] | 127 | |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 128 | def get_argspec(ob): |
Terry Jan Reedy | 715476d | 2014-01-21 15:36:51 -0500 | [diff] [blame] | 129 | '''Return a string describing the signature of a callable object, or ''. |
Terry Jan Reedy | 2a2ce4f | 2012-06-07 19:41:04 -0400 | [diff] [blame] | 130 | |
| 131 | For Python-coded functions and methods, the first line is introspected. |
| 132 | Delete 'self' parameter for classes (.__init__) and bound methods. |
Terry Jan Reedy | d5710f8 | 2014-01-21 20:45:17 -0500 | [diff] [blame] | 133 | The next lines are the first lines of the doc string up to the first |
| 134 | empty line or _MAX_LINES. For builtins, this typically includes |
| 135 | the arguments in addition to the return value. |
Terry Jan Reedy | 2a2ce4f | 2012-06-07 19:41:04 -0400 | [diff] [blame] | 136 | ''' |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 137 | argspec = "" |
Terry Jan Reedy | 715476d | 2014-01-21 15:36:51 -0500 | [diff] [blame] | 138 | try: |
| 139 | ob_call = ob.__call__ |
| 140 | except BaseException: |
| 141 | return argspec |
| 142 | if isinstance(ob, type): |
| 143 | fob = ob.__init__ |
| 144 | elif isinstance(ob_call, types.MethodType): |
| 145 | fob = ob_call |
| 146 | else: |
| 147 | fob = ob |
| 148 | if isinstance(fob, (types.FunctionType, types.MethodType)): |
| 149 | argspec = inspect.formatargspec(*inspect.getfullargspec(fob)) |
| 150 | if (isinstance(ob, (type, types.MethodType)) or |
| 151 | isinstance(ob_call, types.MethodType)): |
| 152 | argspec = _first_param.sub("", 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) |
| 155 | if len(argspec) > _MAX_COLS else [argspec] if argspec else []) |
| 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) |
| 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 | |
Kurt B. Kaiser | 152b3c2 | 2007-08-30 06:35:15 +0000 | [diff] [blame] | 174 | if __name__ == '__main__': |
Terry Jan Reedy | db4e5c5 | 2013-05-27 21:32:03 -0400 | [diff] [blame] | 175 | from unittest import main |
Terry Jan Reedy | 715476d | 2014-01-21 15:36:51 -0500 | [diff] [blame] | 176 | main('idlelib.idle_test.test_calltips', verbosity=2) |