##// END OF EJS Templates
__call__ should not use class docstring
Piti Ongmongkolkul -
Show More
@@ -1,974 +1,974 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 # All active matcher routines for completion
500 # All active matcher routines for completion
501 self.matchers = [self.python_matches,
501 self.matchers = [self.python_matches,
502 self.file_matches,
502 self.file_matches,
503 self.magic_matches,
503 self.magic_matches,
504 self.alias_matches,
504 self.alias_matches,
505 self.python_func_kw_matches,
505 self.python_func_kw_matches,
506 ]
506 ]
507
507
508 def all_completions(self, text):
508 def all_completions(self, text):
509 """
509 """
510 Wrapper around the complete method for the benefit of emacs
510 Wrapper around the complete method for the benefit of emacs
511 and pydb.
511 and pydb.
512 """
512 """
513 return self.complete(text)[1]
513 return self.complete(text)[1]
514
514
515 def _clean_glob(self,text):
515 def _clean_glob(self,text):
516 return self.glob("%s*" % text)
516 return self.glob("%s*" % text)
517
517
518 def _clean_glob_win32(self,text):
518 def _clean_glob_win32(self,text):
519 return [f.replace("\\","/")
519 return [f.replace("\\","/")
520 for f in self.glob("%s*" % text)]
520 for f in self.glob("%s*" % text)]
521
521
522 def file_matches(self, text):
522 def file_matches(self, text):
523 """Match filenames, expanding ~USER type strings.
523 """Match filenames, expanding ~USER type strings.
524
524
525 Most of the seemingly convoluted logic in this completer is an
525 Most of the seemingly convoluted logic in this completer is an
526 attempt to handle filenames with spaces in them. And yet it's not
526 attempt to handle filenames with spaces in them. And yet it's not
527 quite perfect, because Python's readline doesn't expose all of the
527 quite perfect, because Python's readline doesn't expose all of the
528 GNU readline details needed for this to be done correctly.
528 GNU readline details needed for this to be done correctly.
529
529
530 For a filename with a space in it, the printed completions will be
530 For a filename with a space in it, the printed completions will be
531 only the parts after what's already been typed (instead of the
531 only the parts after what's already been typed (instead of the
532 full completions, as is normally done). I don't think with the
532 full completions, as is normally done). I don't think with the
533 current (as of Python 2.3) Python readline it's possible to do
533 current (as of Python 2.3) Python readline it's possible to do
534 better."""
534 better."""
535
535
536 #io.rprint('Completer->file_matches: <%r>' % text) # dbg
536 #io.rprint('Completer->file_matches: <%r>' % text) # dbg
537
537
538 # chars that require escaping with backslash - i.e. chars
538 # chars that require escaping with backslash - i.e. chars
539 # that readline treats incorrectly as delimiters, but we
539 # that readline treats incorrectly as delimiters, but we
540 # don't want to treat as delimiters in filename matching
540 # don't want to treat as delimiters in filename matching
541 # when escaped with backslash
541 # when escaped with backslash
542 if text.startswith('!'):
542 if text.startswith('!'):
543 text = text[1:]
543 text = text[1:]
544 text_prefix = '!'
544 text_prefix = '!'
545 else:
545 else:
546 text_prefix = ''
546 text_prefix = ''
547
547
548 text_until_cursor = self.text_until_cursor
548 text_until_cursor = self.text_until_cursor
549 # track strings with open quotes
549 # track strings with open quotes
550 open_quotes = has_open_quotes(text_until_cursor)
550 open_quotes = has_open_quotes(text_until_cursor)
551
551
552 if '(' in text_until_cursor or '[' in text_until_cursor:
552 if '(' in text_until_cursor or '[' in text_until_cursor:
553 lsplit = text
553 lsplit = text
554 else:
554 else:
555 try:
555 try:
556 # arg_split ~ shlex.split, but with unicode bugs fixed by us
556 # arg_split ~ shlex.split, but with unicode bugs fixed by us
557 lsplit = arg_split(text_until_cursor)[-1]
557 lsplit = arg_split(text_until_cursor)[-1]
558 except ValueError:
558 except ValueError:
559 # typically an unmatched ", or backslash without escaped char.
559 # typically an unmatched ", or backslash without escaped char.
560 if open_quotes:
560 if open_quotes:
561 lsplit = text_until_cursor.split(open_quotes)[-1]
561 lsplit = text_until_cursor.split(open_quotes)[-1]
562 else:
562 else:
563 return []
563 return []
564 except IndexError:
564 except IndexError:
565 # tab pressed on empty line
565 # tab pressed on empty line
566 lsplit = ""
566 lsplit = ""
567
567
568 if not open_quotes and lsplit != protect_filename(lsplit):
568 if not open_quotes and lsplit != protect_filename(lsplit):
569 # if protectables are found, do matching on the whole escaped name
569 # if protectables are found, do matching on the whole escaped name
570 has_protectables = True
570 has_protectables = True
571 text0,text = text,lsplit
571 text0,text = text,lsplit
572 else:
572 else:
573 has_protectables = False
573 has_protectables = False
574 text = os.path.expanduser(text)
574 text = os.path.expanduser(text)
575
575
576 if text == "":
576 if text == "":
577 return [text_prefix + protect_filename(f) for f in self.glob("*")]
577 return [text_prefix + protect_filename(f) for f in self.glob("*")]
578
578
579 # Compute the matches from the filesystem
579 # Compute the matches from the filesystem
580 m0 = self.clean_glob(text.replace('\\',''))
580 m0 = self.clean_glob(text.replace('\\',''))
581
581
582 if has_protectables:
582 if has_protectables:
583 # If we had protectables, we need to revert our changes to the
583 # If we had protectables, we need to revert our changes to the
584 # beginning of filename so that we don't double-write the part
584 # beginning of filename so that we don't double-write the part
585 # of the filename we have so far
585 # of the filename we have so far
586 len_lsplit = len(lsplit)
586 len_lsplit = len(lsplit)
587 matches = [text_prefix + text0 +
587 matches = [text_prefix + text0 +
588 protect_filename(f[len_lsplit:]) for f in m0]
588 protect_filename(f[len_lsplit:]) for f in m0]
589 else:
589 else:
590 if open_quotes:
590 if open_quotes:
591 # if we have a string with an open quote, we don't need to
591 # if we have a string with an open quote, we don't need to
592 # protect the names at all (and we _shouldn't_, as it
592 # protect the names at all (and we _shouldn't_, as it
593 # would cause bugs when the filesystem call is made).
593 # would cause bugs when the filesystem call is made).
594 matches = m0
594 matches = m0
595 else:
595 else:
596 matches = [text_prefix +
596 matches = [text_prefix +
597 protect_filename(f) for f in m0]
597 protect_filename(f) for f in m0]
598
598
599 #io.rprint('mm', matches) # dbg
599 #io.rprint('mm', matches) # dbg
600
600
601 # Mark directories in input list by appending '/' to their names.
601 # Mark directories in input list by appending '/' to their names.
602 matches = [x+'/' if os.path.isdir(x) else x for x in matches]
602 matches = [x+'/' if os.path.isdir(x) else x for x in matches]
603 return matches
603 return matches
604
604
605 def magic_matches(self, text):
605 def magic_matches(self, text):
606 """Match magics"""
606 """Match magics"""
607 #print 'Completer->magic_matches:',text,'lb',self.text_until_cursor # dbg
607 #print 'Completer->magic_matches:',text,'lb',self.text_until_cursor # dbg
608 # Get all shell magics now rather than statically, so magics loaded at
608 # Get all shell magics now rather than statically, so magics loaded at
609 # runtime show up too.
609 # runtime show up too.
610 lsm = self.shell.magics_manager.lsmagic()
610 lsm = self.shell.magics_manager.lsmagic()
611 line_magics = lsm['line']
611 line_magics = lsm['line']
612 cell_magics = lsm['cell']
612 cell_magics = lsm['cell']
613 pre = self.magic_escape
613 pre = self.magic_escape
614 pre2 = pre+pre
614 pre2 = pre+pre
615
615
616 # Completion logic:
616 # Completion logic:
617 # - user gives %%: only do cell magics
617 # - user gives %%: only do cell magics
618 # - user gives %: do both line and cell magics
618 # - user gives %: do both line and cell magics
619 # - no prefix: do both
619 # - no prefix: do both
620 # In other words, line magics are skipped if the user gives %% explicitly
620 # In other words, line magics are skipped if the user gives %% explicitly
621 bare_text = text.lstrip(pre)
621 bare_text = text.lstrip(pre)
622 comp = [ pre2+m for m in cell_magics if m.startswith(bare_text)]
622 comp = [ pre2+m for m in cell_magics if m.startswith(bare_text)]
623 if not text.startswith(pre2):
623 if not text.startswith(pre2):
624 comp += [ pre+m for m in line_magics if m.startswith(bare_text)]
624 comp += [ pre+m for m in line_magics if m.startswith(bare_text)]
625 return comp
625 return comp
626
626
627 def alias_matches(self, text):
627 def alias_matches(self, text):
628 """Match internal system aliases"""
628 """Match internal system aliases"""
629 #print 'Completer->alias_matches:',text,'lb',self.text_until_cursor # dbg
629 #print 'Completer->alias_matches:',text,'lb',self.text_until_cursor # dbg
630
630
631 # if we are not in the first 'item', alias matching
631 # if we are not in the first 'item', alias matching
632 # doesn't make sense - unless we are starting with 'sudo' command.
632 # doesn't make sense - unless we are starting with 'sudo' command.
633 main_text = self.text_until_cursor.lstrip()
633 main_text = self.text_until_cursor.lstrip()
634 if ' ' in main_text and not main_text.startswith('sudo'):
634 if ' ' in main_text and not main_text.startswith('sudo'):
635 return []
635 return []
636 text = os.path.expanduser(text)
636 text = os.path.expanduser(text)
637 aliases = self.alias_table.keys()
637 aliases = self.alias_table.keys()
638 if text == '':
638 if text == '':
639 return aliases
639 return aliases
640 else:
640 else:
641 return [a for a in aliases if a.startswith(text)]
641 return [a for a in aliases if a.startswith(text)]
642
642
643 def python_matches(self,text):
643 def python_matches(self,text):
644 """Match attributes or global python names"""
644 """Match attributes or global python names"""
645
645
646 #io.rprint('Completer->python_matches, txt=%r' % text) # dbg
646 #io.rprint('Completer->python_matches, txt=%r' % text) # dbg
647 if "." in text:
647 if "." in text:
648 try:
648 try:
649 matches = self.attr_matches(text)
649 matches = self.attr_matches(text)
650 if text.endswith('.') and self.omit__names:
650 if text.endswith('.') and self.omit__names:
651 if self.omit__names == 1:
651 if self.omit__names == 1:
652 # true if txt is _not_ a __ name, false otherwise:
652 # true if txt is _not_ a __ name, false otherwise:
653 no__name = (lambda txt:
653 no__name = (lambda txt:
654 re.match(r'.*\.__.*?__',txt) is None)
654 re.match(r'.*\.__.*?__',txt) is None)
655 else:
655 else:
656 # true if txt is _not_ a _ name, false otherwise:
656 # true if txt is _not_ a _ name, false otherwise:
657 no__name = (lambda txt:
657 no__name = (lambda txt:
658 re.match(r'.*\._.*?',txt) is None)
658 re.match(r'.*\._.*?',txt) is None)
659 matches = filter(no__name, matches)
659 matches = filter(no__name, matches)
660 except NameError:
660 except NameError:
661 # catches <undefined attributes>.<tab>
661 # catches <undefined attributes>.<tab>
662 matches = []
662 matches = []
663 else:
663 else:
664 matches = self.global_matches(text)
664 matches = self.global_matches(text)
665
665
666 return matches
666 return matches
667
667
668 def _default_arguments_from_docstring(self,doc):
668 def _default_arguments_from_docstring(self,doc):
669 """Parse first line of docstring of the
669 """Parse first line of docstring of the
670 form 'min(iterable[, key=func])\n' to find
670 form 'min(iterable[, key=func])\n' to find
671 keyword argument names.
671 keyword argument names.
672 """
672 """
673 if doc is None: return []
673 if doc is None: return []
674 doc = doc.lstrip()
674 doc = doc.lstrip()
675 sio = StringIO.StringIO(doc)
675 sio = StringIO.StringIO(doc)
676 #care only the firstline
676 #care only the firstline
677 #docstring can be long
677 #docstring can be long
678 line = sio.readline()
678 line = sio.readline()
679 p = re.compile(r'^[\w|\s.]+\(([^)]*)\).*')
679 p = re.compile(r'^[\w|\s.]+\(([^)]*)\).*')
680 #'min(iterable[, key=func])\n' -> 'iterable[, key=func]'
680 #'min(iterable[, key=func])\n' -> 'iterable[, key=func]'
681 sig = p.search(line)
681 sig = p.search(line)
682 if sig is None: return []
682 if sig is None: return []
683 # iterable[, key=func]' -> ['iterable[' ,' key=func]']
683 # iterable[, key=func]' -> ['iterable[' ,' key=func]']
684 sig = sig.groups()[0].split(',')
684 sig = sig.groups()[0].split(',')
685 #use this if you want iterable to show up too
685 #use this if you want iterable to show up too
686 #q = re.compile('[\s|\[]*(\w+)(?:\s*=?\s*.*)')
686 #q = re.compile('[\s|\[]*(\w+)(?:\s*=?\s*.*)')
687 q = re.compile('[\s|\[]*(\w+)(?:\s*=\s*.*)')
687 q = re.compile('[\s|\[]*(\w+)(?:\s*=\s*.*)')
688 ret = []
688 ret = []
689 for s in sig:
689 for s in sig:
690 ret += q.findall(s)
690 ret += q.findall(s)
691 return ret
691 return ret
692
692
693 def _default_arguments(self, obj):
693 def _default_arguments(self, obj):
694 """Return the list of default arguments of obj if it is callable,
694 """Return the list of default arguments of obj if it is callable,
695 or empty list otherwise."""
695 or empty list otherwise."""
696 call_obj = obj
696 call_obj = obj
697 ret = []
697 ret = []
698 if inspect.isbuiltin(obj):
698 if inspect.isbuiltin(obj):
699 pass
699 pass
700 elif not (inspect.isfunction(obj) or inspect.ismethod(obj)):
700 elif not (inspect.isfunction(obj) or inspect.ismethod(obj)):
701 #for cython embededsignature=True the docstring belongs to
701 if inspect.isclass(obj):
702 #the object itself not __init__ or __call__
702 #for cython embededsignature=True the constructor docstring
703 #belongs to the object itself not __init__
703 ret += self._default_arguments_from_docstring(
704 ret += self._default_arguments_from_docstring(
704 getattr(obj,'__doc__',''))
705 getattr(obj,'__doc__',''))
705 if inspect.isclass(obj):
706 # for classes, check for __init__,__new__
706 # for classes, check for __init__,__new__
707 call_obj = (getattr(obj,'__init__',None) or
707 call_obj = (getattr(obj,'__init__',None) or
708 getattr(obj,'__new__',None))
708 getattr(obj,'__new__',None))
709 # for all others, check if they are __call__able
709 # for all others, check if they are __call__able
710 elif hasattr(obj, '__call__'):
710 elif hasattr(obj, '__call__'):
711 call_obj = obj.__call__
711 call_obj = obj.__call__
712
712
713 ret += self._default_arguments_from_docstring(
713 ret += self._default_arguments_from_docstring(
714 getattr(call_obj,'__doc__',''))
714 getattr(call_obj,'__doc__',''))
715
715
716 try:
716 try:
717 args,_,_1,defaults = inspect.getargspec(call_obj)
717 args,_,_1,defaults = inspect.getargspec(call_obj)
718 if defaults:
718 if defaults:
719 ret+=args[-len(defaults):]
719 ret+=args[-len(defaults):]
720 except TypeError:
720 except TypeError:
721 pass
721 pass
722
722
723 return list(set(ret))
723 return list(set(ret))
724
724
725 def python_func_kw_matches(self,text):
725 def python_func_kw_matches(self,text):
726 """Match named parameters (kwargs) of the last open function"""
726 """Match named parameters (kwargs) of the last open function"""
727
727
728 if "." in text: # a parameter cannot be dotted
728 if "." in text: # a parameter cannot be dotted
729 return []
729 return []
730 try: regexp = self.__funcParamsRegex
730 try: regexp = self.__funcParamsRegex
731 except AttributeError:
731 except AttributeError:
732 regexp = self.__funcParamsRegex = re.compile(r'''
732 regexp = self.__funcParamsRegex = re.compile(r'''
733 '.*?(?<!\\)' | # single quoted strings or
733 '.*?(?<!\\)' | # single quoted strings or
734 ".*?(?<!\\)" | # double quoted strings or
734 ".*?(?<!\\)" | # double quoted strings or
735 \w+ | # identifier
735 \w+ | # identifier
736 \S # other characters
736 \S # other characters
737 ''', re.VERBOSE | re.DOTALL)
737 ''', re.VERBOSE | re.DOTALL)
738 # 1. find the nearest identifier that comes before an unclosed
738 # 1. find the nearest identifier that comes before an unclosed
739 # parenthesis before the cursor
739 # parenthesis before the cursor
740 # e.g. for "foo (1+bar(x), pa<cursor>,a=1)", the candidate is "foo"
740 # e.g. for "foo (1+bar(x), pa<cursor>,a=1)", the candidate is "foo"
741 tokens = regexp.findall(self.text_until_cursor)
741 tokens = regexp.findall(self.text_until_cursor)
742 tokens.reverse()
742 tokens.reverse()
743 iterTokens = iter(tokens); openPar = 0
743 iterTokens = iter(tokens); openPar = 0
744
744
745 for token in iterTokens:
745 for token in iterTokens:
746 if token == ')':
746 if token == ')':
747 openPar -= 1
747 openPar -= 1
748 elif token == '(':
748 elif token == '(':
749 openPar += 1
749 openPar += 1
750 if openPar > 0:
750 if openPar > 0:
751 # found the last unclosed parenthesis
751 # found the last unclosed parenthesis
752 break
752 break
753 else:
753 else:
754 return []
754 return []
755 # 2. Concatenate dotted names ("foo.bar" for "foo.bar(x, pa" )
755 # 2. Concatenate dotted names ("foo.bar" for "foo.bar(x, pa" )
756 ids = []
756 ids = []
757 isId = re.compile(r'\w+$').match
757 isId = re.compile(r'\w+$').match
758
758
759 while True:
759 while True:
760 try:
760 try:
761 ids.append(next(iterTokens))
761 ids.append(next(iterTokens))
762 if not isId(ids[-1]):
762 if not isId(ids[-1]):
763 ids.pop(); break
763 ids.pop(); break
764 if not next(iterTokens) == '.':
764 if not next(iterTokens) == '.':
765 break
765 break
766 except StopIteration:
766 except StopIteration:
767 break
767 break
768 # lookup the candidate callable matches either using global_matches
768 # lookup the candidate callable matches either using global_matches
769 # or attr_matches for dotted names
769 # or attr_matches for dotted names
770 if len(ids) == 1:
770 if len(ids) == 1:
771 callableMatches = self.global_matches(ids[0])
771 callableMatches = self.global_matches(ids[0])
772 else:
772 else:
773 callableMatches = self.attr_matches('.'.join(ids[::-1]))
773 callableMatches = self.attr_matches('.'.join(ids[::-1]))
774 argMatches = []
774 argMatches = []
775 for callableMatch in callableMatches:
775 for callableMatch in callableMatches:
776 try:
776 try:
777 namedArgs = self._default_arguments(eval(callableMatch,
777 namedArgs = self._default_arguments(eval(callableMatch,
778 self.namespace))
778 self.namespace))
779 except:
779 except:
780 continue
780 continue
781
781
782 for namedArg in namedArgs:
782 for namedArg in namedArgs:
783 if namedArg.startswith(text):
783 if namedArg.startswith(text):
784 argMatches.append("%s=" %namedArg)
784 argMatches.append("%s=" %namedArg)
785 return argMatches
785 return argMatches
786
786
787 def dispatch_custom_completer(self, text):
787 def dispatch_custom_completer(self, text):
788 #io.rprint("Custom! '%s' %s" % (text, self.custom_completers)) # dbg
788 #io.rprint("Custom! '%s' %s" % (text, self.custom_completers)) # dbg
789 line = self.line_buffer
789 line = self.line_buffer
790 if not line.strip():
790 if not line.strip():
791 return None
791 return None
792
792
793 # Create a little structure to pass all the relevant information about
793 # Create a little structure to pass all the relevant information about
794 # the current completion to any custom completer.
794 # the current completion to any custom completer.
795 event = Bunch()
795 event = Bunch()
796 event.line = line
796 event.line = line
797 event.symbol = text
797 event.symbol = text
798 cmd = line.split(None,1)[0]
798 cmd = line.split(None,1)[0]
799 event.command = cmd
799 event.command = cmd
800 event.text_until_cursor = self.text_until_cursor
800 event.text_until_cursor = self.text_until_cursor
801
801
802 #print "\ncustom:{%s]\n" % event # dbg
802 #print "\ncustom:{%s]\n" % event # dbg
803
803
804 # for foo etc, try also to find completer for %foo
804 # for foo etc, try also to find completer for %foo
805 if not cmd.startswith(self.magic_escape):
805 if not cmd.startswith(self.magic_escape):
806 try_magic = self.custom_completers.s_matches(
806 try_magic = self.custom_completers.s_matches(
807 self.magic_escape + cmd)
807 self.magic_escape + cmd)
808 else:
808 else:
809 try_magic = []
809 try_magic = []
810
810
811 for c in itertools.chain(self.custom_completers.s_matches(cmd),
811 for c in itertools.chain(self.custom_completers.s_matches(cmd),
812 try_magic,
812 try_magic,
813 self.custom_completers.flat_matches(self.text_until_cursor)):
813 self.custom_completers.flat_matches(self.text_until_cursor)):
814 #print "try",c # dbg
814 #print "try",c # dbg
815 try:
815 try:
816 res = c(event)
816 res = c(event)
817 if res:
817 if res:
818 # first, try case sensitive match
818 # first, try case sensitive match
819 withcase = [r for r in res if r.startswith(text)]
819 withcase = [r for r in res if r.startswith(text)]
820 if withcase:
820 if withcase:
821 return withcase
821 return withcase
822 # if none, then case insensitive ones are ok too
822 # if none, then case insensitive ones are ok too
823 text_low = text.lower()
823 text_low = text.lower()
824 return [r for r in res if r.lower().startswith(text_low)]
824 return [r for r in res if r.lower().startswith(text_low)]
825 except TryNext:
825 except TryNext:
826 pass
826 pass
827
827
828 return None
828 return None
829
829
830 def complete(self, text=None, line_buffer=None, cursor_pos=None):
830 def complete(self, text=None, line_buffer=None, cursor_pos=None):
831 """Find completions for the given text and line context.
831 """Find completions for the given text and line context.
832
832
833 This is called successively with state == 0, 1, 2, ... until it
833 This is called successively with state == 0, 1, 2, ... until it
834 returns None. The completion should begin with 'text'.
834 returns None. The completion should begin with 'text'.
835
835
836 Note that both the text and the line_buffer are optional, but at least
836 Note that both the text and the line_buffer are optional, but at least
837 one of them must be given.
837 one of them must be given.
838
838
839 Parameters
839 Parameters
840 ----------
840 ----------
841 text : string, optional
841 text : string, optional
842 Text to perform the completion on. If not given, the line buffer
842 Text to perform the completion on. If not given, the line buffer
843 is split using the instance's CompletionSplitter object.
843 is split using the instance's CompletionSplitter object.
844
844
845 line_buffer : string, optional
845 line_buffer : string, optional
846 If not given, the completer attempts to obtain the current line
846 If not given, the completer attempts to obtain the current line
847 buffer via readline. This keyword allows clients which are
847 buffer via readline. This keyword allows clients which are
848 requesting for text completions in non-readline contexts to inform
848 requesting for text completions in non-readline contexts to inform
849 the completer of the entire text.
849 the completer of the entire text.
850
850
851 cursor_pos : int, optional
851 cursor_pos : int, optional
852 Index of the cursor in the full line buffer. Should be provided by
852 Index of the cursor in the full line buffer. Should be provided by
853 remote frontends where kernel has no access to frontend state.
853 remote frontends where kernel has no access to frontend state.
854
854
855 Returns
855 Returns
856 -------
856 -------
857 text : str
857 text : str
858 Text that was actually used in the completion.
858 Text that was actually used in the completion.
859
859
860 matches : list
860 matches : list
861 A list of completion matches.
861 A list of completion matches.
862 """
862 """
863 #io.rprint('\nCOMP1 %r %r %r' % (text, line_buffer, cursor_pos)) # dbg
863 #io.rprint('\nCOMP1 %r %r %r' % (text, line_buffer, cursor_pos)) # dbg
864
864
865 # if the cursor position isn't given, the only sane assumption we can
865 # if the cursor position isn't given, the only sane assumption we can
866 # make is that it's at the end of the line (the common case)
866 # make is that it's at the end of the line (the common case)
867 if cursor_pos is None:
867 if cursor_pos is None:
868 cursor_pos = len(line_buffer) if text is None else len(text)
868 cursor_pos = len(line_buffer) if text is None else len(text)
869
869
870 # if text is either None or an empty string, rely on the line buffer
870 # if text is either None or an empty string, rely on the line buffer
871 if not text:
871 if not text:
872 text = self.splitter.split_line(line_buffer, cursor_pos)
872 text = self.splitter.split_line(line_buffer, cursor_pos)
873
873
874 # If no line buffer is given, assume the input text is all there was
874 # If no line buffer is given, assume the input text is all there was
875 if line_buffer is None:
875 if line_buffer is None:
876 line_buffer = text
876 line_buffer = text
877
877
878 self.line_buffer = line_buffer
878 self.line_buffer = line_buffer
879 self.text_until_cursor = self.line_buffer[:cursor_pos]
879 self.text_until_cursor = self.line_buffer[:cursor_pos]
880 #io.rprint('COMP2 %r %r %r' % (text, line_buffer, cursor_pos)) # dbg
880 #io.rprint('COMP2 %r %r %r' % (text, line_buffer, cursor_pos)) # dbg
881
881
882 # Start with a clean slate of completions
882 # Start with a clean slate of completions
883 self.matches[:] = []
883 self.matches[:] = []
884 custom_res = self.dispatch_custom_completer(text)
884 custom_res = self.dispatch_custom_completer(text)
885 if custom_res is not None:
885 if custom_res is not None:
886 # did custom completers produce something?
886 # did custom completers produce something?
887 self.matches = custom_res
887 self.matches = custom_res
888 else:
888 else:
889 # Extend the list of completions with the results of each
889 # Extend the list of completions with the results of each
890 # matcher, so we return results to the user from all
890 # matcher, so we return results to the user from all
891 # namespaces.
891 # namespaces.
892 if self.merge_completions:
892 if self.merge_completions:
893 self.matches = []
893 self.matches = []
894 for matcher in self.matchers:
894 for matcher in self.matchers:
895 try:
895 try:
896 self.matches.extend(matcher(text))
896 self.matches.extend(matcher(text))
897 except:
897 except:
898 # Show the ugly traceback if the matcher causes an
898 # Show the ugly traceback if the matcher causes an
899 # exception, but do NOT crash the kernel!
899 # exception, but do NOT crash the kernel!
900 sys.excepthook(*sys.exc_info())
900 sys.excepthook(*sys.exc_info())
901 else:
901 else:
902 for matcher in self.matchers:
902 for matcher in self.matchers:
903 self.matches = matcher(text)
903 self.matches = matcher(text)
904 if self.matches:
904 if self.matches:
905 break
905 break
906 # FIXME: we should extend our api to return a dict with completions for
906 # FIXME: we should extend our api to return a dict with completions for
907 # different types of objects. The rlcomplete() method could then
907 # different types of objects. The rlcomplete() method could then
908 # simply collapse the dict into a list for readline, but we'd have
908 # simply collapse the dict into a list for readline, but we'd have
909 # richer completion semantics in other evironments.
909 # richer completion semantics in other evironments.
910 self.matches = sorted(set(self.matches))
910 self.matches = sorted(set(self.matches))
911 #io.rprint('COMP TEXT, MATCHES: %r, %r' % (text, self.matches)) # dbg
911 #io.rprint('COMP TEXT, MATCHES: %r, %r' % (text, self.matches)) # dbg
912 return text, self.matches
912 return text, self.matches
913
913
914 def rlcomplete(self, text, state):
914 def rlcomplete(self, text, state):
915 """Return the state-th possible completion for 'text'.
915 """Return the state-th possible completion for 'text'.
916
916
917 This is called successively with state == 0, 1, 2, ... until it
917 This is called successively with state == 0, 1, 2, ... until it
918 returns None. The completion should begin with 'text'.
918 returns None. The completion should begin with 'text'.
919
919
920 Parameters
920 Parameters
921 ----------
921 ----------
922 text : string
922 text : string
923 Text to perform the completion on.
923 Text to perform the completion on.
924
924
925 state : int
925 state : int
926 Counter used by readline.
926 Counter used by readline.
927 """
927 """
928 if state==0:
928 if state==0:
929
929
930 self.line_buffer = line_buffer = self.readline.get_line_buffer()
930 self.line_buffer = line_buffer = self.readline.get_line_buffer()
931 cursor_pos = self.readline.get_endidx()
931 cursor_pos = self.readline.get_endidx()
932
932
933 #io.rprint("\nRLCOMPLETE: %r %r %r" %
933 #io.rprint("\nRLCOMPLETE: %r %r %r" %
934 # (text, line_buffer, cursor_pos) ) # dbg
934 # (text, line_buffer, cursor_pos) ) # dbg
935
935
936 # if there is only a tab on a line with only whitespace, instead of
936 # if there is only a tab on a line with only whitespace, instead of
937 # the mostly useless 'do you want to see all million completions'
937 # the mostly useless 'do you want to see all million completions'
938 # message, just do the right thing and give the user his tab!
938 # message, just do the right thing and give the user his tab!
939 # Incidentally, this enables pasting of tabbed text from an editor
939 # Incidentally, this enables pasting of tabbed text from an editor
940 # (as long as autoindent is off).
940 # (as long as autoindent is off).
941
941
942 # It should be noted that at least pyreadline still shows file
942 # It should be noted that at least pyreadline still shows file
943 # completions - is there a way around it?
943 # completions - is there a way around it?
944
944
945 # don't apply this on 'dumb' terminals, such as emacs buffers, so
945 # don't apply this on 'dumb' terminals, such as emacs buffers, so
946 # we don't interfere with their own tab-completion mechanism.
946 # we don't interfere with their own tab-completion mechanism.
947 if not (self.dumb_terminal or line_buffer.strip()):
947 if not (self.dumb_terminal or line_buffer.strip()):
948 self.readline.insert_text('\t')
948 self.readline.insert_text('\t')
949 sys.stdout.flush()
949 sys.stdout.flush()
950 return None
950 return None
951
951
952 # Note: debugging exceptions that may occur in completion is very
952 # Note: debugging exceptions that may occur in completion is very
953 # tricky, because readline unconditionally silences them. So if
953 # tricky, because readline unconditionally silences them. So if
954 # during development you suspect a bug in the completion code, turn
954 # during development you suspect a bug in the completion code, turn
955 # this flag on temporarily by uncommenting the second form (don't
955 # this flag on temporarily by uncommenting the second form (don't
956 # flip the value in the first line, as the '# dbg' marker can be
956 # flip the value in the first line, as the '# dbg' marker can be
957 # automatically detected and is used elsewhere).
957 # automatically detected and is used elsewhere).
958 DEBUG = False
958 DEBUG = False
959 #DEBUG = True # dbg
959 #DEBUG = True # dbg
960 if DEBUG:
960 if DEBUG:
961 try:
961 try:
962 self.complete(text, line_buffer, cursor_pos)
962 self.complete(text, line_buffer, cursor_pos)
963 except:
963 except:
964 import traceback; traceback.print_exc()
964 import traceback; traceback.print_exc()
965 else:
965 else:
966 # The normal production version is here
966 # The normal production version is here
967
967
968 # This method computes the self.matches array
968 # This method computes the self.matches array
969 self.complete(text, line_buffer, cursor_pos)
969 self.complete(text, line_buffer, cursor_pos)
970
970
971 try:
971 try:
972 return self.matches[state]
972 return self.matches[state]
973 except IndexError:
973 except IndexError:
974 return None
974 return None
General Comments 0
You need to be logged in to leave comments. Login now