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