1
"""Word completion for IPython.
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
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
7
IPython-specific utility.
9
---------------------------------------------------------------------------
10
Original rlcompleter documentation:
12
This requires the latest extension to the readline module (the
13
completes keywords, built-ins and globals in __main__; when completing
14
NAME.NAME..., it evaluates (!) the expression up to the last dot and
15
completes its attributes.
17
It's very cool to do "import string" type "string.", hit the
18
completion key (twice), and see the list of names defined by the
21
Tip: to use the tab key as the completion key, call
23
readline.parse_and_bind("tab: complete")
27
- Exceptions raised by the completer function are *ignored* (and
28
generally cause the completion to fail). This is a feature -- since
29
readline sets the tty device in raw (or cbreak) mode, printing a
30
traceback wouldn't work well without some complicated hoopla to save,
31
reset and restore the tty state.
33
- The evaluation of the NAME.NAME... form may cause arbitrary
34
application defined code to be executed if an object with a
35
__getattr__ hook is found. Since it is the responsibility of the
36
application (or the user) to enable this feature, I consider this an
37
acceptable risk. More complicated expressions (e.g. function calls or
38
indexing operations) are *not* evaluated.
40
- GNU readline is also used by the built-in functions input() and
41
raw_input(), and thus these also benefit/suffer from the completer
42
features. Clearly an interactive application can benefit by
43
specifying its own completer function and using raw_input() for all
46
- When the original stdin is not a tty device, GNU readline is never
47
used, and this module (and the readline module) are silently inactive.
51
#*****************************************************************************
53
# Since this file is essentially a minimally modified copy of the rlcompleter
54
# module which is part of the standard Python distribution, I assume that the
55
# proper procedure is to maintain its copyright as belonging to the Python
56
# Software Foundation (in addition to my own, for all new code).
58
# Copyright (C) 2001 Python Software Foundation, www.python.org
59
# Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
61
# Distributed under the terms of the BSD License. The full license is in
62
# the file COPYING, distributed as part of this software.
64
#*****************************************************************************
74
import IPython.rlineimpl as readline
76
from IPython.ipstruct import Struct
77
from IPython import ipapi
78
from IPython import generics
81
# Python 2.4 offers sets as a builtin
85
from sets import Set as set
87
from IPython.genutils import debugx, dir2
89
__all__ = ['Completer','IPCompleter']
92
def __init__(self,namespace=None,global_namespace=None):
93
"""Create a new completer for the command line.
95
Completer([namespace,global_namespace]) -> completer instance.
97
If unspecified, the default namespace where completions are performed
98
is __main__ (technically, __main__.__dict__). Namespaces should be
99
given as dictionaries.
101
An optional second namespace can be given. This allows the completer
102
to handle cases where both the local and global scopes need to be
105
Completer instances should be used as the completion mechanism of
106
readline via the set_completer() call:
108
readline.set_completer(Completer(my_namespace).complete)
111
# some minimal strict typechecks. For some core data structures, I
112
# want actual basic python types, not just anything that looks like
113
# one. This is especially true for namespaces.
114
for ns in (namespace,global_namespace):
115
if ns is not None and type(ns) != types.DictType:
116
raise TypeError,'namespace must be a dictionary'
118
# Don't bind to namespace quite yet, but flag whether the user wants a
119
# specific namespace or to use __main__.__dict__. This will allow us
120
# to bind to __main__.__dict__ at completion time, not now.
121
if namespace is None:
125
self.namespace = namespace
127
# The global namespace, if given, can be bound directly
128
if global_namespace is None:
129
self.global_namespace = {}
131
self.global_namespace = global_namespace
133
def complete(self, text, state):
134
"""Return the next possible completion for 'text'.
136
This is called successively with state == 0, 1, 2, ... until it
137
returns None. The completion should begin with 'text'.
141
self.namespace = __main__.__dict__
145
self.matches = self.attr_matches(text)
147
self.matches = self.global_matches(text)
149
return self.matches[state]
153
def global_matches(self, text):
154
"""Compute matches when text is a simple name.
156
Return a list of all keywords, built-in functions and names currently
157
defined in self.namespace or self.global_namespace that match.
161
match_append = matches.append
163
for lst in [keyword.kwlist,
164
__builtin__.__dict__.keys(),
165
self.namespace.keys(),
166
self.global_namespace.keys()]:
168
if word[:n] == text and word != "__builtins__":
172
def attr_matches(self, text):
173
"""Compute matches when text contains a dot.
175
Assuming the text is of the form NAME.NAME....[NAME], and is
176
evaluatable in self.namespace or self.global_namespace, it will be
177
evaluated and its attributes (as revealed by dir()) are used as
178
possible completions. (For class instances, class members are are
181
WARNING: this can still invoke arbitrary C code, if an object
182
with a __getattr__ hook is evaluated.
187
# Another option, seems to work great. Catches things like ''.<tab>
188
m = re.match(r"(\S+(\.\w+)*)\.(\w*)$", text)
193
expr, attr = m.group(1, 3)
195
obj = eval(expr, self.namespace)
198
obj = eval(expr, self.global_namespace)
205
words = generics.complete_object(obj, words)
206
except ipapi.TryNext:
208
# Build match list to return
210
res = ["%s.%s" % (expr, w) for w in words if w[:n] == attr ]
213
class IPCompleter(Completer):
214
"""Extension of the completer class with IPython-specific features"""
216
def __init__(self,shell,namespace=None,global_namespace=None,
217
omit__names=0,alias_table=None):
218
"""IPCompleter() -> completer
220
Return a completer object suitable for use by the readline library
221
via readline.set_completer().
225
- shell: a pointer to the ipython shell itself. This is needed
226
because this completer knows about magic functions, and those can
227
only be accessed via the ipython instance.
229
- namespace: an optional dict where completions are performed.
231
- global_namespace: secondary optional dict for completions, to
232
handle cases (such as IPython embedded inside functions) where
233
both Python scopes are visible.
235
- The optional omit__names parameter sets the completer to omit the
236
'magic' names (__magicname__) for python objects unless the text
237
to be completed explicitly starts with one or more underscores.
239
- If alias_table is supplied, it should be a dictionary of aliases
242
Completer.__init__(self,namespace,global_namespace)
243
self.magic_prefix = shell.name+'.magic_'
244
self.magic_escape = shell.ESC_MAGIC
245
self.readline = readline
246
delims = self.readline.get_completer_delims()
247
delims = delims.replace(self.magic_escape,'')
248
self.readline.set_completer_delims(delims)
249
self.get_line_buffer = self.readline.get_line_buffer
250
self.get_endidx = self.readline.get_endidx
251
self.omit__names = omit__names
252
self.merge_completions = shell.rc.readline_merge_completions
253
if alias_table is None:
255
self.alias_table = alias_table
256
# Regexp to split filenames with spaces in them
257
self.space_name_re = re.compile(r'([^\\] )')
258
# Hold a local ref. to glob.glob for speed
259
self.glob = glob.glob
261
# Determine if we are running on 'dumb' terminals, like (X)Emacs
262
# buffers, to avoid completion problems.
263
term = os.environ.get('TERM','xterm')
264
self.dumb_terminal = term in ['dumb','emacs']
266
# Special handling of backslashes needed in win32 platforms
267
if sys.platform == "win32":
268
self.clean_glob = self._clean_glob_win32
270
self.clean_glob = self._clean_glob
271
self.matchers = [self.python_matches,
274
self.python_func_kw_matches]
277
# Code contributed by Alex Schmolck, for ipython/emacs integration
278
def all_completions(self, text):
279
"""Return all possible completions for the benefit of emacs."""
282
comp_append = completions.append
284
for i in xrange(sys.maxint):
285
res = self.complete(text, i)
290
#XXX workaround for ``notDefined.<tab>``
294
# /end Alex Schmolck code.
296
def _clean_glob(self,text):
297
return self.glob("%s*" % text)
299
def _clean_glob_win32(self,text):
300
return [f.replace("\\","/")
301
for f in self.glob("%s*" % text)]
303
def file_matches(self, text):
304
"""Match filenames, expanding ~USER type strings.
306
Most of the seemingly convoluted logic in this completer is an
307
attempt to handle filenames with spaces in them. And yet it's not
308
quite perfect, because Python's readline doesn't expose all of the
309
GNU readline details needed for this to be done correctly.
311
For a filename with a space in it, the printed completions will be
312
only the parts after what's already been typed (instead of the
313
full completions, as is normally done). I don't think with the
314
current (as of Python 2.3) Python readline it's possible to do
317
#print 'Completer->file_matches: <%s>' % text # dbg
319
# chars that require escaping with backslash - i.e. chars
320
# that readline treats incorrectly as delimiters, but we
321
# don't want to treat as delimiters in filename matching
322
# when escaped with backslash
324
protectables = ' ()[]{}'
326
if text.startswith('!'):
332
def protect_filename(s):
333
return "".join([(ch in protectables and '\\' + ch or ch)
336
def single_dir_expand(matches):
337
"Recursively expand match lists containing a single dir."
339
if len(matches) == 1 and os.path.isdir(matches[0]):
340
# Takes care of links to directories also. Use '/'
341
# explicitly, even under Windows, so that name completions
342
# don't end up escaped.
344
if d[-1] in ['/','\\']:
347
subdirs = os.listdir(d)
349
matches = [ (d + '/' + p) for p in subdirs]
350
return single_dir_expand(matches)
357
open_quotes = 0 # track strings with open quotes
359
lsplit = shlex.split(lbuf)[-1]
361
# typically an unmatched ", or backslash without escaped char.
362
if lbuf.count('"')==1:
364
lsplit = lbuf.split('"')[-1]
365
elif lbuf.count("'")==1:
367
lsplit = lbuf.split("'")[-1]
371
# tab pressed on empty line
374
if lsplit != protect_filename(lsplit):
375
# if protectables are found, do matching on the whole escaped
378
text0,text = text,lsplit
381
text = os.path.expanduser(text)
384
return [text_prefix + protect_filename(f) for f in self.glob("*")]
386
m0 = self.clean_glob(text.replace('\\',''))
388
# If we had protectables, we need to revert our changes to the
389
# beginning of filename so that we don't double-write the part
390
# of the filename we have so far
391
len_lsplit = len(lsplit)
392
matches = [text_prefix + text0 +
393
protect_filename(f[len_lsplit:]) for f in m0]
396
# if we have a string with an open quote, we don't need to
397
# protect the names at all (and we _shouldn't_, as it
398
# would cause bugs when the filesystem call is made).
401
matches = [text_prefix +
402
protect_filename(f) for f in m0]
404
#print 'mm',matches # dbg
405
return single_dir_expand(matches)
407
def alias_matches(self, text):
408
"""Match internal system aliases"""
409
#print 'Completer->alias_matches:',text,'lb',self.lbuf # dbg
411
# if we are not in the first 'item', alias matching
412
# doesn't make sense - unless we are starting with 'sudo' command.
413
if ' ' in self.lbuf.lstrip() and not self.lbuf.lstrip().startswith('sudo'):
415
text = os.path.expanduser(text)
416
aliases = self.alias_table.keys()
420
return [alias for alias in aliases if alias.startswith(text)]
422
def python_matches(self,text):
423
"""Match attributes or global python names"""
425
#print 'Completer->python_matches, txt=<%s>' % text # dbg
428
matches = self.attr_matches(text)
429
if text.endswith('.') and self.omit__names:
430
if self.omit__names == 1:
431
# true if txt is _not_ a __ name, false otherwise:
432
no__name = (lambda txt:
433
re.match(r'.*\.__.*?__',txt) is None)
435
# true if txt is _not_ a _ name, false otherwise:
436
no__name = (lambda txt:
437
re.match(r'.*\._.*?',txt) is None)
438
matches = filter(no__name, matches)
440
# catches <undefined attributes>.<tab>
443
matches = self.global_matches(text)
444
# this is so completion finds magics when automagic is on:
445
if (matches == [] and
446
not text.startswith(os.sep) and
447
not ' ' in self.lbuf):
448
matches = self.attr_matches(self.magic_prefix+text)
451
def _default_arguments(self, obj):
452
"""Return the list of default arguments of obj if it is callable,
453
or empty list otherwise."""
455
if not (inspect.isfunction(obj) or inspect.ismethod(obj)):
456
# for classes, check for __init__,__new__
457
if inspect.isclass(obj):
458
obj = (getattr(obj,'__init__',None) or
459
getattr(obj,'__new__',None))
460
# for all others, check if they are __call__able
461
elif hasattr(obj, '__call__'):
463
# XXX: is there a way to handle the builtins ?
465
args,_,_1,defaults = inspect.getargspec(obj)
467
return args[-len(defaults):]
468
except TypeError: pass
471
def python_func_kw_matches(self,text):
472
"""Match named parameters (kwargs) of the last open function"""
474
if "." in text: # a parameter cannot be dotted
476
try: regexp = self.__funcParamsRegex
477
except AttributeError:
478
regexp = self.__funcParamsRegex = re.compile(r'''
479
'.*?' | # single quoted strings or
480
".*?" | # double quoted strings or
482
\S # other characters
483
''', re.VERBOSE | re.DOTALL)
484
# 1. find the nearest identifier that comes before an unclosed
485
# parenthesis e.g. for "foo (1+bar(x), pa", the candidate is "foo"
486
tokens = regexp.findall(self.get_line_buffer())
488
iterTokens = iter(tokens); openPar = 0
489
for token in iterTokens:
495
# found the last unclosed parenthesis
499
# 2. Concatenate dotted names ("foo.bar" for "foo.bar(x, pa" )
501
isId = re.compile(r'\w+$').match
504
ids.append(iterTokens.next())
505
if not isId(ids[-1]):
507
if not iterTokens.next() == '.':
509
except StopIteration:
511
# lookup the candidate callable matches either using global_matches
512
# or attr_matches for dotted names
514
callableMatches = self.global_matches(ids[0])
516
callableMatches = self.attr_matches('.'.join(ids[::-1]))
518
for callableMatch in callableMatches:
519
try: namedArgs = self._default_arguments(eval(callableMatch,
522
for namedArg in namedArgs:
523
if namedArg.startswith(text):
524
argMatches.append("%s=" %namedArg)
527
def dispatch_custom_completer(self,text):
528
#print "Custom! '%s' %s" % (text, self.custom_completers) # dbg
529
line = self.full_lbuf
536
cmd = line.split(None,1)[0]
538
#print "\ncustom:{%s]\n" % event # dbg
540
# for foo etc, try also to find completer for %foo
541
if not cmd.startswith(self.magic_escape):
542
try_magic = self.custom_completers.s_matches(
543
self.magic_escape + cmd)
548
for c in itertools.chain(
549
self.custom_completers.s_matches(cmd),
551
self.custom_completers.flat_matches(self.lbuf)):
555
# first, try case sensitive match
556
withcase = [r for r in res if r.startswith(text)]
559
# if none, then case insensitive ones are ok too
560
return [r for r in res if r.lower().startswith(text.lower())]
561
except ipapi.TryNext:
566
def complete(self, text, state,line_buffer=None):
567
"""Return the next possible completion for 'text'.
569
This is called successively with state == 0, 1, 2, ... until it
570
returns None. The completion should begin with 'text'.
573
- line_buffer: string
574
If not given, the completer attempts to obtain the current line buffer
575
via readline. This keyword allows clients which are requesting for
576
text completions in non-readline contexts to inform the completer of
580
#print '\n*** COMPLETE: <%s> (%s)' % (text,state) # dbg
582
# if there is only a tab on a line with only whitespace, instead
583
# of the mostly useless 'do you want to see all million
584
# completions' message, just do the right thing and give the user
585
# his tab! Incidentally, this enables pasting of tabbed text from
586
# an editor (as long as autoindent is off).
588
# It should be noted that at least pyreadline still shows
589
# file completions - is there a way around it?
591
# don't apply this on 'dumb' terminals, such as emacs buffers, so we
592
# don't interfere with their own tab-completion mechanism.
593
if line_buffer is None:
594
self.full_lbuf = self.get_line_buffer()
596
self.full_lbuf = line_buffer
598
if not (self.dumb_terminal or self.full_lbuf.strip()):
599
self.readline.insert_text('\t')
602
magic_escape = self.magic_escape
603
magic_prefix = self.magic_prefix
605
self.lbuf = self.full_lbuf[:self.get_endidx()]
608
if text.startswith(magic_escape):
609
text = text.replace(magic_escape,magic_prefix)
610
elif text.startswith('~'):
611
text = os.path.expanduser(text)
613
custom_res = self.dispatch_custom_completer(text)
614
if custom_res is not None:
615
# did custom completers produce something?
616
self.matches = custom_res
618
# Extend the list of completions with the results of each
619
# matcher, so we return results to the user from all
621
if self.merge_completions:
623
for matcher in self.matchers:
624
self.matches.extend(matcher(text))
626
for matcher in self.matchers:
627
self.matches = matcher(text)
632
return [set.setdefault(e,e) for e in alist if e not in set]
633
self.matches = uniq(self.matches)
635
ret = self.matches[state].replace(magic_prefix,magic_escape)
640
#from IPython.ultraTB import AutoFormattedTB; # dbg
641
#tb=AutoFormattedTB('Verbose');tb() #dbg
643
# If completion fails, don't annoy the user.
added
removed
IPython/completer.py
