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