##// END OF EJS Templates
_default_arguments_from_docstring docstring style
Piti Ongmongkolkul -
Show More
@@ -1,979 +1,981 b''
1 """Word completion for IPython.
1 """Word completion for IPython.
2
2
3 This module is a fork of the rlcompleter module in the Python standard
3 This module is a fork of the rlcompleter module in the Python standard
4 library. The original enhancements made to rlcompleter have been sent
4 library. The original enhancements made to rlcompleter have been sent
5 upstream and were accepted as of Python 2.3, but we need a lot more
5 upstream and were accepted as of Python 2.3, but we need a lot more
6 functionality specific to IPython, so this module will continue to live as an
6 functionality specific to IPython, so this module will continue to live as an
7 IPython-specific utility.
7 IPython-specific utility.
8
8
9 Original rlcompleter documentation:
9 Original rlcompleter documentation:
10
10
11 This requires the latest extension to the readline module (the
11 This requires the latest extension to the readline module (the
12 completes keywords, built-ins and globals in __main__; when completing
12 completes keywords, built-ins and globals in __main__; when completing
13 NAME.NAME..., it evaluates (!) the expression up to the last dot and
13 NAME.NAME..., it evaluates (!) the expression up to the last dot and
14 completes its attributes.
14 completes its attributes.
15
15
16 It's very cool to do "import string" type "string.", hit the
16 It's very cool to do "import string" type "string.", hit the
17 completion key (twice), and see the list of names defined by the
17 completion key (twice), and see the list of names defined by the
18 string module!
18 string module!
19
19
20 Tip: to use the tab key as the completion key, call
20 Tip: to use the tab key as the completion key, call
21
21
22 readline.parse_and_bind("tab: complete")
22 readline.parse_and_bind("tab: complete")
23
23
24 Notes:
24 Notes:
25
25
26 - Exceptions raised by the completer function are *ignored* (and
26 - Exceptions raised by the completer function are *ignored* (and
27 generally cause the completion to fail). This is a feature -- since
27 generally cause the completion to fail). This is a feature -- since
28 readline sets the tty device in raw (or cbreak) mode, printing a
28 readline sets the tty device in raw (or cbreak) mode, printing a
29 traceback wouldn't work well without some complicated hoopla to save,
29 traceback wouldn't work well without some complicated hoopla to save,
30 reset and restore the tty state.
30 reset and restore the tty state.
31
31
32 - The evaluation of the NAME.NAME... form may cause arbitrary
32 - The evaluation of the NAME.NAME... form may cause arbitrary
33 application defined code to be executed if an object with a
33 application defined code to be executed if an object with a
34 __getattr__ hook is found. Since it is the responsibility of the
34 __getattr__ hook is found. Since it is the responsibility of the
35 application (or the user) to enable this feature, I consider this an
35 application (or the user) to enable this feature, I consider this an
36 acceptable risk. More complicated expressions (e.g. function calls or
36 acceptable risk. More complicated expressions (e.g. function calls or
37 indexing operations) are *not* evaluated.
37 indexing operations) are *not* evaluated.
38
38
39 - GNU readline is also used by the built-in functions input() and
39 - GNU readline is also used by the built-in functions input() and
40 raw_input(), and thus these also benefit/suffer from the completer
40 raw_input(), and thus these also benefit/suffer from the completer
41 features. Clearly an interactive application can benefit by
41 features. Clearly an interactive application can benefit by
42 specifying its own completer function and using raw_input() for all
42 specifying its own completer function and using raw_input() for all
43 its input.
43 its input.
44
44
45 - When the original stdin is not a tty device, GNU readline is never
45 - When the original stdin is not a tty device, GNU readline is never
46 used, and this module (and the readline module) are silently inactive.
46 used, and this module (and the readline module) are silently inactive.
47 """
47 """
48
48
49 #*****************************************************************************
49 #*****************************************************************************
50 #
50 #
51 # Since this file is essentially a minimally modified copy of the rlcompleter
51 # Since this file is essentially a minimally modified copy of the rlcompleter
52 # module which is part of the standard Python distribution, I assume that the
52 # module which is part of the standard Python distribution, I assume that the
53 # proper procedure is to maintain its copyright as belonging to the Python
53 # proper procedure is to maintain its copyright as belonging to the Python
54 # Software Foundation (in addition to my own, for all new code).
54 # Software Foundation (in addition to my own, for all new code).
55 #
55 #
56 # Copyright (C) 2008 IPython Development Team
56 # Copyright (C) 2008 IPython Development Team
57 # Copyright (C) 2001 Fernando Perez. <fperez@colorado.edu>
57 # Copyright (C) 2001 Fernando Perez. <fperez@colorado.edu>
58 # Copyright (C) 2001 Python Software Foundation, www.python.org
58 # Copyright (C) 2001 Python Software Foundation, www.python.org
59 #
59 #
60 # Distributed under the terms of the BSD License. The full license is in
60 # Distributed under the terms of the BSD License. The full license is in
61 # the file COPYING, distributed as part of this software.
61 # the file COPYING, distributed as part of this software.
62 #
62 #
63 #*****************************************************************************
63 #*****************************************************************************
64
64
65 #-----------------------------------------------------------------------------
65 #-----------------------------------------------------------------------------
66 # Imports
66 # Imports
67 #-----------------------------------------------------------------------------
67 #-----------------------------------------------------------------------------
68
68
69 import __builtin__
69 import __builtin__
70 import __main__
70 import __main__
71 import glob
71 import glob
72 import inspect
72 import inspect
73 import itertools
73 import itertools
74 import keyword
74 import keyword
75 import os
75 import os
76 import re
76 import re
77 import shlex
77 import shlex
78 import sys
78 import sys
79 import StringIO
79 import StringIO
80
80
81 from IPython.config.configurable import Configurable
81 from IPython.config.configurable import Configurable
82 from IPython.core.error import TryNext
82 from IPython.core.error import TryNext
83 from IPython.core.inputsplitter import ESC_MAGIC
83 from IPython.core.inputsplitter import ESC_MAGIC
84 from IPython.utils import generics
84 from IPython.utils import generics
85 from IPython.utils import io
85 from IPython.utils import io
86 from IPython.utils.dir2 import dir2
86 from IPython.utils.dir2 import dir2
87 from IPython.utils.process import arg_split
87 from IPython.utils.process import arg_split
88 from IPython.utils.traitlets import CBool, Enum
88 from IPython.utils.traitlets import CBool, Enum
89
89
90 #-----------------------------------------------------------------------------
90 #-----------------------------------------------------------------------------
91 # Globals
91 # Globals
92 #-----------------------------------------------------------------------------
92 #-----------------------------------------------------------------------------
93
93
94 # Public API
94 # Public API
95 __all__ = ['Completer','IPCompleter']
95 __all__ = ['Completer','IPCompleter']
96
96
97 if sys.platform == 'win32':
97 if sys.platform == 'win32':
98 PROTECTABLES = ' '
98 PROTECTABLES = ' '
99 else:
99 else:
100 PROTECTABLES = ' ()[]{}?=\\|;:\'#*"^&'
100 PROTECTABLES = ' ()[]{}?=\\|;:\'#*"^&'
101
101
102 #-----------------------------------------------------------------------------
102 #-----------------------------------------------------------------------------
103 # Main functions and classes
103 # Main functions and classes
104 #-----------------------------------------------------------------------------
104 #-----------------------------------------------------------------------------
105
105
106 def has_open_quotes(s):
106 def has_open_quotes(s):
107 """Return whether a string has open quotes.
107 """Return whether a string has open quotes.
108
108
109 This simply counts whether the number of quote characters of either type in
109 This simply counts whether the number of quote characters of either type in
110 the string is odd.
110 the string is odd.
111
111
112 Returns
112 Returns
113 -------
113 -------
114 If there is an open quote, the quote character is returned. Else, return
114 If there is an open quote, the quote character is returned. Else, return
115 False.
115 False.
116 """
116 """
117 # We check " first, then ', so complex cases with nested quotes will get
117 # We check " first, then ', so complex cases with nested quotes will get
118 # the " to take precedence.
118 # the " to take precedence.
119 if s.count('"') % 2:
119 if s.count('"') % 2:
120 return '"'
120 return '"'
121 elif s.count("'") % 2:
121 elif s.count("'") % 2:
122 return "'"
122 return "'"
123 else:
123 else:
124 return False
124 return False
125
125
126
126
127 def protect_filename(s):
127 def protect_filename(s):
128 """Escape a string to protect certain characters."""
128 """Escape a string to protect certain characters."""
129
129
130 return "".join([(ch in PROTECTABLES and '\\' + ch or ch)
130 return "".join([(ch in PROTECTABLES and '\\' + ch or ch)
131 for ch in s])
131 for ch in s])
132
132
133 def expand_user(path):
133 def expand_user(path):
134 """Expand '~'-style usernames in strings.
134 """Expand '~'-style usernames in strings.
135
135
136 This is similar to :func:`os.path.expanduser`, but it computes and returns
136 This is similar to :func:`os.path.expanduser`, but it computes and returns
137 extra information that will be useful if the input was being used in
137 extra information that will be useful if the input was being used in
138 computing completions, and you wish to return the completions with the
138 computing completions, and you wish to return the completions with the
139 original '~' instead of its expanded value.
139 original '~' instead of its expanded value.
140
140
141 Parameters
141 Parameters
142 ----------
142 ----------
143 path : str
143 path : str
144 String to be expanded. If no ~ is present, the output is the same as the
144 String to be expanded. If no ~ is present, the output is the same as the
145 input.
145 input.
146
146
147 Returns
147 Returns
148 -------
148 -------
149 newpath : str
149 newpath : str
150 Result of ~ expansion in the input path.
150 Result of ~ expansion in the input path.
151 tilde_expand : bool
151 tilde_expand : bool
152 Whether any expansion was performed or not.
152 Whether any expansion was performed or not.
153 tilde_val : str
153 tilde_val : str
154 The value that ~ was replaced with.
154 The value that ~ was replaced with.
155 """
155 """
156 # Default values
156 # Default values
157 tilde_expand = False
157 tilde_expand = False
158 tilde_val = ''
158 tilde_val = ''
159 newpath = path
159 newpath = path
160
160
161 if path.startswith('~'):
161 if path.startswith('~'):
162 tilde_expand = True
162 tilde_expand = True
163 rest = len(path)-1
163 rest = len(path)-1
164 newpath = os.path.expanduser(path)
164 newpath = os.path.expanduser(path)
165 if rest:
165 if rest:
166 tilde_val = newpath[:-rest]
166 tilde_val = newpath[:-rest]
167 else:
167 else:
168 tilde_val = newpath
168 tilde_val = newpath
169
169
170 return newpath, tilde_expand, tilde_val
170 return newpath, tilde_expand, tilde_val
171
171
172
172
173 def compress_user(path, tilde_expand, tilde_val):
173 def compress_user(path, tilde_expand, tilde_val):
174 """Does the opposite of expand_user, with its outputs.
174 """Does the opposite of expand_user, with its outputs.
175 """
175 """
176 if tilde_expand:
176 if tilde_expand:
177 return path.replace(tilde_val, '~')
177 return path.replace(tilde_val, '~')
178 else:
178 else:
179 return path
179 return path
180
180
181
181
182 class Bunch(object): pass
182 class Bunch(object): pass
183
183
184
184
185 DELIMS = ' \t\n`!@#$^&*()=+[{]}\\|;:\'",<>?'
185 DELIMS = ' \t\n`!@#$^&*()=+[{]}\\|;:\'",<>?'
186 GREEDY_DELIMS = ' \r\n'
186 GREEDY_DELIMS = ' \r\n'
187
187
188
188
189 class CompletionSplitter(object):
189 class CompletionSplitter(object):
190 """An object to split an input line in a manner similar to readline.
190 """An object to split an input line in a manner similar to readline.
191
191
192 By having our own implementation, we can expose readline-like completion in
192 By having our own implementation, we can expose readline-like completion in
193 a uniform manner to all frontends. This object only needs to be given the
193 a uniform manner to all frontends. This object only needs to be given the
194 line of text to be split and the cursor position on said line, and it
194 line of text to be split and the cursor position on said line, and it
195 returns the 'word' to be completed on at the cursor after splitting the
195 returns the 'word' to be completed on at the cursor after splitting the
196 entire line.
196 entire line.
197
197
198 What characters are used as splitting delimiters can be controlled by
198 What characters are used as splitting delimiters can be controlled by
199 setting the `delims` attribute (this is a property that internally
199 setting the `delims` attribute (this is a property that internally
200 automatically builds the necessary regular expression)"""
200 automatically builds the necessary regular expression)"""
201
201
202 # Private interface
202 # Private interface
203
203
204 # A string of delimiter characters. The default value makes sense for
204 # A string of delimiter characters. The default value makes sense for
205 # IPython's most typical usage patterns.
205 # IPython's most typical usage patterns.
206 _delims = DELIMS
206 _delims = DELIMS
207
207
208 # The expression (a normal string) to be compiled into a regular expression
208 # The expression (a normal string) to be compiled into a regular expression
209 # for actual splitting. We store it as an attribute mostly for ease of
209 # for actual splitting. We store it as an attribute mostly for ease of
210 # debugging, since this type of code can be so tricky to debug.
210 # debugging, since this type of code can be so tricky to debug.
211 _delim_expr = None
211 _delim_expr = None
212
212
213 # The regular expression that does the actual splitting
213 # The regular expression that does the actual splitting
214 _delim_re = None
214 _delim_re = None
215
215
216 def __init__(self, delims=None):
216 def __init__(self, delims=None):
217 delims = CompletionSplitter._delims if delims is None else delims
217 delims = CompletionSplitter._delims if delims is None else delims
218 self.delims = delims
218 self.delims = delims
219
219
220 @property
220 @property
221 def delims(self):
221 def delims(self):
222 """Return the string of delimiter characters."""
222 """Return the string of delimiter characters."""
223 return self._delims
223 return self._delims
224
224
225 @delims.setter
225 @delims.setter
226 def delims(self, delims):
226 def delims(self, delims):
227 """Set the delimiters for line splitting."""
227 """Set the delimiters for line splitting."""
228 expr = '[' + ''.join('\\'+ c for c in delims) + ']'
228 expr = '[' + ''.join('\\'+ c for c in delims) + ']'
229 self._delim_re = re.compile(expr)
229 self._delim_re = re.compile(expr)
230 self._delims = delims
230 self._delims = delims
231 self._delim_expr = expr
231 self._delim_expr = expr
232
232
233 def split_line(self, line, cursor_pos=None):
233 def split_line(self, line, cursor_pos=None):
234 """Split a line of text with a cursor at the given position.
234 """Split a line of text with a cursor at the given position.
235 """
235 """
236 l = line if cursor_pos is None else line[:cursor_pos]
236 l = line if cursor_pos is None else line[:cursor_pos]
237 return self._delim_re.split(l)[-1]
237 return self._delim_re.split(l)[-1]
238
238
239
239
240 class Completer(Configurable):
240 class Completer(Configurable):
241
241
242 greedy = CBool(False, config=True,
242 greedy = CBool(False, config=True,
243 help="""Activate greedy completion
243 help="""Activate greedy completion
244
244
245 This will enable completion on elements of lists, results of function calls, etc.,
245 This will enable completion on elements of lists, results of function calls, etc.,
246 but can be unsafe because the code is actually evaluated on TAB.
246 but can be unsafe because the code is actually evaluated on TAB.
247 """
247 """
248 )
248 )
249
249
250
250
251 def __init__(self, namespace=None, global_namespace=None, config=None, **kwargs):
251 def __init__(self, namespace=None, global_namespace=None, config=None, **kwargs):
252 """Create a new completer for the command line.
252 """Create a new completer for the command line.
253
253
254 Completer(namespace=ns,global_namespace=ns2) -> completer instance.
254 Completer(namespace=ns,global_namespace=ns2) -> completer instance.
255
255
256 If unspecified, the default namespace where completions are performed
256 If unspecified, the default namespace where completions are performed
257 is __main__ (technically, __main__.__dict__). Namespaces should be
257 is __main__ (technically, __main__.__dict__). Namespaces should be
258 given as dictionaries.
258 given as dictionaries.
259
259
260 An optional second namespace can be given. This allows the completer
260 An optional second namespace can be given. This allows the completer
261 to handle cases where both the local and global scopes need to be
261 to handle cases where both the local and global scopes need to be
262 distinguished.
262 distinguished.
263
263
264 Completer instances should be used as the completion mechanism of
264 Completer instances should be used as the completion mechanism of
265 readline via the set_completer() call:
265 readline via the set_completer() call:
266
266
267 readline.set_completer(Completer(my_namespace).complete)
267 readline.set_completer(Completer(my_namespace).complete)
268 """
268 """
269
269
270 # Don't bind to namespace quite yet, but flag whether the user wants a
270 # Don't bind to namespace quite yet, but flag whether the user wants a
271 # specific namespace or to use __main__.__dict__. This will allow us
271 # specific namespace or to use __main__.__dict__. This will allow us
272 # to bind to __main__.__dict__ at completion time, not now.
272 # to bind to __main__.__dict__ at completion time, not now.
273 if namespace is None:
273 if namespace is None:
274 self.use_main_ns = 1
274 self.use_main_ns = 1
275 else:
275 else:
276 self.use_main_ns = 0
276 self.use_main_ns = 0
277 self.namespace = namespace
277 self.namespace = namespace
278
278
279 # The global namespace, if given, can be bound directly
279 # The global namespace, if given, can be bound directly
280 if global_namespace is None:
280 if global_namespace is None:
281 self.global_namespace = {}
281 self.global_namespace = {}
282 else:
282 else:
283 self.global_namespace = global_namespace
283 self.global_namespace = global_namespace
284
284
285 super(Completer, self).__init__(config=config, **kwargs)
285 super(Completer, self).__init__(config=config, **kwargs)
286
286
287 def complete(self, text, state):
287 def complete(self, text, state):
288 """Return the next possible completion for 'text'.
288 """Return the next possible completion for 'text'.
289
289
290 This is called successively with state == 0, 1, 2, ... until it
290 This is called successively with state == 0, 1, 2, ... until it
291 returns None. The completion should begin with 'text'.
291 returns None. The completion should begin with 'text'.
292
292
293 """
293 """
294 if self.use_main_ns:
294 if self.use_main_ns:
295 self.namespace = __main__.__dict__
295 self.namespace = __main__.__dict__
296
296
297 if state == 0:
297 if state == 0:
298 if "." in text:
298 if "." in text:
299 self.matches = self.attr_matches(text)
299 self.matches = self.attr_matches(text)
300 else:
300 else:
301 self.matches = self.global_matches(text)
301 self.matches = self.global_matches(text)
302 try:
302 try:
303 return self.matches[state]
303 return self.matches[state]
304 except IndexError:
304 except IndexError:
305 return None
305 return None
306
306
307 def global_matches(self, text):
307 def global_matches(self, text):
308 """Compute matches when text is a simple name.
308 """Compute matches when text is a simple name.
309
309
310 Return a list of all keywords, built-in functions and names currently
310 Return a list of all keywords, built-in functions and names currently
311 defined in self.namespace or self.global_namespace that match.
311 defined in self.namespace or self.global_namespace that match.
312
312
313 """
313 """
314 #print 'Completer->global_matches, txt=%r' % text # dbg
314 #print 'Completer->global_matches, txt=%r' % text # dbg
315 matches = []
315 matches = []
316 match_append = matches.append
316 match_append = matches.append
317 n = len(text)
317 n = len(text)
318 for lst in [keyword.kwlist,
318 for lst in [keyword.kwlist,
319 __builtin__.__dict__.keys(),
319 __builtin__.__dict__.keys(),
320 self.namespace.keys(),
320 self.namespace.keys(),
321 self.global_namespace.keys()]:
321 self.global_namespace.keys()]:
322 for word in lst:
322 for word in lst:
323 if word[:n] == text and word != "__builtins__":
323 if word[:n] == text and word != "__builtins__":
324 match_append(word)
324 match_append(word)
325 return matches
325 return matches
326
326
327 def attr_matches(self, text):
327 def attr_matches(self, text):
328 """Compute matches when text contains a dot.
328 """Compute matches when text contains a dot.
329
329
330 Assuming the text is of the form NAME.NAME....[NAME], and is
330 Assuming the text is of the form NAME.NAME....[NAME], and is
331 evaluatable in self.namespace or self.global_namespace, it will be
331 evaluatable in self.namespace or self.global_namespace, it will be
332 evaluated and its attributes (as revealed by dir()) are used as
332 evaluated and its attributes (as revealed by dir()) are used as
333 possible completions. (For class instances, class members are are
333 possible completions. (For class instances, class members are are
334 also considered.)
334 also considered.)
335
335
336 WARNING: this can still invoke arbitrary C code, if an object
336 WARNING: this can still invoke arbitrary C code, if an object
337 with a __getattr__ hook is evaluated.
337 with a __getattr__ hook is evaluated.
338
338
339 """
339 """
340
340
341 #io.rprint('Completer->attr_matches, txt=%r' % text) # dbg
341 #io.rprint('Completer->attr_matches, txt=%r' % text) # dbg
342 # Another option, seems to work great. Catches things like ''.<tab>
342 # Another option, seems to work great. Catches things like ''.<tab>
343 m = re.match(r"(\S+(\.\w+)*)\.(\w*)$", text)
343 m = re.match(r"(\S+(\.\w+)*)\.(\w*)$", text)
344
344
345 if m:
345 if m:
346 expr, attr = m.group(1, 3)
346 expr, attr = m.group(1, 3)
347 elif self.greedy:
347 elif self.greedy:
348 m2 = re.match(r"(.+)\.(\w*)$", self.line_buffer)
348 m2 = re.match(r"(.+)\.(\w*)$", self.line_buffer)
349 if not m2:
349 if not m2:
350 return []
350 return []
351 expr, attr = m2.group(1,2)
351 expr, attr = m2.group(1,2)
352 else:
352 else:
353 return []
353 return []
354
354
355 try:
355 try:
356 obj = eval(expr, self.namespace)
356 obj = eval(expr, self.namespace)
357 except:
357 except:
358 try:
358 try:
359 obj = eval(expr, self.global_namespace)
359 obj = eval(expr, self.global_namespace)
360 except:
360 except:
361 return []
361 return []
362
362
363 if self.limit_to__all__ and hasattr(obj, '__all__'):
363 if self.limit_to__all__ and hasattr(obj, '__all__'):
364 words = get__all__entries(obj)
364 words = get__all__entries(obj)
365 else:
365 else:
366 words = dir2(obj)
366 words = dir2(obj)
367
367
368 try:
368 try:
369 words = generics.complete_object(obj, words)
369 words = generics.complete_object(obj, words)
370 except TryNext:
370 except TryNext:
371 pass
371 pass
372 except Exception:
372 except Exception:
373 # Silence errors from completion function
373 # Silence errors from completion function
374 #raise # dbg
374 #raise # dbg
375 pass
375 pass
376 # Build match list to return
376 # Build match list to return
377 n = len(attr)
377 n = len(attr)
378 res = ["%s.%s" % (expr, w) for w in words if w[:n] == attr ]
378 res = ["%s.%s" % (expr, w) for w in words if w[:n] == attr ]
379 return res
379 return res
380
380
381
381
382 def get__all__entries(obj):
382 def get__all__entries(obj):
383 """returns the strings in the __all__ attribute"""
383 """returns the strings in the __all__ attribute"""
384 try:
384 try:
385 words = getattr(obj, '__all__')
385 words = getattr(obj, '__all__')
386 except:
386 except:
387 return []
387 return []
388
388
389 return [w for w in words if isinstance(w, basestring)]
389 return [w for w in words if isinstance(w, basestring)]
390
390
391
391
392 class IPCompleter(Completer):
392 class IPCompleter(Completer):
393 """Extension of the completer class with IPython-specific features"""
393 """Extension of the completer class with IPython-specific features"""
394
394
395 def _greedy_changed(self, name, old, new):
395 def _greedy_changed(self, name, old, new):
396 """update the splitter and readline delims when greedy is changed"""
396 """update the splitter and readline delims when greedy is changed"""
397 if new:
397 if new:
398 self.splitter.delims = GREEDY_DELIMS
398 self.splitter.delims = GREEDY_DELIMS
399 else:
399 else:
400 self.splitter.delims = DELIMS
400 self.splitter.delims = DELIMS
401
401
402 if self.readline:
402 if self.readline:
403 self.readline.set_completer_delims(self.splitter.delims)
403 self.readline.set_completer_delims(self.splitter.delims)
404
404
405 merge_completions = CBool(True, config=True,
405 merge_completions = CBool(True, config=True,
406 help="""Whether to merge completion results into a single list
406 help="""Whether to merge completion results into a single list
407
407
408 If False, only the completion results from the first non-empty
408 If False, only the completion results from the first non-empty
409 completer will be returned.
409 completer will be returned.
410 """
410 """
411 )
411 )
412 omit__names = Enum((0,1,2), default_value=2, config=True,
412 omit__names = Enum((0,1,2), default_value=2, config=True,
413 help="""Instruct the completer to omit private method names
413 help="""Instruct the completer to omit private method names
414
414
415 Specifically, when completing on ``object.<tab>``.
415 Specifically, when completing on ``object.<tab>``.
416
416
417 When 2 [default]: all names that start with '_' will be excluded.
417 When 2 [default]: all names that start with '_' will be excluded.
418
418
419 When 1: all 'magic' names (``__foo__``) will be excluded.
419 When 1: all 'magic' names (``__foo__``) will be excluded.
420
420
421 When 0: nothing will be excluded.
421 When 0: nothing will be excluded.
422 """
422 """
423 )
423 )
424 limit_to__all__ = CBool(default_value=False, config=True,
424 limit_to__all__ = CBool(default_value=False, config=True,
425 help="""Instruct the completer to use __all__ for the completion
425 help="""Instruct the completer to use __all__ for the completion
426
426
427 Specifically, when completing on ``object.<tab>``.
427 Specifically, when completing on ``object.<tab>``.
428
428
429 When True: only those names in obj.__all__ will be included.
429 When True: only those names in obj.__all__ will be included.
430
430
431 When False [default]: the __all__ attribute is ignored
431 When False [default]: the __all__ attribute is ignored
432 """
432 """
433 )
433 )
434
434
435 def __init__(self, shell=None, namespace=None, global_namespace=None,
435 def __init__(self, shell=None, namespace=None, global_namespace=None,
436 alias_table=None, use_readline=True,
436 alias_table=None, use_readline=True,
437 config=None, **kwargs):
437 config=None, **kwargs):
438 """IPCompleter() -> completer
438 """IPCompleter() -> completer
439
439
440 Return a completer object suitable for use by the readline library
440 Return a completer object suitable for use by the readline library
441 via readline.set_completer().
441 via readline.set_completer().
442
442
443 Inputs:
443 Inputs:
444
444
445 - shell: a pointer to the ipython shell itself. This is needed
445 - shell: a pointer to the ipython shell itself. This is needed
446 because this completer knows about magic functions, and those can
446 because this completer knows about magic functions, and those can
447 only be accessed via the ipython instance.
447 only be accessed via the ipython instance.
448
448
449 - namespace: an optional dict where completions are performed.
449 - namespace: an optional dict where completions are performed.
450
450
451 - global_namespace: secondary optional dict for completions, to
451 - global_namespace: secondary optional dict for completions, to
452 handle cases (such as IPython embedded inside functions) where
452 handle cases (such as IPython embedded inside functions) where
453 both Python scopes are visible.
453 both Python scopes are visible.
454
454
455 - If alias_table is supplied, it should be a dictionary of aliases
455 - If alias_table is supplied, it should be a dictionary of aliases
456 to complete.
456 to complete.
457
457
458 use_readline : bool, optional
458 use_readline : bool, optional
459 If true, use the readline library. This completer can still function
459 If true, use the readline library. This completer can still function
460 without readline, though in that case callers must provide some extra
460 without readline, though in that case callers must provide some extra
461 information on each call about the current line."""
461 information on each call about the current line."""
462
462
463 self.magic_escape = ESC_MAGIC
463 self.magic_escape = ESC_MAGIC
464 self.splitter = CompletionSplitter()
464 self.splitter = CompletionSplitter()
465
465
466 # Readline configuration, only used by the rlcompleter method.
466 # Readline configuration, only used by the rlcompleter method.
467 if use_readline:
467 if use_readline:
468 # We store the right version of readline so that later code
468 # We store the right version of readline so that later code
469 import IPython.utils.rlineimpl as readline
469 import IPython.utils.rlineimpl as readline
470 self.readline = readline
470 self.readline = readline
471 else:
471 else:
472 self.readline = None
472 self.readline = None
473
473
474 # _greedy_changed() depends on splitter and readline being defined:
474 # _greedy_changed() depends on splitter and readline being defined:
475 Completer.__init__(self, namespace=namespace, global_namespace=global_namespace,
475 Completer.__init__(self, namespace=namespace, global_namespace=global_namespace,
476 config=config, **kwargs)
476 config=config, **kwargs)
477
477
478 # List where completion matches will be stored
478 # List where completion matches will be stored
479 self.matches = []
479 self.matches = []
480 self.shell = shell
480 self.shell = shell
481 if alias_table is None:
481 if alias_table is None:
482 alias_table = {}
482 alias_table = {}
483 self.alias_table = alias_table
483 self.alias_table = alias_table
484 # Regexp to split filenames with spaces in them
484 # Regexp to split filenames with spaces in them
485 self.space_name_re = re.compile(r'([^\\] )')
485 self.space_name_re = re.compile(r'([^\\] )')
486 # Hold a local ref. to glob.glob for speed
486 # Hold a local ref. to glob.glob for speed
487 self.glob = glob.glob
487 self.glob = glob.glob
488
488
489 # Determine if we are running on 'dumb' terminals, like (X)Emacs
489 # Determine if we are running on 'dumb' terminals, like (X)Emacs
490 # buffers, to avoid completion problems.
490 # buffers, to avoid completion problems.
491 term = os.environ.get('TERM','xterm')
491 term = os.environ.get('TERM','xterm')
492 self.dumb_terminal = term in ['dumb','emacs']
492 self.dumb_terminal = term in ['dumb','emacs']
493
493
494 # Special handling of backslashes needed in win32 platforms
494 # Special handling of backslashes needed in win32 platforms
495 if sys.platform == "win32":
495 if sys.platform == "win32":
496 self.clean_glob = self._clean_glob_win32
496 self.clean_glob = self._clean_glob_win32
497 else:
497 else:
498 self.clean_glob = self._clean_glob
498 self.clean_glob = self._clean_glob
499
499
500 #regexp to parse docstring for function signature
500 #regexp to parse docstring for function signature
501 self.docstring_sig_re = re.compile(r'^[\w|\s.]+\(([^)]*)\).*')
501 self.docstring_sig_re = re.compile(r'^[\w|\s.]+\(([^)]*)\).*')
502 self.docstring_kwd_re = re.compile(r'[\s|\[]*(\w+)(?:\s*=\s*.*)')
502 self.docstring_kwd_re = re.compile(r'[\s|\[]*(\w+)(?:\s*=\s*.*)')
503 #use this if positional argument name is also needed
503 #use this if positional argument name is also needed
504 #= re.compile(r'[\s|\[]*(\w+)(?:\s*=?\s*.*)')
504 #= re.compile(r'[\s|\[]*(\w+)(?:\s*=?\s*.*)')
505
505
506 # All active matcher routines for completion
506 # All active matcher routines for completion
507 self.matchers = [self.python_matches,
507 self.matchers = [self.python_matches,
508 self.file_matches,
508 self.file_matches,
509 self.magic_matches,
509 self.magic_matches,
510 self.alias_matches,
510 self.alias_matches,
511 self.python_func_kw_matches,
511 self.python_func_kw_matches,
512 ]
512 ]
513
513
514 def all_completions(self, text):
514 def all_completions(self, text):
515 """
515 """
516 Wrapper around the complete method for the benefit of emacs
516 Wrapper around the complete method for the benefit of emacs
517 and pydb.
517 and pydb.
518 """
518 """
519 return self.complete(text)[1]
519 return self.complete(text)[1]
520
520
521 def _clean_glob(self,text):
521 def _clean_glob(self,text):
522 return self.glob("%s*" % text)
522 return self.glob("%s*" % text)
523
523
524 def _clean_glob_win32(self,text):
524 def _clean_glob_win32(self,text):
525 return [f.replace("\\","/")
525 return [f.replace("\\","/")
526 for f in self.glob("%s*" % text)]
526 for f in self.glob("%s*" % text)]
527
527
528 def file_matches(self, text):
528 def file_matches(self, text):
529 """Match filenames, expanding ~USER type strings.
529 """Match filenames, expanding ~USER type strings.
530
530
531 Most of the seemingly convoluted logic in this completer is an
531 Most of the seemingly convoluted logic in this completer is an
532 attempt to handle filenames with spaces in them. And yet it's not
532 attempt to handle filenames with spaces in them. And yet it's not
533 quite perfect, because Python's readline doesn't expose all of the
533 quite perfect, because Python's readline doesn't expose all of the
534 GNU readline details needed for this to be done correctly.
534 GNU readline details needed for this to be done correctly.
535
535
536 For a filename with a space in it, the printed completions will be
536 For a filename with a space in it, the printed completions will be
537 only the parts after what's already been typed (instead of the
537 only the parts after what's already been typed (instead of the
538 full completions, as is normally done). I don't think with the
538 full completions, as is normally done). I don't think with the
539 current (as of Python 2.3) Python readline it's possible to do
539 current (as of Python 2.3) Python readline it's possible to do
540 better."""
540 better."""
541
541
542 #io.rprint('Completer->file_matches: <%r>' % text) # dbg
542 #io.rprint('Completer->file_matches: <%r>' % text) # dbg
543
543
544 # chars that require escaping with backslash - i.e. chars
544 # chars that require escaping with backslash - i.e. chars
545 # that readline treats incorrectly as delimiters, but we
545 # that readline treats incorrectly as delimiters, but we
546 # don't want to treat as delimiters in filename matching
546 # don't want to treat as delimiters in filename matching
547 # when escaped with backslash
547 # when escaped with backslash
548 if text.startswith('!'):
548 if text.startswith('!'):
549 text = text[1:]
549 text = text[1:]
550 text_prefix = '!'
550 text_prefix = '!'
551 else:
551 else:
552 text_prefix = ''
552 text_prefix = ''
553
553
554 text_until_cursor = self.text_until_cursor
554 text_until_cursor = self.text_until_cursor
555 # track strings with open quotes
555 # track strings with open quotes
556 open_quotes = has_open_quotes(text_until_cursor)
556 open_quotes = has_open_quotes(text_until_cursor)
557
557
558 if '(' in text_until_cursor or '[' in text_until_cursor:
558 if '(' in text_until_cursor or '[' in text_until_cursor:
559 lsplit = text
559 lsplit = text
560 else:
560 else:
561 try:
561 try:
562 # arg_split ~ shlex.split, but with unicode bugs fixed by us
562 # arg_split ~ shlex.split, but with unicode bugs fixed by us
563 lsplit = arg_split(text_until_cursor)[-1]
563 lsplit = arg_split(text_until_cursor)[-1]
564 except ValueError:
564 except ValueError:
565 # typically an unmatched ", or backslash without escaped char.
565 # typically an unmatched ", or backslash without escaped char.
566 if open_quotes:
566 if open_quotes:
567 lsplit = text_until_cursor.split(open_quotes)[-1]
567 lsplit = text_until_cursor.split(open_quotes)[-1]
568 else:
568 else:
569 return []
569 return []
570 except IndexError:
570 except IndexError:
571 # tab pressed on empty line
571 # tab pressed on empty line
572 lsplit = ""
572 lsplit = ""
573
573
574 if not open_quotes and lsplit != protect_filename(lsplit):
574 if not open_quotes and lsplit != protect_filename(lsplit):
575 # if protectables are found, do matching on the whole escaped name
575 # if protectables are found, do matching on the whole escaped name
576 has_protectables = True
576 has_protectables = True
577 text0,text = text,lsplit
577 text0,text = text,lsplit
578 else:
578 else:
579 has_protectables = False
579 has_protectables = False
580 text = os.path.expanduser(text)
580 text = os.path.expanduser(text)
581
581
582 if text == "":
582 if text == "":
583 return [text_prefix + protect_filename(f) for f in self.glob("*")]
583 return [text_prefix + protect_filename(f) for f in self.glob("*")]
584
584
585 # Compute the matches from the filesystem
585 # Compute the matches from the filesystem
586 m0 = self.clean_glob(text.replace('\\',''))
586 m0 = self.clean_glob(text.replace('\\',''))
587
587
588 if has_protectables:
588 if has_protectables:
589 # If we had protectables, we need to revert our changes to the
589 # If we had protectables, we need to revert our changes to the
590 # beginning of filename so that we don't double-write the part
590 # beginning of filename so that we don't double-write the part
591 # of the filename we have so far
591 # of the filename we have so far
592 len_lsplit = len(lsplit)
592 len_lsplit = len(lsplit)
593 matches = [text_prefix + text0 +
593 matches = [text_prefix + text0 +
594 protect_filename(f[len_lsplit:]) for f in m0]
594 protect_filename(f[len_lsplit:]) for f in m0]
595 else:
595 else:
596 if open_quotes:
596 if open_quotes:
597 # if we have a string with an open quote, we don't need to
597 # if we have a string with an open quote, we don't need to
598 # protect the names at all (and we _shouldn't_, as it
598 # protect the names at all (and we _shouldn't_, as it
599 # would cause bugs when the filesystem call is made).
599 # would cause bugs when the filesystem call is made).
600 matches = m0
600 matches = m0
601 else:
601 else:
602 matches = [text_prefix +
602 matches = [text_prefix +
603 protect_filename(f) for f in m0]
603 protect_filename(f) for f in m0]
604
604
605 #io.rprint('mm', matches) # dbg
605 #io.rprint('mm', matches) # dbg
606
606
607 # Mark directories in input list by appending '/' to their names.
607 # Mark directories in input list by appending '/' to their names.
608 matches = [x+'/' if os.path.isdir(x) else x for x in matches]
608 matches = [x+'/' if os.path.isdir(x) else x for x in matches]
609 return matches
609 return matches
610
610
611 def magic_matches(self, text):
611 def magic_matches(self, text):
612 """Match magics"""
612 """Match magics"""
613 #print 'Completer->magic_matches:',text,'lb',self.text_until_cursor # dbg
613 #print 'Completer->magic_matches:',text,'lb',self.text_until_cursor # dbg
614 # Get all shell magics now rather than statically, so magics loaded at
614 # Get all shell magics now rather than statically, so magics loaded at
615 # runtime show up too.
615 # runtime show up too.
616 lsm = self.shell.magics_manager.lsmagic()
616 lsm = self.shell.magics_manager.lsmagic()
617 line_magics = lsm['line']
617 line_magics = lsm['line']
618 cell_magics = lsm['cell']
618 cell_magics = lsm['cell']
619 pre = self.magic_escape
619 pre = self.magic_escape
620 pre2 = pre+pre
620 pre2 = pre+pre
621
621
622 # Completion logic:
622 # Completion logic:
623 # - user gives %%: only do cell magics
623 # - user gives %%: only do cell magics
624 # - user gives %: do both line and cell magics
624 # - user gives %: do both line and cell magics
625 # - no prefix: do both
625 # - no prefix: do both
626 # In other words, line magics are skipped if the user gives %% explicitly
626 # In other words, line magics are skipped if the user gives %% explicitly
627 bare_text = text.lstrip(pre)
627 bare_text = text.lstrip(pre)
628 comp = [ pre2+m for m in cell_magics if m.startswith(bare_text)]
628 comp = [ pre2+m for m in cell_magics if m.startswith(bare_text)]
629 if not text.startswith(pre2):
629 if not text.startswith(pre2):
630 comp += [ pre+m for m in line_magics if m.startswith(bare_text)]
630 comp += [ pre+m for m in line_magics if m.startswith(bare_text)]
631 return comp
631 return comp
632
632
633 def alias_matches(self, text):
633 def alias_matches(self, text):
634 """Match internal system aliases"""
634 """Match internal system aliases"""
635 #print 'Completer->alias_matches:',text,'lb',self.text_until_cursor # dbg
635 #print 'Completer->alias_matches:',text,'lb',self.text_until_cursor # dbg
636
636
637 # if we are not in the first 'item', alias matching
637 # if we are not in the first 'item', alias matching
638 # doesn't make sense - unless we are starting with 'sudo' command.
638 # doesn't make sense - unless we are starting with 'sudo' command.
639 main_text = self.text_until_cursor.lstrip()
639 main_text = self.text_until_cursor.lstrip()
640 if ' ' in main_text and not main_text.startswith('sudo'):
640 if ' ' in main_text and not main_text.startswith('sudo'):
641 return []
641 return []
642 text = os.path.expanduser(text)
642 text = os.path.expanduser(text)
643 aliases = self.alias_table.keys()
643 aliases = self.alias_table.keys()
644 if text == '':
644 if text == '':
645 return aliases
645 return aliases
646 else:
646 else:
647 return [a for a in aliases if a.startswith(text)]
647 return [a for a in aliases if a.startswith(text)]
648
648
649 def python_matches(self,text):
649 def python_matches(self,text):
650 """Match attributes or global python names"""
650 """Match attributes or global python names"""
651
651
652 #io.rprint('Completer->python_matches, txt=%r' % text) # dbg
652 #io.rprint('Completer->python_matches, txt=%r' % text) # dbg
653 if "." in text:
653 if "." in text:
654 try:
654 try:
655 matches = self.attr_matches(text)
655 matches = self.attr_matches(text)
656 if text.endswith('.') and self.omit__names:
656 if text.endswith('.') and self.omit__names:
657 if self.omit__names == 1:
657 if self.omit__names == 1:
658 # true if txt is _not_ a __ name, false otherwise:
658 # true if txt is _not_ a __ name, false otherwise:
659 no__name = (lambda txt:
659 no__name = (lambda txt:
660 re.match(r'.*\.__.*?__',txt) is None)
660 re.match(r'.*\.__.*?__',txt) is None)
661 else:
661 else:
662 # true if txt is _not_ a _ name, false otherwise:
662 # true if txt is _not_ a _ name, false otherwise:
663 no__name = (lambda txt:
663 no__name = (lambda txt:
664 re.match(r'.*\._.*?',txt) is None)
664 re.match(r'.*\._.*?',txt) is None)
665 matches = filter(no__name, matches)
665 matches = filter(no__name, matches)
666 except NameError:
666 except NameError:
667 # catches <undefined attributes>.<tab>
667 # catches <undefined attributes>.<tab>
668 matches = []
668 matches = []
669 else:
669 else:
670 matches = self.global_matches(text)
670 matches = self.global_matches(text)
671
671
672 return matches
672 return matches
673
673
674 def _default_arguments_from_docstring(self,doc):
674 def _default_arguments_from_docstring(self, doc):
675 """Parse first line of docstring of the
675 """Parse first line of docstring for call signature
676 form 'min(iterable[, key=func])\n' to find
676
677 keyword argument names.
677 Docstring should be of the form 'min(iterable[, key=func])\n'.
678 I can also parse cython docstring of the form
679 'Minuit.migrad(self, int ncall=10000, resume=True, int nsplit=1)'
678 """
680 """
679 if doc is None:
681 if doc is None:
680 return []
682 return []
681 sio = StringIO.StringIO(doc.lstrip())
683 sio = StringIO.StringIO(doc.lstrip())
682 #care only the firstline
684 #care only the firstline
683 #docstring can be long
685 #docstring can be long
684 line = sio.readline()
686 line = sio.readline()
685 #p = re.compile(r'^[\w|\s.]+\(([^)]*)\).*')
687 #p = re.compile(r'^[\w|\s.]+\(([^)]*)\).*')
686 #'min(iterable[, key=func])\n' -> 'iterable[, key=func]'
688 #'min(iterable[, key=func])\n' -> 'iterable[, key=func]'
687 sig = self.docstring_sig_re.search(line)
689 sig = self.docstring_sig_re.search(line)
688 if sig is None:
690 if sig is None:
689 return []
691 return []
690 # iterable[, key=func]' -> ['iterable[' ,' key=func]']
692 # iterable[, key=func]' -> ['iterable[' ,' key=func]']
691 sig = sig.groups()[0].split(',')
693 sig = sig.groups()[0].split(',')
692 ret = []
694 ret = []
693 for s in sig:
695 for s in sig:
694 #re.compile(r'[\s|\[]*(\w+)(?:\s*=\s*.*)')
696 #re.compile(r'[\s|\[]*(\w+)(?:\s*=\s*.*)')
695 ret += self.docstring_kwd_re.findall(s)
697 ret += self.docstring_kwd_re.findall(s)
696 return ret
698 return ret
697
699
698 def _default_arguments(self, obj):
700 def _default_arguments(self, obj):
699 """Return the list of default arguments of obj if it is callable,
701 """Return the list of default arguments of obj if it is callable,
700 or empty list otherwise."""
702 or empty list otherwise."""
701 call_obj = obj
703 call_obj = obj
702 ret = []
704 ret = []
703 if inspect.isbuiltin(obj):
705 if inspect.isbuiltin(obj):
704 pass
706 pass
705 elif not (inspect.isfunction(obj) or inspect.ismethod(obj)):
707 elif not (inspect.isfunction(obj) or inspect.ismethod(obj)):
706 if inspect.isclass(obj):
708 if inspect.isclass(obj):
707 #for cython embededsignature=True the constructor docstring
709 #for cython embededsignature=True the constructor docstring
708 #belongs to the object itself not __init__
710 #belongs to the object itself not __init__
709 ret += self._default_arguments_from_docstring(
711 ret += self._default_arguments_from_docstring(
710 getattr(obj, '__doc__', ''))
712 getattr(obj, '__doc__', ''))
711 # for classes, check for __init__,__new__
713 # for classes, check for __init__,__new__
712 call_obj = (getattr(obj, '__init__', None) or
714 call_obj = (getattr(obj, '__init__', None) or
713 getattr(obj, '__new__', None))
715 getattr(obj, '__new__', None))
714 # for all others, check if they are __call__able
716 # for all others, check if they are __call__able
715 elif hasattr(obj, '__call__'):
717 elif hasattr(obj, '__call__'):
716 call_obj = obj.__call__
718 call_obj = obj.__call__
717
719
718 ret += self._default_arguments_from_docstring(
720 ret += self._default_arguments_from_docstring(
719 getattr(call_obj, '__doc__', ''))
721 getattr(call_obj, '__doc__', ''))
720
722
721 try:
723 try:
722 args,_,_1,defaults = inspect.getargspec(call_obj)
724 args,_,_1,defaults = inspect.getargspec(call_obj)
723 if defaults:
725 if defaults:
724 ret+=args[-len(defaults):]
726 ret+=args[-len(defaults):]
725 except TypeError:
727 except TypeError:
726 pass
728 pass
727
729
728 return list(set(ret))
730 return list(set(ret))
729
731
730 def python_func_kw_matches(self,text):
732 def python_func_kw_matches(self,text):
731 """Match named parameters (kwargs) of the last open function"""
733 """Match named parameters (kwargs) of the last open function"""
732
734
733 if "." in text: # a parameter cannot be dotted
735 if "." in text: # a parameter cannot be dotted
734 return []
736 return []
735 try: regexp = self.__funcParamsRegex
737 try: regexp = self.__funcParamsRegex
736 except AttributeError:
738 except AttributeError:
737 regexp = self.__funcParamsRegex = re.compile(r'''
739 regexp = self.__funcParamsRegex = re.compile(r'''
738 '.*?(?<!\\)' | # single quoted strings or
740 '.*?(?<!\\)' | # single quoted strings or
739 ".*?(?<!\\)" | # double quoted strings or
741 ".*?(?<!\\)" | # double quoted strings or
740 \w+ | # identifier
742 \w+ | # identifier
741 \S # other characters
743 \S # other characters
742 ''', re.VERBOSE | re.DOTALL)
744 ''', re.VERBOSE | re.DOTALL)
743 # 1. find the nearest identifier that comes before an unclosed
745 # 1. find the nearest identifier that comes before an unclosed
744 # parenthesis before the cursor
746 # parenthesis before the cursor
745 # e.g. for "foo (1+bar(x), pa<cursor>,a=1)", the candidate is "foo"
747 # e.g. for "foo (1+bar(x), pa<cursor>,a=1)", the candidate is "foo"
746 tokens = regexp.findall(self.text_until_cursor)
748 tokens = regexp.findall(self.text_until_cursor)
747 tokens.reverse()
749 tokens.reverse()
748 iterTokens = iter(tokens); openPar = 0
750 iterTokens = iter(tokens); openPar = 0
749
751
750 for token in iterTokens:
752 for token in iterTokens:
751 if token == ')':
753 if token == ')':
752 openPar -= 1
754 openPar -= 1
753 elif token == '(':
755 elif token == '(':
754 openPar += 1
756 openPar += 1
755 if openPar > 0:
757 if openPar > 0:
756 # found the last unclosed parenthesis
758 # found the last unclosed parenthesis
757 break
759 break
758 else:
760 else:
759 return []
761 return []
760 # 2. Concatenate dotted names ("foo.bar" for "foo.bar(x, pa" )
762 # 2. Concatenate dotted names ("foo.bar" for "foo.bar(x, pa" )
761 ids = []
763 ids = []
762 isId = re.compile(r'\w+$').match
764 isId = re.compile(r'\w+$').match
763
765
764 while True:
766 while True:
765 try:
767 try:
766 ids.append(next(iterTokens))
768 ids.append(next(iterTokens))
767 if not isId(ids[-1]):
769 if not isId(ids[-1]):
768 ids.pop(); break
770 ids.pop(); break
769 if not next(iterTokens) == '.':
771 if not next(iterTokens) == '.':
770 break
772 break
771 except StopIteration:
773 except StopIteration:
772 break
774 break
773 # lookup the candidate callable matches either using global_matches
775 # lookup the candidate callable matches either using global_matches
774 # or attr_matches for dotted names
776 # or attr_matches for dotted names
775 if len(ids) == 1:
777 if len(ids) == 1:
776 callableMatches = self.global_matches(ids[0])
778 callableMatches = self.global_matches(ids[0])
777 else:
779 else:
778 callableMatches = self.attr_matches('.'.join(ids[::-1]))
780 callableMatches = self.attr_matches('.'.join(ids[::-1]))
779 argMatches = []
781 argMatches = []
780 for callableMatch in callableMatches:
782 for callableMatch in callableMatches:
781 try:
783 try:
782 namedArgs = self._default_arguments(eval(callableMatch,
784 namedArgs = self._default_arguments(eval(callableMatch,
783 self.namespace))
785 self.namespace))
784 except:
786 except:
785 continue
787 continue
786
788
787 for namedArg in namedArgs:
789 for namedArg in namedArgs:
788 if namedArg.startswith(text):
790 if namedArg.startswith(text):
789 argMatches.append("%s=" %namedArg)
791 argMatches.append("%s=" %namedArg)
790 return argMatches
792 return argMatches
791
793
792 def dispatch_custom_completer(self, text):
794 def dispatch_custom_completer(self, text):
793 #io.rprint("Custom! '%s' %s" % (text, self.custom_completers)) # dbg
795 #io.rprint("Custom! '%s' %s" % (text, self.custom_completers)) # dbg
794 line = self.line_buffer
796 line = self.line_buffer
795 if not line.strip():
797 if not line.strip():
796 return None
798 return None
797
799
798 # Create a little structure to pass all the relevant information about
800 # Create a little structure to pass all the relevant information about
799 # the current completion to any custom completer.
801 # the current completion to any custom completer.
800 event = Bunch()
802 event = Bunch()
801 event.line = line
803 event.line = line
802 event.symbol = text
804 event.symbol = text
803 cmd = line.split(None,1)[0]
805 cmd = line.split(None,1)[0]
804 event.command = cmd
806 event.command = cmd
805 event.text_until_cursor = self.text_until_cursor
807 event.text_until_cursor = self.text_until_cursor
806
808
807 #print "\ncustom:{%s]\n" % event # dbg
809 #print "\ncustom:{%s]\n" % event # dbg
808
810
809 # for foo etc, try also to find completer for %foo
811 # for foo etc, try also to find completer for %foo
810 if not cmd.startswith(self.magic_escape):
812 if not cmd.startswith(self.magic_escape):
811 try_magic = self.custom_completers.s_matches(
813 try_magic = self.custom_completers.s_matches(
812 self.magic_escape + cmd)
814 self.magic_escape + cmd)
813 else:
815 else:
814 try_magic = []
816 try_magic = []
815
817
816 for c in itertools.chain(self.custom_completers.s_matches(cmd),
818 for c in itertools.chain(self.custom_completers.s_matches(cmd),
817 try_magic,
819 try_magic,
818 self.custom_completers.flat_matches(self.text_until_cursor)):
820 self.custom_completers.flat_matches(self.text_until_cursor)):
819 #print "try",c # dbg
821 #print "try",c # dbg
820 try:
822 try:
821 res = c(event)
823 res = c(event)
822 if res:
824 if res:
823 # first, try case sensitive match
825 # first, try case sensitive match
824 withcase = [r for r in res if r.startswith(text)]
826 withcase = [r for r in res if r.startswith(text)]
825 if withcase:
827 if withcase:
826 return withcase
828 return withcase
827 # if none, then case insensitive ones are ok too
829 # if none, then case insensitive ones are ok too
828 text_low = text.lower()
830 text_low = text.lower()
829 return [r for r in res if r.lower().startswith(text_low)]
831 return [r for r in res if r.lower().startswith(text_low)]
830 except TryNext:
832 except TryNext:
831 pass
833 pass
832
834
833 return None
835 return None
834
836
835 def complete(self, text=None, line_buffer=None, cursor_pos=None):
837 def complete(self, text=None, line_buffer=None, cursor_pos=None):
836 """Find completions for the given text and line context.
838 """Find completions for the given text and line context.
837
839
838 This is called successively with state == 0, 1, 2, ... until it
840 This is called successively with state == 0, 1, 2, ... until it
839 returns None. The completion should begin with 'text'.
841 returns None. The completion should begin with 'text'.
840
842
841 Note that both the text and the line_buffer are optional, but at least
843 Note that both the text and the line_buffer are optional, but at least
842 one of them must be given.
844 one of them must be given.
843
845
844 Parameters
846 Parameters
845 ----------
847 ----------
846 text : string, optional
848 text : string, optional
847 Text to perform the completion on. If not given, the line buffer
849 Text to perform the completion on. If not given, the line buffer
848 is split using the instance's CompletionSplitter object.
850 is split using the instance's CompletionSplitter object.
849
851
850 line_buffer : string, optional
852 line_buffer : string, optional
851 If not given, the completer attempts to obtain the current line
853 If not given, the completer attempts to obtain the current line
852 buffer via readline. This keyword allows clients which are
854 buffer via readline. This keyword allows clients which are
853 requesting for text completions in non-readline contexts to inform
855 requesting for text completions in non-readline contexts to inform
854 the completer of the entire text.
856 the completer of the entire text.
855
857
856 cursor_pos : int, optional
858 cursor_pos : int, optional
857 Index of the cursor in the full line buffer. Should be provided by
859 Index of the cursor in the full line buffer. Should be provided by
858 remote frontends where kernel has no access to frontend state.
860 remote frontends where kernel has no access to frontend state.
859
861
860 Returns
862 Returns
861 -------
863 -------
862 text : str
864 text : str
863 Text that was actually used in the completion.
865 Text that was actually used in the completion.
864
866
865 matches : list
867 matches : list
866 A list of completion matches.
868 A list of completion matches.
867 """
869 """
868 #io.rprint('\nCOMP1 %r %r %r' % (text, line_buffer, cursor_pos)) # dbg
870 #io.rprint('\nCOMP1 %r %r %r' % (text, line_buffer, cursor_pos)) # dbg
869
871
870 # if the cursor position isn't given, the only sane assumption we can
872 # if the cursor position isn't given, the only sane assumption we can
871 # make is that it's at the end of the line (the common case)
873 # make is that it's at the end of the line (the common case)
872 if cursor_pos is None:
874 if cursor_pos is None:
873 cursor_pos = len(line_buffer) if text is None else len(text)
875 cursor_pos = len(line_buffer) if text is None else len(text)
874
876
875 # if text is either None or an empty string, rely on the line buffer
877 # if text is either None or an empty string, rely on the line buffer
876 if not text:
878 if not text:
877 text = self.splitter.split_line(line_buffer, cursor_pos)
879 text = self.splitter.split_line(line_buffer, cursor_pos)
878
880
879 # If no line buffer is given, assume the input text is all there was
881 # If no line buffer is given, assume the input text is all there was
880 if line_buffer is None:
882 if line_buffer is None:
881 line_buffer = text
883 line_buffer = text
882
884
883 self.line_buffer = line_buffer
885 self.line_buffer = line_buffer
884 self.text_until_cursor = self.line_buffer[:cursor_pos]
886 self.text_until_cursor = self.line_buffer[:cursor_pos]
885 #io.rprint('COMP2 %r %r %r' % (text, line_buffer, cursor_pos)) # dbg
887 #io.rprint('COMP2 %r %r %r' % (text, line_buffer, cursor_pos)) # dbg
886
888
887 # Start with a clean slate of completions
889 # Start with a clean slate of completions
888 self.matches[:] = []
890 self.matches[:] = []
889 custom_res = self.dispatch_custom_completer(text)
891 custom_res = self.dispatch_custom_completer(text)
890 if custom_res is not None:
892 if custom_res is not None:
891 # did custom completers produce something?
893 # did custom completers produce something?
892 self.matches = custom_res
894 self.matches = custom_res
893 else:
895 else:
894 # Extend the list of completions with the results of each
896 # Extend the list of completions with the results of each
895 # matcher, so we return results to the user from all
897 # matcher, so we return results to the user from all
896 # namespaces.
898 # namespaces.
897 if self.merge_completions:
899 if self.merge_completions:
898 self.matches = []
900 self.matches = []
899 for matcher in self.matchers:
901 for matcher in self.matchers:
900 try:
902 try:
901 self.matches.extend(matcher(text))
903 self.matches.extend(matcher(text))
902 except:
904 except:
903 # Show the ugly traceback if the matcher causes an
905 # Show the ugly traceback if the matcher causes an
904 # exception, but do NOT crash the kernel!
906 # exception, but do NOT crash the kernel!
905 sys.excepthook(*sys.exc_info())
907 sys.excepthook(*sys.exc_info())
906 else:
908 else:
907 for matcher in self.matchers:
909 for matcher in self.matchers:
908 self.matches = matcher(text)
910 self.matches = matcher(text)
909 if self.matches:
911 if self.matches:
910 break
912 break
911 # FIXME: we should extend our api to return a dict with completions for
913 # FIXME: we should extend our api to return a dict with completions for
912 # different types of objects. The rlcomplete() method could then
914 # different types of objects. The rlcomplete() method could then
913 # simply collapse the dict into a list for readline, but we'd have
915 # simply collapse the dict into a list for readline, but we'd have
914 # richer completion semantics in other evironments.
916 # richer completion semantics in other evironments.
915 self.matches = sorted(set(self.matches))
917 self.matches = sorted(set(self.matches))
916 #io.rprint('COMP TEXT, MATCHES: %r, %r' % (text, self.matches)) # dbg
918 #io.rprint('COMP TEXT, MATCHES: %r, %r' % (text, self.matches)) # dbg
917 return text, self.matches
919 return text, self.matches
918
920
919 def rlcomplete(self, text, state):
921 def rlcomplete(self, text, state):
920 """Return the state-th possible completion for 'text'.
922 """Return the state-th possible completion for 'text'.
921
923
922 This is called successively with state == 0, 1, 2, ... until it
924 This is called successively with state == 0, 1, 2, ... until it
923 returns None. The completion should begin with 'text'.
925 returns None. The completion should begin with 'text'.
924
926
925 Parameters
927 Parameters
926 ----------
928 ----------
927 text : string
929 text : string
928 Text to perform the completion on.
930 Text to perform the completion on.
929
931
930 state : int
932 state : int
931 Counter used by readline.
933 Counter used by readline.
932 """
934 """
933 if state==0:
935 if state==0:
934
936
935 self.line_buffer = line_buffer = self.readline.get_line_buffer()
937 self.line_buffer = line_buffer = self.readline.get_line_buffer()
936 cursor_pos = self.readline.get_endidx()
938 cursor_pos = self.readline.get_endidx()
937
939
938 #io.rprint("\nRLCOMPLETE: %r %r %r" %
940 #io.rprint("\nRLCOMPLETE: %r %r %r" %
939 # (text, line_buffer, cursor_pos) ) # dbg
941 # (text, line_buffer, cursor_pos) ) # dbg
940
942
941 # if there is only a tab on a line with only whitespace, instead of
943 # if there is only a tab on a line with only whitespace, instead of
942 # the mostly useless 'do you want to see all million completions'
944 # the mostly useless 'do you want to see all million completions'
943 # message, just do the right thing and give the user his tab!
945 # message, just do the right thing and give the user his tab!
944 # Incidentally, this enables pasting of tabbed text from an editor
946 # Incidentally, this enables pasting of tabbed text from an editor
945 # (as long as autoindent is off).
947 # (as long as autoindent is off).
946
948
947 # It should be noted that at least pyreadline still shows file
949 # It should be noted that at least pyreadline still shows file
948 # completions - is there a way around it?
950 # completions - is there a way around it?
949
951
950 # don't apply this on 'dumb' terminals, such as emacs buffers, so
952 # don't apply this on 'dumb' terminals, such as emacs buffers, so
951 # we don't interfere with their own tab-completion mechanism.
953 # we don't interfere with their own tab-completion mechanism.
952 if not (self.dumb_terminal or line_buffer.strip()):
954 if not (self.dumb_terminal or line_buffer.strip()):
953 self.readline.insert_text('\t')
955 self.readline.insert_text('\t')
954 sys.stdout.flush()
956 sys.stdout.flush()
955 return None
957 return None
956
958
957 # Note: debugging exceptions that may occur in completion is very
959 # Note: debugging exceptions that may occur in completion is very
958 # tricky, because readline unconditionally silences them. So if
960 # tricky, because readline unconditionally silences them. So if
959 # during development you suspect a bug in the completion code, turn
961 # during development you suspect a bug in the completion code, turn
960 # this flag on temporarily by uncommenting the second form (don't
962 # this flag on temporarily by uncommenting the second form (don't
961 # flip the value in the first line, as the '# dbg' marker can be
963 # flip the value in the first line, as the '# dbg' marker can be
962 # automatically detected and is used elsewhere).
964 # automatically detected and is used elsewhere).
963 DEBUG = False
965 DEBUG = False
964 #DEBUG = True # dbg
966 #DEBUG = True # dbg
965 if DEBUG:
967 if DEBUG:
966 try:
968 try:
967 self.complete(text, line_buffer, cursor_pos)
969 self.complete(text, line_buffer, cursor_pos)
968 except:
970 except:
969 import traceback; traceback.print_exc()
971 import traceback; traceback.print_exc()
970 else:
972 else:
971 # The normal production version is here
973 # The normal production version is here
972
974
973 # This method computes the self.matches array
975 # This method computes the self.matches array
974 self.complete(text, line_buffer, cursor_pos)
976 self.complete(text, line_buffer, cursor_pos)
975
977
976 try:
978 try:
977 return self.matches[state]
979 return self.matches[state]
978 except IndexError:
980 except IndexError:
979 return None
981 return None
General Comments 0
You need to be logged in to leave comments. Login now