##// END OF EJS Templates
Merge pull request #13284 from Carreau/dict-higher...
Matthias Bussonnier -
r27067:9100ebdd merge
parent child Browse files
Show More
@@ -1,2257 +1,2257 b''
1 1 """Completion for IPython.
2 2
3 3 This module started as 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,
6 6
7 7 This module now support a wide variety of completion mechanism both available
8 8 for normal classic Python code, as well as completer for IPython specific
9 9 Syntax like magics.
10 10
11 11 Latex and Unicode completion
12 12 ============================
13 13
14 14 IPython and compatible frontends not only can complete your code, but can help
15 15 you to input a wide range of characters. In particular we allow you to insert
16 16 a unicode character using the tab completion mechanism.
17 17
18 18 Forward latex/unicode completion
19 19 --------------------------------
20 20
21 21 Forward completion allows you to easily type a unicode character using its latex
22 22 name, or unicode long description. To do so type a backslash follow by the
23 23 relevant name and press tab:
24 24
25 25
26 26 Using latex completion:
27 27
28 28 .. code::
29 29
30 30 \\alpha<tab>
31 31 Ξ±
32 32
33 33 or using unicode completion:
34 34
35 35
36 36 .. code::
37 37
38 38 \\GREEK SMALL LETTER ALPHA<tab>
39 39 Ξ±
40 40
41 41
42 42 Only valid Python identifiers will complete. Combining characters (like arrow or
43 43 dots) are also available, unlike latex they need to be put after the their
44 44 counterpart that is to say, `F\\\\vec<tab>` is correct, not `\\\\vec<tab>F`.
45 45
46 46 Some browsers are known to display combining characters incorrectly.
47 47
48 48 Backward latex completion
49 49 -------------------------
50 50
51 51 It is sometime challenging to know how to type a character, if you are using
52 52 IPython, or any compatible frontend you can prepend backslash to the character
53 53 and press `<tab>` to expand it to its latex form.
54 54
55 55 .. code::
56 56
57 57 \\Ξ±<tab>
58 58 \\alpha
59 59
60 60
61 61 Both forward and backward completions can be deactivated by setting the
62 62 ``Completer.backslash_combining_completions`` option to ``False``.
63 63
64 64
65 65 Experimental
66 66 ============
67 67
68 68 Starting with IPython 6.0, this module can make use of the Jedi library to
69 69 generate completions both using static analysis of the code, and dynamically
70 70 inspecting multiple namespaces. Jedi is an autocompletion and static analysis
71 71 for Python. The APIs attached to this new mechanism is unstable and will
72 72 raise unless use in an :any:`provisionalcompleter` context manager.
73 73
74 74 You will find that the following are experimental:
75 75
76 76 - :any:`provisionalcompleter`
77 77 - :any:`IPCompleter.completions`
78 78 - :any:`Completion`
79 79 - :any:`rectify_completions`
80 80
81 81 .. note::
82 82
83 83 better name for :any:`rectify_completions` ?
84 84
85 85 We welcome any feedback on these new API, and we also encourage you to try this
86 86 module in debug mode (start IPython with ``--Completer.debug=True``) in order
87 87 to have extra logging information if :any:`jedi` is crashing, or if current
88 88 IPython completer pending deprecations are returning results not yet handled
89 89 by :any:`jedi`
90 90
91 91 Using Jedi for tab completion allow snippets like the following to work without
92 92 having to execute any code:
93 93
94 94 >>> myvar = ['hello', 42]
95 95 ... myvar[1].bi<tab>
96 96
97 97 Tab completion will be able to infer that ``myvar[1]`` is a real number without
98 98 executing any code unlike the previously available ``IPCompleter.greedy``
99 99 option.
100 100
101 101 Be sure to update :any:`jedi` to the latest stable version or to try the
102 102 current development version to get better completions.
103 103 """
104 104
105 105
106 106 # Copyright (c) IPython Development Team.
107 107 # Distributed under the terms of the Modified BSD License.
108 108 #
109 109 # Some of this code originated from rlcompleter in the Python standard library
110 110 # Copyright (C) 2001 Python Software Foundation, www.python.org
111 111
112 112
113 113 import builtins as builtin_mod
114 114 import glob
115 115 import inspect
116 116 import itertools
117 117 import keyword
118 118 import os
119 119 import re
120 120 import string
121 121 import sys
122 122 import time
123 123 import unicodedata
124 124 import uuid
125 125 import warnings
126 126 from contextlib import contextmanager
127 127 from importlib import import_module
128 128 from types import SimpleNamespace
129 129 from typing import Iterable, Iterator, List, Tuple, Union, Any, Sequence, Dict, NamedTuple, Pattern, Optional
130 130
131 131 from IPython.core.error import TryNext
132 132 from IPython.core.inputtransformer2 import ESC_MAGIC
133 133 from IPython.core.latex_symbols import latex_symbols, reverse_latex_symbol
134 134 from IPython.core.oinspect import InspectColors
135 135 from IPython.utils import generics
136 136 from IPython.utils.dir2 import dir2, get_real_method
137 137 from IPython.utils.path import ensure_dir_exists
138 138 from IPython.utils.process import arg_split
139 139 from traitlets import Bool, Enum, Int, List as ListTrait, Unicode, default, observe
140 140 from traitlets.config.configurable import Configurable
141 141
142 142 import __main__
143 143
144 144 # skip module docstests
145 145 __skip_doctest__ = True
146 146
147 147 try:
148 148 import jedi
149 149 jedi.settings.case_insensitive_completion = False
150 150 import jedi.api.helpers
151 151 import jedi.api.classes
152 152 JEDI_INSTALLED = True
153 153 except ImportError:
154 154 JEDI_INSTALLED = False
155 155 #-----------------------------------------------------------------------------
156 156 # Globals
157 157 #-----------------------------------------------------------------------------
158 158
159 159 # ranges where we have most of the valid unicode names. We could be more finer
160 160 # grained but is it worth it for performance While unicode have character in the
161 161 # range 0, 0x110000, we seem to have name for about 10% of those. (131808 as I
162 162 # write this). With below range we cover them all, with a density of ~67%
163 163 # biggest next gap we consider only adds up about 1% density and there are 600
164 164 # gaps that would need hard coding.
165 165 _UNICODE_RANGES = [(32, 0x3134b), (0xe0001, 0xe01f0)]
166 166
167 167 # Public API
168 168 __all__ = ['Completer','IPCompleter']
169 169
170 170 if sys.platform == 'win32':
171 171 PROTECTABLES = ' '
172 172 else:
173 173 PROTECTABLES = ' ()[]{}?=\\|;:\'#*"^&'
174 174
175 175 # Protect against returning an enormous number of completions which the frontend
176 176 # may have trouble processing.
177 177 MATCHES_LIMIT = 500
178 178
179 179 _deprecation_readline_sentinel = object()
180 180
181 181
182 182 class ProvisionalCompleterWarning(FutureWarning):
183 183 """
184 184 Exception raise by an experimental feature in this module.
185 185
186 186 Wrap code in :any:`provisionalcompleter` context manager if you
187 187 are certain you want to use an unstable feature.
188 188 """
189 189 pass
190 190
191 191 warnings.filterwarnings('error', category=ProvisionalCompleterWarning)
192 192
193 193 @contextmanager
194 194 def provisionalcompleter(action='ignore'):
195 195 """
196 196 This context manager has to be used in any place where unstable completer
197 197 behavior and API may be called.
198 198
199 199 >>> with provisionalcompleter():
200 200 ... completer.do_experimental_things() # works
201 201
202 202 >>> completer.do_experimental_things() # raises.
203 203
204 204 .. note::
205 205
206 206 Unstable
207 207
208 208 By using this context manager you agree that the API in use may change
209 209 without warning, and that you won't complain if they do so.
210 210
211 211 You also understand that, if the API is not to your liking, you should report
212 212 a bug to explain your use case upstream.
213 213
214 214 We'll be happy to get your feedback, feature requests, and improvements on
215 215 any of the unstable APIs!
216 216 """
217 217 with warnings.catch_warnings():
218 218 warnings.filterwarnings(action, category=ProvisionalCompleterWarning)
219 219 yield
220 220
221 221
222 222 def has_open_quotes(s):
223 223 """Return whether a string has open quotes.
224 224
225 225 This simply counts whether the number of quote characters of either type in
226 226 the string is odd.
227 227
228 228 Returns
229 229 -------
230 230 If there is an open quote, the quote character is returned. Else, return
231 231 False.
232 232 """
233 233 # We check " first, then ', so complex cases with nested quotes will get
234 234 # the " to take precedence.
235 235 if s.count('"') % 2:
236 236 return '"'
237 237 elif s.count("'") % 2:
238 238 return "'"
239 239 else:
240 240 return False
241 241
242 242
243 243 def protect_filename(s, protectables=PROTECTABLES):
244 244 """Escape a string to protect certain characters."""
245 245 if set(s) & set(protectables):
246 246 if sys.platform == "win32":
247 247 return '"' + s + '"'
248 248 else:
249 249 return "".join(("\\" + c if c in protectables else c) for c in s)
250 250 else:
251 251 return s
252 252
253 253
254 254 def expand_user(path:str) -> Tuple[str, bool, str]:
255 255 """Expand ``~``-style usernames in strings.
256 256
257 257 This is similar to :func:`os.path.expanduser`, but it computes and returns
258 258 extra information that will be useful if the input was being used in
259 259 computing completions, and you wish to return the completions with the
260 260 original '~' instead of its expanded value.
261 261
262 262 Parameters
263 263 ----------
264 264 path : str
265 265 String to be expanded. If no ~ is present, the output is the same as the
266 266 input.
267 267
268 268 Returns
269 269 -------
270 270 newpath : str
271 271 Result of ~ expansion in the input path.
272 272 tilde_expand : bool
273 273 Whether any expansion was performed or not.
274 274 tilde_val : str
275 275 The value that ~ was replaced with.
276 276 """
277 277 # Default values
278 278 tilde_expand = False
279 279 tilde_val = ''
280 280 newpath = path
281 281
282 282 if path.startswith('~'):
283 283 tilde_expand = True
284 284 rest = len(path)-1
285 285 newpath = os.path.expanduser(path)
286 286 if rest:
287 287 tilde_val = newpath[:-rest]
288 288 else:
289 289 tilde_val = newpath
290 290
291 291 return newpath, tilde_expand, tilde_val
292 292
293 293
294 294 def compress_user(path:str, tilde_expand:bool, tilde_val:str) -> str:
295 295 """Does the opposite of expand_user, with its outputs.
296 296 """
297 297 if tilde_expand:
298 298 return path.replace(tilde_val, '~')
299 299 else:
300 300 return path
301 301
302 302
303 303 def completions_sorting_key(word):
304 304 """key for sorting completions
305 305
306 306 This does several things:
307 307
308 308 - Demote any completions starting with underscores to the end
309 309 - Insert any %magic and %%cellmagic completions in the alphabetical order
310 310 by their name
311 311 """
312 312 prio1, prio2 = 0, 0
313 313
314 314 if word.startswith('__'):
315 315 prio1 = 2
316 316 elif word.startswith('_'):
317 317 prio1 = 1
318 318
319 319 if word.endswith('='):
320 320 prio1 = -1
321 321
322 322 if word.startswith('%%'):
323 323 # If there's another % in there, this is something else, so leave it alone
324 324 if not "%" in word[2:]:
325 325 word = word[2:]
326 326 prio2 = 2
327 327 elif word.startswith('%'):
328 328 if not "%" in word[1:]:
329 329 word = word[1:]
330 330 prio2 = 1
331 331
332 332 return prio1, word, prio2
333 333
334 334
335 335 class _FakeJediCompletion:
336 336 """
337 337 This is a workaround to communicate to the UI that Jedi has crashed and to
338 338 report a bug. Will be used only id :any:`IPCompleter.debug` is set to true.
339 339
340 340 Added in IPython 6.0 so should likely be removed for 7.0
341 341
342 342 """
343 343
344 344 def __init__(self, name):
345 345
346 346 self.name = name
347 347 self.complete = name
348 348 self.type = 'crashed'
349 349 self.name_with_symbols = name
350 350 self.signature = ''
351 351 self._origin = 'fake'
352 352
353 353 def __repr__(self):
354 354 return '<Fake completion object jedi has crashed>'
355 355
356 356
357 357 class Completion:
358 358 """
359 359 Completion object used and return by IPython completers.
360 360
361 361 .. warning::
362 362
363 363 Unstable
364 364
365 365 This function is unstable, API may change without warning.
366 366 It will also raise unless use in proper context manager.
367 367
368 368 This act as a middle ground :any:`Completion` object between the
369 369 :any:`jedi.api.classes.Completion` object and the Prompt Toolkit completion
370 370 object. While Jedi need a lot of information about evaluator and how the
371 371 code should be ran/inspected, PromptToolkit (and other frontend) mostly
372 372 need user facing information.
373 373
374 374 - Which range should be replaced replaced by what.
375 375 - Some metadata (like completion type), or meta information to displayed to
376 376 the use user.
377 377
378 378 For debugging purpose we can also store the origin of the completion (``jedi``,
379 379 ``IPython.python_matches``, ``IPython.magics_matches``...).
380 380 """
381 381
382 382 __slots__ = ['start', 'end', 'text', 'type', 'signature', '_origin']
383 383
384 384 def __init__(self, start: int, end: int, text: str, *, type: str=None, _origin='', signature='') -> None:
385 385 warnings.warn("``Completion`` is a provisional API (as of IPython 6.0). "
386 386 "It may change without warnings. "
387 387 "Use in corresponding context manager.",
388 388 category=ProvisionalCompleterWarning, stacklevel=2)
389 389
390 390 self.start = start
391 391 self.end = end
392 392 self.text = text
393 393 self.type = type
394 394 self.signature = signature
395 395 self._origin = _origin
396 396
397 397 def __repr__(self):
398 398 return '<Completion start=%s end=%s text=%r type=%r, signature=%r,>' % \
399 399 (self.start, self.end, self.text, self.type or '?', self.signature or '?')
400 400
401 401 def __eq__(self, other)->Bool:
402 402 """
403 403 Equality and hash do not hash the type (as some completer may not be
404 404 able to infer the type), but are use to (partially) de-duplicate
405 405 completion.
406 406
407 407 Completely de-duplicating completion is a bit tricker that just
408 408 comparing as it depends on surrounding text, which Completions are not
409 409 aware of.
410 410 """
411 411 return self.start == other.start and \
412 412 self.end == other.end and \
413 413 self.text == other.text
414 414
415 415 def __hash__(self):
416 416 return hash((self.start, self.end, self.text))
417 417
418 418
419 419 _IC = Iterable[Completion]
420 420
421 421
422 422 def _deduplicate_completions(text: str, completions: _IC)-> _IC:
423 423 """
424 424 Deduplicate a set of completions.
425 425
426 426 .. warning::
427 427
428 428 Unstable
429 429
430 430 This function is unstable, API may change without warning.
431 431
432 432 Parameters
433 433 ----------
434 434 text : str
435 435 text that should be completed.
436 436 completions : Iterator[Completion]
437 437 iterator over the completions to deduplicate
438 438
439 439 Yields
440 440 ------
441 441 `Completions` objects
442 442 Completions coming from multiple sources, may be different but end up having
443 443 the same effect when applied to ``text``. If this is the case, this will
444 444 consider completions as equal and only emit the first encountered.
445 445 Not folded in `completions()` yet for debugging purpose, and to detect when
446 446 the IPython completer does return things that Jedi does not, but should be
447 447 at some point.
448 448 """
449 449 completions = list(completions)
450 450 if not completions:
451 451 return
452 452
453 453 new_start = min(c.start for c in completions)
454 454 new_end = max(c.end for c in completions)
455 455
456 456 seen = set()
457 457 for c in completions:
458 458 new_text = text[new_start:c.start] + c.text + text[c.end:new_end]
459 459 if new_text not in seen:
460 460 yield c
461 461 seen.add(new_text)
462 462
463 463
464 464 def rectify_completions(text: str, completions: _IC, *, _debug=False)->_IC:
465 465 """
466 466 Rectify a set of completions to all have the same ``start`` and ``end``
467 467
468 468 .. warning::
469 469
470 470 Unstable
471 471
472 472 This function is unstable, API may change without warning.
473 473 It will also raise unless use in proper context manager.
474 474
475 475 Parameters
476 476 ----------
477 477 text : str
478 478 text that should be completed.
479 479 completions : Iterator[Completion]
480 480 iterator over the completions to rectify
481 481
482 482 Notes
483 483 -----
484 484 :any:`jedi.api.classes.Completion` s returned by Jedi may not have the same start and end, though
485 485 the Jupyter Protocol requires them to behave like so. This will readjust
486 486 the completion to have the same ``start`` and ``end`` by padding both
487 487 extremities with surrounding text.
488 488
489 489 During stabilisation should support a ``_debug`` option to log which
490 490 completion are return by the IPython completer and not found in Jedi in
491 491 order to make upstream bug report.
492 492 """
493 493 warnings.warn("`rectify_completions` is a provisional API (as of IPython 6.0). "
494 494 "It may change without warnings. "
495 495 "Use in corresponding context manager.",
496 496 category=ProvisionalCompleterWarning, stacklevel=2)
497 497
498 498 completions = list(completions)
499 499 if not completions:
500 500 return
501 501 starts = (c.start for c in completions)
502 502 ends = (c.end for c in completions)
503 503
504 504 new_start = min(starts)
505 505 new_end = max(ends)
506 506
507 507 seen_jedi = set()
508 508 seen_python_matches = set()
509 509 for c in completions:
510 510 new_text = text[new_start:c.start] + c.text + text[c.end:new_end]
511 511 if c._origin == 'jedi':
512 512 seen_jedi.add(new_text)
513 513 elif c._origin == 'IPCompleter.python_matches':
514 514 seen_python_matches.add(new_text)
515 515 yield Completion(new_start, new_end, new_text, type=c.type, _origin=c._origin, signature=c.signature)
516 516 diff = seen_python_matches.difference(seen_jedi)
517 517 if diff and _debug:
518 518 print('IPython.python matches have extras:', diff)
519 519
520 520
521 521 if sys.platform == 'win32':
522 522 DELIMS = ' \t\n`!@#$^&*()=+[{]}|;\'",<>?'
523 523 else:
524 524 DELIMS = ' \t\n`!@#$^&*()=+[{]}\\|;:\'",<>?'
525 525
526 526 GREEDY_DELIMS = ' =\r\n'
527 527
528 528
529 529 class CompletionSplitter(object):
530 530 """An object to split an input line in a manner similar to readline.
531 531
532 532 By having our own implementation, we can expose readline-like completion in
533 533 a uniform manner to all frontends. This object only needs to be given the
534 534 line of text to be split and the cursor position on said line, and it
535 535 returns the 'word' to be completed on at the cursor after splitting the
536 536 entire line.
537 537
538 538 What characters are used as splitting delimiters can be controlled by
539 539 setting the ``delims`` attribute (this is a property that internally
540 540 automatically builds the necessary regular expression)"""
541 541
542 542 # Private interface
543 543
544 544 # A string of delimiter characters. The default value makes sense for
545 545 # IPython's most typical usage patterns.
546 546 _delims = DELIMS
547 547
548 548 # The expression (a normal string) to be compiled into a regular expression
549 549 # for actual splitting. We store it as an attribute mostly for ease of
550 550 # debugging, since this type of code can be so tricky to debug.
551 551 _delim_expr = None
552 552
553 553 # The regular expression that does the actual splitting
554 554 _delim_re = None
555 555
556 556 def __init__(self, delims=None):
557 557 delims = CompletionSplitter._delims if delims is None else delims
558 558 self.delims = delims
559 559
560 560 @property
561 561 def delims(self):
562 562 """Return the string of delimiter characters."""
563 563 return self._delims
564 564
565 565 @delims.setter
566 566 def delims(self, delims):
567 567 """Set the delimiters for line splitting."""
568 568 expr = '[' + ''.join('\\'+ c for c in delims) + ']'
569 569 self._delim_re = re.compile(expr)
570 570 self._delims = delims
571 571 self._delim_expr = expr
572 572
573 573 def split_line(self, line, cursor_pos=None):
574 574 """Split a line of text with a cursor at the given position.
575 575 """
576 576 l = line if cursor_pos is None else line[:cursor_pos]
577 577 return self._delim_re.split(l)[-1]
578 578
579 579
580 580
581 581 class Completer(Configurable):
582 582
583 583 greedy = Bool(False,
584 584 help="""Activate greedy completion
585 585 PENDING DEPRECTION. this is now mostly taken care of with Jedi.
586 586
587 587 This will enable completion on elements of lists, results of function calls, etc.,
588 588 but can be unsafe because the code is actually evaluated on TAB.
589 589 """
590 590 ).tag(config=True)
591 591
592 592 use_jedi = Bool(default_value=JEDI_INSTALLED,
593 593 help="Experimental: Use Jedi to generate autocompletions. "
594 594 "Default to True if jedi is installed.").tag(config=True)
595 595
596 596 jedi_compute_type_timeout = Int(default_value=400,
597 597 help="""Experimental: restrict time (in milliseconds) during which Jedi can compute types.
598 598 Set to 0 to stop computing types. Non-zero value lower than 100ms may hurt
599 599 performance by preventing jedi to build its cache.
600 600 """).tag(config=True)
601 601
602 602 debug = Bool(default_value=False,
603 603 help='Enable debug for the Completer. Mostly print extra '
604 604 'information for experimental jedi integration.')\
605 605 .tag(config=True)
606 606
607 607 backslash_combining_completions = Bool(True,
608 608 help="Enable unicode completions, e.g. \\alpha<tab> . "
609 609 "Includes completion of latex commands, unicode names, and expanding "
610 610 "unicode characters back to latex commands.").tag(config=True)
611 611
612 612
613 613
614 614 def __init__(self, namespace=None, global_namespace=None, **kwargs):
615 615 """Create a new completer for the command line.
616 616
617 617 Completer(namespace=ns, global_namespace=ns2) -> completer instance.
618 618
619 619 If unspecified, the default namespace where completions are performed
620 620 is __main__ (technically, __main__.__dict__). Namespaces should be
621 621 given as dictionaries.
622 622
623 623 An optional second namespace can be given. This allows the completer
624 624 to handle cases where both the local and global scopes need to be
625 625 distinguished.
626 626 """
627 627
628 628 # Don't bind to namespace quite yet, but flag whether the user wants a
629 629 # specific namespace or to use __main__.__dict__. This will allow us
630 630 # to bind to __main__.__dict__ at completion time, not now.
631 631 if namespace is None:
632 632 self.use_main_ns = True
633 633 else:
634 634 self.use_main_ns = False
635 635 self.namespace = namespace
636 636
637 637 # The global namespace, if given, can be bound directly
638 638 if global_namespace is None:
639 639 self.global_namespace = {}
640 640 else:
641 641 self.global_namespace = global_namespace
642 642
643 643 self.custom_matchers = []
644 644
645 645 super(Completer, self).__init__(**kwargs)
646 646
647 647 def complete(self, text, state):
648 648 """Return the next possible completion for 'text'.
649 649
650 650 This is called successively with state == 0, 1, 2, ... until it
651 651 returns None. The completion should begin with 'text'.
652 652
653 653 """
654 654 if self.use_main_ns:
655 655 self.namespace = __main__.__dict__
656 656
657 657 if state == 0:
658 658 if "." in text:
659 659 self.matches = self.attr_matches(text)
660 660 else:
661 661 self.matches = self.global_matches(text)
662 662 try:
663 663 return self.matches[state]
664 664 except IndexError:
665 665 return None
666 666
667 667 def global_matches(self, text):
668 668 """Compute matches when text is a simple name.
669 669
670 670 Return a list of all keywords, built-in functions and names currently
671 671 defined in self.namespace or self.global_namespace that match.
672 672
673 673 """
674 674 matches = []
675 675 match_append = matches.append
676 676 n = len(text)
677 677 for lst in [keyword.kwlist,
678 678 builtin_mod.__dict__.keys(),
679 679 self.namespace.keys(),
680 680 self.global_namespace.keys()]:
681 681 for word in lst:
682 682 if word[:n] == text and word != "__builtins__":
683 683 match_append(word)
684 684
685 685 snake_case_re = re.compile(r"[^_]+(_[^_]+)+?\Z")
686 686 for lst in [self.namespace.keys(),
687 687 self.global_namespace.keys()]:
688 688 shortened = {"_".join([sub[0] for sub in word.split('_')]) : word
689 689 for word in lst if snake_case_re.match(word)}
690 690 for word in shortened.keys():
691 691 if word[:n] == text and word != "__builtins__":
692 692 match_append(shortened[word])
693 693 return matches
694 694
695 695 def attr_matches(self, text):
696 696 """Compute matches when text contains a dot.
697 697
698 698 Assuming the text is of the form NAME.NAME....[NAME], and is
699 699 evaluatable in self.namespace or self.global_namespace, it will be
700 700 evaluated and its attributes (as revealed by dir()) are used as
701 701 possible completions. (For class instances, class members are
702 702 also considered.)
703 703
704 704 WARNING: this can still invoke arbitrary C code, if an object
705 705 with a __getattr__ hook is evaluated.
706 706
707 707 """
708 708
709 709 # Another option, seems to work great. Catches things like ''.<tab>
710 710 m = re.match(r"(\S+(\.\w+)*)\.(\w*)$", text)
711 711
712 712 if m:
713 713 expr, attr = m.group(1, 3)
714 714 elif self.greedy:
715 715 m2 = re.match(r"(.+)\.(\w*)$", self.line_buffer)
716 716 if not m2:
717 717 return []
718 718 expr, attr = m2.group(1,2)
719 719 else:
720 720 return []
721 721
722 722 try:
723 723 obj = eval(expr, self.namespace)
724 724 except:
725 725 try:
726 726 obj = eval(expr, self.global_namespace)
727 727 except:
728 728 return []
729 729
730 730 if self.limit_to__all__ and hasattr(obj, '__all__'):
731 731 words = get__all__entries(obj)
732 732 else:
733 733 words = dir2(obj)
734 734
735 735 try:
736 736 words = generics.complete_object(obj, words)
737 737 except TryNext:
738 738 pass
739 739 except AssertionError:
740 740 raise
741 741 except Exception:
742 742 # Silence errors from completion function
743 743 #raise # dbg
744 744 pass
745 745 # Build match list to return
746 746 n = len(attr)
747 747 return [u"%s.%s" % (expr, w) for w in words if w[:n] == attr ]
748 748
749 749
750 750 def get__all__entries(obj):
751 751 """returns the strings in the __all__ attribute"""
752 752 try:
753 753 words = getattr(obj, '__all__')
754 754 except:
755 755 return []
756 756
757 757 return [w for w in words if isinstance(w, str)]
758 758
759 759
760 760 def match_dict_keys(keys: List[Union[str, bytes, Tuple[Union[str, bytes]]]], prefix: str, delims: str,
761 761 extra_prefix: Optional[Tuple[str, bytes]]=None) -> Tuple[str, int, List[str]]:
762 762 """Used by dict_key_matches, matching the prefix to a list of keys
763 763
764 764 Parameters
765 765 ----------
766 766 keys
767 767 list of keys in dictionary currently being completed.
768 768 prefix
769 769 Part of the text already typed by the user. E.g. `mydict[b'fo`
770 770 delims
771 771 String of delimiters to consider when finding the current key.
772 772 extra_prefix : optional
773 773 Part of the text already typed in multi-key index cases. E.g. for
774 774 `mydict['foo', "bar", 'b`, this would be `('foo', 'bar')`.
775 775
776 776 Returns
777 777 -------
778 778 A tuple of three elements: ``quote``, ``token_start``, ``matched``, with
779 779 ``quote`` being the quote that need to be used to close current string.
780 780 ``token_start`` the position where the replacement should start occurring,
781 781 ``matches`` a list of replacement/completion
782 782
783 783 """
784 784 prefix_tuple = extra_prefix if extra_prefix else ()
785 785 Nprefix = len(prefix_tuple)
786 786 def filter_prefix_tuple(key):
787 787 # Reject too short keys
788 788 if len(key) <= Nprefix:
789 789 return False
790 790 # Reject keys with non str/bytes in it
791 791 for k in key:
792 792 if not isinstance(k, (str, bytes)):
793 793 return False
794 794 # Reject keys that do not match the prefix
795 795 for k, pt in zip(key, prefix_tuple):
796 796 if k != pt:
797 797 return False
798 798 # All checks passed!
799 799 return True
800 800
801 801 filtered_keys:List[Union[str,bytes]] = []
802 802 def _add_to_filtered_keys(key):
803 803 if isinstance(key, (str, bytes)):
804 804 filtered_keys.append(key)
805 805
806 806 for k in keys:
807 807 if isinstance(k, tuple):
808 808 if filter_prefix_tuple(k):
809 809 _add_to_filtered_keys(k[Nprefix])
810 810 else:
811 811 _add_to_filtered_keys(k)
812 812
813 813 if not prefix:
814 814 return '', 0, [repr(k) for k in filtered_keys]
815 815 quote_match = re.search('["\']', prefix)
816 816 assert quote_match is not None # silence mypy
817 817 quote = quote_match.group()
818 818 try:
819 819 prefix_str = eval(prefix + quote, {})
820 820 except Exception:
821 821 return '', 0, []
822 822
823 823 pattern = '[^' + ''.join('\\' + c for c in delims) + ']*$'
824 824 token_match = re.search(pattern, prefix, re.UNICODE)
825 825 assert token_match is not None # silence mypy
826 826 token_start = token_match.start()
827 827 token_prefix = token_match.group()
828 828
829 829 matched:List[str] = []
830 830 for key in filtered_keys:
831 831 try:
832 832 if not key.startswith(prefix_str):
833 833 continue
834 834 except (AttributeError, TypeError, UnicodeError):
835 835 # Python 3+ TypeError on b'a'.startswith('a') or vice-versa
836 836 continue
837 837
838 838 # reformat remainder of key to begin with prefix
839 839 rem = key[len(prefix_str):]
840 840 # force repr wrapped in '
841 841 rem_repr = repr(rem + '"') if isinstance(rem, str) else repr(rem + b'"')
842 842 rem_repr = rem_repr[1 + rem_repr.index("'"):-2]
843 843 if quote == '"':
844 844 # The entered prefix is quoted with ",
845 845 # but the match is quoted with '.
846 846 # A contained " hence needs escaping for comparison:
847 847 rem_repr = rem_repr.replace('"', '\\"')
848 848
849 849 # then reinsert prefix from start of token
850 850 matched.append('%s%s' % (token_prefix, rem_repr))
851 851 return quote, token_start, matched
852 852
853 853
854 854 def cursor_to_position(text:str, line:int, column:int)->int:
855 855 """
856 856 Convert the (line,column) position of the cursor in text to an offset in a
857 857 string.
858 858
859 859 Parameters
860 860 ----------
861 861 text : str
862 862 The text in which to calculate the cursor offset
863 863 line : int
864 864 Line of the cursor; 0-indexed
865 865 column : int
866 866 Column of the cursor 0-indexed
867 867
868 868 Returns
869 869 -------
870 870 Position of the cursor in ``text``, 0-indexed.
871 871
872 872 See Also
873 873 --------
874 874 position_to_cursor : reciprocal of this function
875 875
876 876 """
877 877 lines = text.split('\n')
878 878 assert line <= len(lines), '{} <= {}'.format(str(line), str(len(lines)))
879 879
880 880 return sum(len(l) + 1 for l in lines[:line]) + column
881 881
882 882 def position_to_cursor(text:str, offset:int)->Tuple[int, int]:
883 883 """
884 884 Convert the position of the cursor in text (0 indexed) to a line
885 885 number(0-indexed) and a column number (0-indexed) pair
886 886
887 887 Position should be a valid position in ``text``.
888 888
889 889 Parameters
890 890 ----------
891 891 text : str
892 892 The text in which to calculate the cursor offset
893 893 offset : int
894 894 Position of the cursor in ``text``, 0-indexed.
895 895
896 896 Returns
897 897 -------
898 898 (line, column) : (int, int)
899 899 Line of the cursor; 0-indexed, column of the cursor 0-indexed
900 900
901 901 See Also
902 902 --------
903 903 cursor_to_position : reciprocal of this function
904 904
905 905 """
906 906
907 907 assert 0 <= offset <= len(text) , "0 <= %s <= %s" % (offset , len(text))
908 908
909 909 before = text[:offset]
910 910 blines = before.split('\n') # ! splitnes trim trailing \n
911 911 line = before.count('\n')
912 912 col = len(blines[-1])
913 913 return line, col
914 914
915 915
916 916 def _safe_isinstance(obj, module, class_name):
917 917 """Checks if obj is an instance of module.class_name if loaded
918 918 """
919 919 return (module in sys.modules and
920 920 isinstance(obj, getattr(import_module(module), class_name)))
921 921
922 922 def back_unicode_name_matches(text:str) -> Tuple[str, Sequence[str]]:
923 923 """Match Unicode characters back to Unicode name
924 924
925 925 This does ``β˜ƒ`` -> ``\\snowman``
926 926
927 927 Note that snowman is not a valid python3 combining character but will be expanded.
928 928 Though it will not recombine back to the snowman character by the completion machinery.
929 929
930 930 This will not either back-complete standard sequences like \\n, \\b ...
931 931
932 932 Returns
933 933 =======
934 934
935 935 Return a tuple with two elements:
936 936
937 937 - The Unicode character that was matched (preceded with a backslash), or
938 938 empty string,
939 939 - a sequence (of 1), name for the match Unicode character, preceded by
940 940 backslash, or empty if no match.
941 941
942 942 """
943 943 if len(text)<2:
944 944 return '', ()
945 945 maybe_slash = text[-2]
946 946 if maybe_slash != '\\':
947 947 return '', ()
948 948
949 949 char = text[-1]
950 950 # no expand on quote for completion in strings.
951 951 # nor backcomplete standard ascii keys
952 952 if char in string.ascii_letters or char in ('"',"'"):
953 953 return '', ()
954 954 try :
955 955 unic = unicodedata.name(char)
956 956 return '\\'+char,('\\'+unic,)
957 957 except KeyError:
958 958 pass
959 959 return '', ()
960 960
961 961 def back_latex_name_matches(text:str) -> Tuple[str, Sequence[str]] :
962 962 """Match latex characters back to unicode name
963 963
964 964 This does ``\\β„΅`` -> ``\\aleph``
965 965
966 966 """
967 967 if len(text)<2:
968 968 return '', ()
969 969 maybe_slash = text[-2]
970 970 if maybe_slash != '\\':
971 971 return '', ()
972 972
973 973
974 974 char = text[-1]
975 975 # no expand on quote for completion in strings.
976 976 # nor backcomplete standard ascii keys
977 977 if char in string.ascii_letters or char in ('"',"'"):
978 978 return '', ()
979 979 try :
980 980 latex = reverse_latex_symbol[char]
981 981 # '\\' replace the \ as well
982 982 return '\\'+char,[latex]
983 983 except KeyError:
984 984 pass
985 985 return '', ()
986 986
987 987
988 988 def _formatparamchildren(parameter) -> str:
989 989 """
990 990 Get parameter name and value from Jedi Private API
991 991
992 992 Jedi does not expose a simple way to get `param=value` from its API.
993 993
994 994 Parameters
995 995 ----------
996 996 parameter
997 997 Jedi's function `Param`
998 998
999 999 Returns
1000 1000 -------
1001 1001 A string like 'a', 'b=1', '*args', '**kwargs'
1002 1002
1003 1003 """
1004 1004 description = parameter.description
1005 1005 if not description.startswith('param '):
1006 1006 raise ValueError('Jedi function parameter description have change format.'
1007 1007 'Expected "param ...", found %r".' % description)
1008 1008 return description[6:]
1009 1009
1010 1010 def _make_signature(completion)-> str:
1011 1011 """
1012 1012 Make the signature from a jedi completion
1013 1013
1014 1014 Parameters
1015 1015 ----------
1016 1016 completion : jedi.Completion
1017 1017 object does not complete a function type
1018 1018
1019 1019 Returns
1020 1020 -------
1021 1021 a string consisting of the function signature, with the parenthesis but
1022 1022 without the function name. example:
1023 1023 `(a, *args, b=1, **kwargs)`
1024 1024
1025 1025 """
1026 1026
1027 1027 # it looks like this might work on jedi 0.17
1028 1028 if hasattr(completion, 'get_signatures'):
1029 1029 signatures = completion.get_signatures()
1030 1030 if not signatures:
1031 1031 return '(?)'
1032 1032
1033 1033 c0 = completion.get_signatures()[0]
1034 1034 return '('+c0.to_string().split('(', maxsplit=1)[1]
1035 1035
1036 1036 return '(%s)'% ', '.join([f for f in (_formatparamchildren(p) for signature in completion.get_signatures()
1037 1037 for p in signature.defined_names()) if f])
1038 1038
1039 1039
1040 1040 class _CompleteResult(NamedTuple):
1041 1041 matched_text : str
1042 1042 matches: Sequence[str]
1043 1043 matches_origin: Sequence[str]
1044 1044 jedi_matches: Any
1045 1045
1046 1046
1047 1047 class IPCompleter(Completer):
1048 1048 """Extension of the completer class with IPython-specific features"""
1049 1049
1050 1050 __dict_key_regexps: Optional[Dict[bool,Pattern]] = None
1051 1051
1052 1052 @observe('greedy')
1053 1053 def _greedy_changed(self, change):
1054 1054 """update the splitter and readline delims when greedy is changed"""
1055 1055 if change['new']:
1056 1056 self.splitter.delims = GREEDY_DELIMS
1057 1057 else:
1058 1058 self.splitter.delims = DELIMS
1059 1059
1060 1060 dict_keys_only = Bool(False,
1061 1061 help="""Whether to show dict key matches only""")
1062 1062
1063 1063 merge_completions = Bool(True,
1064 1064 help="""Whether to merge completion results into a single list
1065 1065
1066 1066 If False, only the completion results from the first non-empty
1067 1067 completer will be returned.
1068 1068 """
1069 1069 ).tag(config=True)
1070 1070 omit__names = Enum((0,1,2), default_value=2,
1071 1071 help="""Instruct the completer to omit private method names
1072 1072
1073 1073 Specifically, when completing on ``object.<tab>``.
1074 1074
1075 1075 When 2 [default]: all names that start with '_' will be excluded.
1076 1076
1077 1077 When 1: all 'magic' names (``__foo__``) will be excluded.
1078 1078
1079 1079 When 0: nothing will be excluded.
1080 1080 """
1081 1081 ).tag(config=True)
1082 1082 limit_to__all__ = Bool(False,
1083 1083 help="""
1084 1084 DEPRECATED as of version 5.0.
1085 1085
1086 1086 Instruct the completer to use __all__ for the completion
1087 1087
1088 1088 Specifically, when completing on ``object.<tab>``.
1089 1089
1090 1090 When True: only those names in obj.__all__ will be included.
1091 1091
1092 1092 When False [default]: the __all__ attribute is ignored
1093 1093 """,
1094 1094 ).tag(config=True)
1095 1095
1096 1096 profile_completions = Bool(
1097 1097 default_value=False,
1098 1098 help="If True, emit profiling data for completion subsystem using cProfile."
1099 1099 ).tag(config=True)
1100 1100
1101 1101 profiler_output_dir = Unicode(
1102 1102 default_value=".completion_profiles",
1103 1103 help="Template for path at which to output profile data for completions."
1104 1104 ).tag(config=True)
1105 1105
1106 1106 @observe('limit_to__all__')
1107 1107 def _limit_to_all_changed(self, change):
1108 1108 warnings.warn('`IPython.core.IPCompleter.limit_to__all__` configuration '
1109 1109 'value has been deprecated since IPython 5.0, will be made to have '
1110 1110 'no effects and then removed in future version of IPython.',
1111 1111 UserWarning)
1112 1112
1113 1113 def __init__(self, shell=None, namespace=None, global_namespace=None,
1114 1114 use_readline=_deprecation_readline_sentinel, config=None, **kwargs):
1115 1115 """IPCompleter() -> completer
1116 1116
1117 1117 Return a completer object.
1118 1118
1119 1119 Parameters
1120 1120 ----------
1121 1121 shell
1122 1122 a pointer to the ipython shell itself. This is needed
1123 1123 because this completer knows about magic functions, and those can
1124 1124 only be accessed via the ipython instance.
1125 1125 namespace : dict, optional
1126 1126 an optional dict where completions are performed.
1127 1127 global_namespace : dict, optional
1128 1128 secondary optional dict for completions, to
1129 1129 handle cases (such as IPython embedded inside functions) where
1130 1130 both Python scopes are visible.
1131 1131 use_readline : bool, optional
1132 1132 DEPRECATED, ignored since IPython 6.0, will have no effects
1133 1133 """
1134 1134
1135 1135 self.magic_escape = ESC_MAGIC
1136 1136 self.splitter = CompletionSplitter()
1137 1137
1138 1138 if use_readline is not _deprecation_readline_sentinel:
1139 1139 warnings.warn('The `use_readline` parameter is deprecated and ignored since IPython 6.0.',
1140 1140 DeprecationWarning, stacklevel=2)
1141 1141
1142 1142 # _greedy_changed() depends on splitter and readline being defined:
1143 1143 Completer.__init__(self, namespace=namespace, global_namespace=global_namespace,
1144 1144 config=config, **kwargs)
1145 1145
1146 1146 # List where completion matches will be stored
1147 1147 self.matches = []
1148 1148 self.shell = shell
1149 1149 # Regexp to split filenames with spaces in them
1150 1150 self.space_name_re = re.compile(r'([^\\] )')
1151 1151 # Hold a local ref. to glob.glob for speed
1152 1152 self.glob = glob.glob
1153 1153
1154 1154 # Determine if we are running on 'dumb' terminals, like (X)Emacs
1155 1155 # buffers, to avoid completion problems.
1156 1156 term = os.environ.get('TERM','xterm')
1157 1157 self.dumb_terminal = term in ['dumb','emacs']
1158 1158
1159 1159 # Special handling of backslashes needed in win32 platforms
1160 1160 if sys.platform == "win32":
1161 1161 self.clean_glob = self._clean_glob_win32
1162 1162 else:
1163 1163 self.clean_glob = self._clean_glob
1164 1164
1165 1165 #regexp to parse docstring for function signature
1166 1166 self.docstring_sig_re = re.compile(r'^[\w|\s.]+\(([^)]*)\).*')
1167 1167 self.docstring_kwd_re = re.compile(r'[\s|\[]*(\w+)(?:\s*=\s*.*)')
1168 1168 #use this if positional argument name is also needed
1169 1169 #= re.compile(r'[\s|\[]*(\w+)(?:\s*=?\s*.*)')
1170 1170
1171 1171 self.magic_arg_matchers = [
1172 1172 self.magic_config_matches,
1173 1173 self.magic_color_matches,
1174 1174 ]
1175 1175
1176 1176 # This is set externally by InteractiveShell
1177 1177 self.custom_completers = None
1178 1178
1179 1179 # This is a list of names of unicode characters that can be completed
1180 1180 # into their corresponding unicode value. The list is large, so we
1181 1181 # laziliy initialize it on first use. Consuming code should access this
1182 1182 # attribute through the `@unicode_names` property.
1183 1183 self._unicode_names = None
1184 1184
1185 1185 @property
1186 1186 def matchers(self) -> List[Any]:
1187 1187 """All active matcher routines for completion"""
1188 1188 if self.dict_keys_only:
1189 1189 return [self.dict_key_matches]
1190 1190
1191 1191 if self.use_jedi:
1192 1192 return [
1193 1193 *self.custom_matchers,
1194 self.dict_key_matches,
1194 1195 self.file_matches,
1195 1196 self.magic_matches,
1196 self.dict_key_matches,
1197 1197 ]
1198 1198 else:
1199 1199 return [
1200 1200 *self.custom_matchers,
1201 self.dict_key_matches,
1201 1202 self.python_matches,
1202 1203 self.file_matches,
1203 1204 self.magic_matches,
1204 1205 self.python_func_kw_matches,
1205 self.dict_key_matches,
1206 1206 ]
1207 1207
1208 1208 def all_completions(self, text:str) -> List[str]:
1209 1209 """
1210 1210 Wrapper around the completion methods for the benefit of emacs.
1211 1211 """
1212 1212 prefix = text.rpartition('.')[0]
1213 1213 with provisionalcompleter():
1214 1214 return ['.'.join([prefix, c.text]) if prefix and self.use_jedi else c.text
1215 1215 for c in self.completions(text, len(text))]
1216 1216
1217 1217 return self.complete(text)[1]
1218 1218
1219 1219 def _clean_glob(self, text:str):
1220 1220 return self.glob("%s*" % text)
1221 1221
1222 1222 def _clean_glob_win32(self, text:str):
1223 1223 return [f.replace("\\","/")
1224 1224 for f in self.glob("%s*" % text)]
1225 1225
1226 1226 def file_matches(self, text:str)->List[str]:
1227 1227 """Match filenames, expanding ~USER type strings.
1228 1228
1229 1229 Most of the seemingly convoluted logic in this completer is an
1230 1230 attempt to handle filenames with spaces in them. And yet it's not
1231 1231 quite perfect, because Python's readline doesn't expose all of the
1232 1232 GNU readline details needed for this to be done correctly.
1233 1233
1234 1234 For a filename with a space in it, the printed completions will be
1235 1235 only the parts after what's already been typed (instead of the
1236 1236 full completions, as is normally done). I don't think with the
1237 1237 current (as of Python 2.3) Python readline it's possible to do
1238 1238 better."""
1239 1239
1240 1240 # chars that require escaping with backslash - i.e. chars
1241 1241 # that readline treats incorrectly as delimiters, but we
1242 1242 # don't want to treat as delimiters in filename matching
1243 1243 # when escaped with backslash
1244 1244 if text.startswith('!'):
1245 1245 text = text[1:]
1246 1246 text_prefix = u'!'
1247 1247 else:
1248 1248 text_prefix = u''
1249 1249
1250 1250 text_until_cursor = self.text_until_cursor
1251 1251 # track strings with open quotes
1252 1252 open_quotes = has_open_quotes(text_until_cursor)
1253 1253
1254 1254 if '(' in text_until_cursor or '[' in text_until_cursor:
1255 1255 lsplit = text
1256 1256 else:
1257 1257 try:
1258 1258 # arg_split ~ shlex.split, but with unicode bugs fixed by us
1259 1259 lsplit = arg_split(text_until_cursor)[-1]
1260 1260 except ValueError:
1261 1261 # typically an unmatched ", or backslash without escaped char.
1262 1262 if open_quotes:
1263 1263 lsplit = text_until_cursor.split(open_quotes)[-1]
1264 1264 else:
1265 1265 return []
1266 1266 except IndexError:
1267 1267 # tab pressed on empty line
1268 1268 lsplit = ""
1269 1269
1270 1270 if not open_quotes and lsplit != protect_filename(lsplit):
1271 1271 # if protectables are found, do matching on the whole escaped name
1272 1272 has_protectables = True
1273 1273 text0,text = text,lsplit
1274 1274 else:
1275 1275 has_protectables = False
1276 1276 text = os.path.expanduser(text)
1277 1277
1278 1278 if text == "":
1279 1279 return [text_prefix + protect_filename(f) for f in self.glob("*")]
1280 1280
1281 1281 # Compute the matches from the filesystem
1282 1282 if sys.platform == 'win32':
1283 1283 m0 = self.clean_glob(text)
1284 1284 else:
1285 1285 m0 = self.clean_glob(text.replace('\\', ''))
1286 1286
1287 1287 if has_protectables:
1288 1288 # If we had protectables, we need to revert our changes to the
1289 1289 # beginning of filename so that we don't double-write the part
1290 1290 # of the filename we have so far
1291 1291 len_lsplit = len(lsplit)
1292 1292 matches = [text_prefix + text0 +
1293 1293 protect_filename(f[len_lsplit:]) for f in m0]
1294 1294 else:
1295 1295 if open_quotes:
1296 1296 # if we have a string with an open quote, we don't need to
1297 1297 # protect the names beyond the quote (and we _shouldn't_, as
1298 1298 # it would cause bugs when the filesystem call is made).
1299 1299 matches = m0 if sys.platform == "win32" else\
1300 1300 [protect_filename(f, open_quotes) for f in m0]
1301 1301 else:
1302 1302 matches = [text_prefix +
1303 1303 protect_filename(f) for f in m0]
1304 1304
1305 1305 # Mark directories in input list by appending '/' to their names.
1306 1306 return [x+'/' if os.path.isdir(x) else x for x in matches]
1307 1307
1308 1308 def magic_matches(self, text:str):
1309 1309 """Match magics"""
1310 1310 # Get all shell magics now rather than statically, so magics loaded at
1311 1311 # runtime show up too.
1312 1312 lsm = self.shell.magics_manager.lsmagic()
1313 1313 line_magics = lsm['line']
1314 1314 cell_magics = lsm['cell']
1315 1315 pre = self.magic_escape
1316 1316 pre2 = pre+pre
1317 1317
1318 1318 explicit_magic = text.startswith(pre)
1319 1319
1320 1320 # Completion logic:
1321 1321 # - user gives %%: only do cell magics
1322 1322 # - user gives %: do both line and cell magics
1323 1323 # - no prefix: do both
1324 1324 # In other words, line magics are skipped if the user gives %% explicitly
1325 1325 #
1326 1326 # We also exclude magics that match any currently visible names:
1327 1327 # https://github.com/ipython/ipython/issues/4877, unless the user has
1328 1328 # typed a %:
1329 1329 # https://github.com/ipython/ipython/issues/10754
1330 1330 bare_text = text.lstrip(pre)
1331 1331 global_matches = self.global_matches(bare_text)
1332 1332 if not explicit_magic:
1333 1333 def matches(magic):
1334 1334 """
1335 1335 Filter magics, in particular remove magics that match
1336 1336 a name present in global namespace.
1337 1337 """
1338 1338 return ( magic.startswith(bare_text) and
1339 1339 magic not in global_matches )
1340 1340 else:
1341 1341 def matches(magic):
1342 1342 return magic.startswith(bare_text)
1343 1343
1344 1344 comp = [ pre2+m for m in cell_magics if matches(m)]
1345 1345 if not text.startswith(pre2):
1346 1346 comp += [ pre+m for m in line_magics if matches(m)]
1347 1347
1348 1348 return comp
1349 1349
1350 1350 def magic_config_matches(self, text:str) -> List[str]:
1351 1351 """ Match class names and attributes for %config magic """
1352 1352 texts = text.strip().split()
1353 1353
1354 1354 if len(texts) > 0 and (texts[0] == 'config' or texts[0] == '%config'):
1355 1355 # get all configuration classes
1356 1356 classes = sorted(set([ c for c in self.shell.configurables
1357 1357 if c.__class__.class_traits(config=True)
1358 1358 ]), key=lambda x: x.__class__.__name__)
1359 1359 classnames = [ c.__class__.__name__ for c in classes ]
1360 1360
1361 1361 # return all classnames if config or %config is given
1362 1362 if len(texts) == 1:
1363 1363 return classnames
1364 1364
1365 1365 # match classname
1366 1366 classname_texts = texts[1].split('.')
1367 1367 classname = classname_texts[0]
1368 1368 classname_matches = [ c for c in classnames
1369 1369 if c.startswith(classname) ]
1370 1370
1371 1371 # return matched classes or the matched class with attributes
1372 1372 if texts[1].find('.') < 0:
1373 1373 return classname_matches
1374 1374 elif len(classname_matches) == 1 and \
1375 1375 classname_matches[0] == classname:
1376 1376 cls = classes[classnames.index(classname)].__class__
1377 1377 help = cls.class_get_help()
1378 1378 # strip leading '--' from cl-args:
1379 1379 help = re.sub(re.compile(r'^--', re.MULTILINE), '', help)
1380 1380 return [ attr.split('=')[0]
1381 1381 for attr in help.strip().splitlines()
1382 1382 if attr.startswith(texts[1]) ]
1383 1383 return []
1384 1384
1385 1385 def magic_color_matches(self, text:str) -> List[str] :
1386 1386 """ Match color schemes for %colors magic"""
1387 1387 texts = text.split()
1388 1388 if text.endswith(' '):
1389 1389 # .split() strips off the trailing whitespace. Add '' back
1390 1390 # so that: '%colors ' -> ['%colors', '']
1391 1391 texts.append('')
1392 1392
1393 1393 if len(texts) == 2 and (texts[0] == 'colors' or texts[0] == '%colors'):
1394 1394 prefix = texts[1]
1395 1395 return [ color for color in InspectColors.keys()
1396 1396 if color.startswith(prefix) ]
1397 1397 return []
1398 1398
1399 1399 def _jedi_matches(self, cursor_column:int, cursor_line:int, text:str) -> Iterable[Any]:
1400 1400 """
1401 1401 Return a list of :any:`jedi.api.Completions` object from a ``text`` and
1402 1402 cursor position.
1403 1403
1404 1404 Parameters
1405 1405 ----------
1406 1406 cursor_column : int
1407 1407 column position of the cursor in ``text``, 0-indexed.
1408 1408 cursor_line : int
1409 1409 line position of the cursor in ``text``, 0-indexed
1410 1410 text : str
1411 1411 text to complete
1412 1412
1413 1413 Notes
1414 1414 -----
1415 1415 If ``IPCompleter.debug`` is ``True`` may return a :any:`_FakeJediCompletion`
1416 1416 object containing a string with the Jedi debug information attached.
1417 1417 """
1418 1418 namespaces = [self.namespace]
1419 1419 if self.global_namespace is not None:
1420 1420 namespaces.append(self.global_namespace)
1421 1421
1422 1422 completion_filter = lambda x:x
1423 1423 offset = cursor_to_position(text, cursor_line, cursor_column)
1424 1424 # filter output if we are completing for object members
1425 1425 if offset:
1426 1426 pre = text[offset-1]
1427 1427 if pre == '.':
1428 1428 if self.omit__names == 2:
1429 1429 completion_filter = lambda c:not c.name.startswith('_')
1430 1430 elif self.omit__names == 1:
1431 1431 completion_filter = lambda c:not (c.name.startswith('__') and c.name.endswith('__'))
1432 1432 elif self.omit__names == 0:
1433 1433 completion_filter = lambda x:x
1434 1434 else:
1435 1435 raise ValueError("Don't understand self.omit__names == {}".format(self.omit__names))
1436 1436
1437 1437 interpreter = jedi.Interpreter(text[:offset], namespaces)
1438 1438 try_jedi = True
1439 1439
1440 1440 try:
1441 1441 # find the first token in the current tree -- if it is a ' or " then we are in a string
1442 1442 completing_string = False
1443 1443 try:
1444 1444 first_child = next(c for c in interpreter._get_module().tree_node.children if hasattr(c, 'value'))
1445 1445 except StopIteration:
1446 1446 pass
1447 1447 else:
1448 1448 # note the value may be ', ", or it may also be ''' or """, or
1449 1449 # in some cases, """what/you/typed..., but all of these are
1450 1450 # strings.
1451 1451 completing_string = len(first_child.value) > 0 and first_child.value[0] in {"'", '"'}
1452 1452
1453 1453 # if we are in a string jedi is likely not the right candidate for
1454 1454 # now. Skip it.
1455 1455 try_jedi = not completing_string
1456 1456 except Exception as e:
1457 1457 # many of things can go wrong, we are using private API just don't crash.
1458 1458 if self.debug:
1459 1459 print("Error detecting if completing a non-finished string :", e, '|')
1460 1460
1461 1461 if not try_jedi:
1462 1462 return []
1463 1463 try:
1464 1464 return filter(completion_filter, interpreter.complete(column=cursor_column, line=cursor_line + 1))
1465 1465 except Exception as e:
1466 1466 if self.debug:
1467 1467 return [_FakeJediCompletion('Oops Jedi has crashed, please report a bug with the following:\n"""\n%s\ns"""' % (e))]
1468 1468 else:
1469 1469 return []
1470 1470
1471 1471 def python_matches(self, text:str)->List[str]:
1472 1472 """Match attributes or global python names"""
1473 1473 if "." in text:
1474 1474 try:
1475 1475 matches = self.attr_matches(text)
1476 1476 if text.endswith('.') and self.omit__names:
1477 1477 if self.omit__names == 1:
1478 1478 # true if txt is _not_ a __ name, false otherwise:
1479 1479 no__name = (lambda txt:
1480 1480 re.match(r'.*\.__.*?__',txt) is None)
1481 1481 else:
1482 1482 # true if txt is _not_ a _ name, false otherwise:
1483 1483 no__name = (lambda txt:
1484 1484 re.match(r'\._.*?',txt[txt.rindex('.'):]) is None)
1485 1485 matches = filter(no__name, matches)
1486 1486 except NameError:
1487 1487 # catches <undefined attributes>.<tab>
1488 1488 matches = []
1489 1489 else:
1490 1490 matches = self.global_matches(text)
1491 1491 return matches
1492 1492
1493 1493 def _default_arguments_from_docstring(self, doc):
1494 1494 """Parse the first line of docstring for call signature.
1495 1495
1496 1496 Docstring should be of the form 'min(iterable[, key=func])\n'.
1497 1497 It can also parse cython docstring of the form
1498 1498 'Minuit.migrad(self, int ncall=10000, resume=True, int nsplit=1)'.
1499 1499 """
1500 1500 if doc is None:
1501 1501 return []
1502 1502
1503 1503 #care only the firstline
1504 1504 line = doc.lstrip().splitlines()[0]
1505 1505
1506 1506 #p = re.compile(r'^[\w|\s.]+\(([^)]*)\).*')
1507 1507 #'min(iterable[, key=func])\n' -> 'iterable[, key=func]'
1508 1508 sig = self.docstring_sig_re.search(line)
1509 1509 if sig is None:
1510 1510 return []
1511 1511 # iterable[, key=func]' -> ['iterable[' ,' key=func]']
1512 1512 sig = sig.groups()[0].split(',')
1513 1513 ret = []
1514 1514 for s in sig:
1515 1515 #re.compile(r'[\s|\[]*(\w+)(?:\s*=\s*.*)')
1516 1516 ret += self.docstring_kwd_re.findall(s)
1517 1517 return ret
1518 1518
1519 1519 def _default_arguments(self, obj):
1520 1520 """Return the list of default arguments of obj if it is callable,
1521 1521 or empty list otherwise."""
1522 1522 call_obj = obj
1523 1523 ret = []
1524 1524 if inspect.isbuiltin(obj):
1525 1525 pass
1526 1526 elif not (inspect.isfunction(obj) or inspect.ismethod(obj)):
1527 1527 if inspect.isclass(obj):
1528 1528 #for cython embedsignature=True the constructor docstring
1529 1529 #belongs to the object itself not __init__
1530 1530 ret += self._default_arguments_from_docstring(
1531 1531 getattr(obj, '__doc__', ''))
1532 1532 # for classes, check for __init__,__new__
1533 1533 call_obj = (getattr(obj, '__init__', None) or
1534 1534 getattr(obj, '__new__', None))
1535 1535 # for all others, check if they are __call__able
1536 1536 elif hasattr(obj, '__call__'):
1537 1537 call_obj = obj.__call__
1538 1538 ret += self._default_arguments_from_docstring(
1539 1539 getattr(call_obj, '__doc__', ''))
1540 1540
1541 1541 _keeps = (inspect.Parameter.KEYWORD_ONLY,
1542 1542 inspect.Parameter.POSITIONAL_OR_KEYWORD)
1543 1543
1544 1544 try:
1545 1545 sig = inspect.signature(obj)
1546 1546 ret.extend(k for k, v in sig.parameters.items() if
1547 1547 v.kind in _keeps)
1548 1548 except ValueError:
1549 1549 pass
1550 1550
1551 1551 return list(set(ret))
1552 1552
1553 1553 def python_func_kw_matches(self, text):
1554 1554 """Match named parameters (kwargs) of the last open function"""
1555 1555
1556 1556 if "." in text: # a parameter cannot be dotted
1557 1557 return []
1558 1558 try: regexp = self.__funcParamsRegex
1559 1559 except AttributeError:
1560 1560 regexp = self.__funcParamsRegex = re.compile(r'''
1561 1561 '.*?(?<!\\)' | # single quoted strings or
1562 1562 ".*?(?<!\\)" | # double quoted strings or
1563 1563 \w+ | # identifier
1564 1564 \S # other characters
1565 1565 ''', re.VERBOSE | re.DOTALL)
1566 1566 # 1. find the nearest identifier that comes before an unclosed
1567 1567 # parenthesis before the cursor
1568 1568 # e.g. for "foo (1+bar(x), pa<cursor>,a=1)", the candidate is "foo"
1569 1569 tokens = regexp.findall(self.text_until_cursor)
1570 1570 iterTokens = reversed(tokens); openPar = 0
1571 1571
1572 1572 for token in iterTokens:
1573 1573 if token == ')':
1574 1574 openPar -= 1
1575 1575 elif token == '(':
1576 1576 openPar += 1
1577 1577 if openPar > 0:
1578 1578 # found the last unclosed parenthesis
1579 1579 break
1580 1580 else:
1581 1581 return []
1582 1582 # 2. Concatenate dotted names ("foo.bar" for "foo.bar(x, pa" )
1583 1583 ids = []
1584 1584 isId = re.compile(r'\w+$').match
1585 1585
1586 1586 while True:
1587 1587 try:
1588 1588 ids.append(next(iterTokens))
1589 1589 if not isId(ids[-1]):
1590 1590 ids.pop(); break
1591 1591 if not next(iterTokens) == '.':
1592 1592 break
1593 1593 except StopIteration:
1594 1594 break
1595 1595
1596 1596 # Find all named arguments already assigned to, as to avoid suggesting
1597 1597 # them again
1598 1598 usedNamedArgs = set()
1599 1599 par_level = -1
1600 1600 for token, next_token in zip(tokens, tokens[1:]):
1601 1601 if token == '(':
1602 1602 par_level += 1
1603 1603 elif token == ')':
1604 1604 par_level -= 1
1605 1605
1606 1606 if par_level != 0:
1607 1607 continue
1608 1608
1609 1609 if next_token != '=':
1610 1610 continue
1611 1611
1612 1612 usedNamedArgs.add(token)
1613 1613
1614 1614 argMatches = []
1615 1615 try:
1616 1616 callableObj = '.'.join(ids[::-1])
1617 1617 namedArgs = self._default_arguments(eval(callableObj,
1618 1618 self.namespace))
1619 1619
1620 1620 # Remove used named arguments from the list, no need to show twice
1621 1621 for namedArg in set(namedArgs) - usedNamedArgs:
1622 1622 if namedArg.startswith(text):
1623 1623 argMatches.append("%s=" %namedArg)
1624 1624 except:
1625 1625 pass
1626 1626
1627 1627 return argMatches
1628 1628
1629 1629 @staticmethod
1630 1630 def _get_keys(obj: Any) -> List[Any]:
1631 1631 # Objects can define their own completions by defining an
1632 1632 # _ipy_key_completions_() method.
1633 1633 method = get_real_method(obj, '_ipython_key_completions_')
1634 1634 if method is not None:
1635 1635 return method()
1636 1636
1637 1637 # Special case some common in-memory dict-like types
1638 1638 if isinstance(obj, dict) or\
1639 1639 _safe_isinstance(obj, 'pandas', 'DataFrame'):
1640 1640 try:
1641 1641 return list(obj.keys())
1642 1642 except Exception:
1643 1643 return []
1644 1644 elif _safe_isinstance(obj, 'numpy', 'ndarray') or\
1645 1645 _safe_isinstance(obj, 'numpy', 'void'):
1646 1646 return obj.dtype.names or []
1647 1647 return []
1648 1648
1649 1649 def dict_key_matches(self, text:str) -> List[str]:
1650 1650 "Match string keys in a dictionary, after e.g. 'foo[' "
1651 1651
1652 1652
1653 1653 if self.__dict_key_regexps is not None:
1654 1654 regexps = self.__dict_key_regexps
1655 1655 else:
1656 1656 dict_key_re_fmt = r'''(?x)
1657 1657 ( # match dict-referring expression wrt greedy setting
1658 1658 %s
1659 1659 )
1660 1660 \[ # open bracket
1661 1661 \s* # and optional whitespace
1662 1662 # Capture any number of str-like objects (e.g. "a", "b", 'c')
1663 1663 ((?:[uUbB]? # string prefix (r not handled)
1664 1664 (?:
1665 1665 '(?:[^']|(?<!\\)\\')*'
1666 1666 |
1667 1667 "(?:[^"]|(?<!\\)\\")*"
1668 1668 )
1669 1669 \s*,\s*
1670 1670 )*)
1671 1671 ([uUbB]? # string prefix (r not handled)
1672 1672 (?: # unclosed string
1673 1673 '(?:[^']|(?<!\\)\\')*
1674 1674 |
1675 1675 "(?:[^"]|(?<!\\)\\")*
1676 1676 )
1677 1677 )?
1678 1678 $
1679 1679 '''
1680 1680 regexps = self.__dict_key_regexps = {
1681 1681 False: re.compile(dict_key_re_fmt % r'''
1682 1682 # identifiers separated by .
1683 1683 (?!\d)\w+
1684 1684 (?:\.(?!\d)\w+)*
1685 1685 '''),
1686 1686 True: re.compile(dict_key_re_fmt % '''
1687 1687 .+
1688 1688 ''')
1689 1689 }
1690 1690
1691 1691 match = regexps[self.greedy].search(self.text_until_cursor)
1692 1692
1693 1693 if match is None:
1694 1694 return []
1695 1695
1696 1696 expr, prefix0, prefix = match.groups()
1697 1697 try:
1698 1698 obj = eval(expr, self.namespace)
1699 1699 except Exception:
1700 1700 try:
1701 1701 obj = eval(expr, self.global_namespace)
1702 1702 except Exception:
1703 1703 return []
1704 1704
1705 1705 keys = self._get_keys(obj)
1706 1706 if not keys:
1707 1707 return keys
1708 1708
1709 1709 extra_prefix = eval(prefix0) if prefix0 != '' else None
1710 1710
1711 1711 closing_quote, token_offset, matches = match_dict_keys(keys, prefix, self.splitter.delims, extra_prefix=extra_prefix)
1712 1712 if not matches:
1713 1713 return matches
1714 1714
1715 1715 # get the cursor position of
1716 1716 # - the text being completed
1717 1717 # - the start of the key text
1718 1718 # - the start of the completion
1719 1719 text_start = len(self.text_until_cursor) - len(text)
1720 1720 if prefix:
1721 1721 key_start = match.start(3)
1722 1722 completion_start = key_start + token_offset
1723 1723 else:
1724 1724 key_start = completion_start = match.end()
1725 1725
1726 1726 # grab the leading prefix, to make sure all completions start with `text`
1727 1727 if text_start > key_start:
1728 1728 leading = ''
1729 1729 else:
1730 1730 leading = text[text_start:completion_start]
1731 1731
1732 1732 # the index of the `[` character
1733 1733 bracket_idx = match.end(1)
1734 1734
1735 1735 # append closing quote and bracket as appropriate
1736 1736 # this is *not* appropriate if the opening quote or bracket is outside
1737 1737 # the text given to this method
1738 1738 suf = ''
1739 1739 continuation = self.line_buffer[len(self.text_until_cursor):]
1740 1740 if key_start > text_start and closing_quote:
1741 1741 # quotes were opened inside text, maybe close them
1742 1742 if continuation.startswith(closing_quote):
1743 1743 continuation = continuation[len(closing_quote):]
1744 1744 else:
1745 1745 suf += closing_quote
1746 1746 if bracket_idx > text_start:
1747 1747 # brackets were opened inside text, maybe close them
1748 1748 if not continuation.startswith(']'):
1749 1749 suf += ']'
1750 1750
1751 1751 return [leading + k + suf for k in matches]
1752 1752
1753 1753 @staticmethod
1754 1754 def unicode_name_matches(text:str) -> Tuple[str, List[str]] :
1755 1755 """Match Latex-like syntax for unicode characters base
1756 1756 on the name of the character.
1757 1757
1758 1758 This does ``\\GREEK SMALL LETTER ETA`` -> ``Ξ·``
1759 1759
1760 1760 Works only on valid python 3 identifier, or on combining characters that
1761 1761 will combine to form a valid identifier.
1762 1762 """
1763 1763 slashpos = text.rfind('\\')
1764 1764 if slashpos > -1:
1765 1765 s = text[slashpos+1:]
1766 1766 try :
1767 1767 unic = unicodedata.lookup(s)
1768 1768 # allow combining chars
1769 1769 if ('a'+unic).isidentifier():
1770 1770 return '\\'+s,[unic]
1771 1771 except KeyError:
1772 1772 pass
1773 1773 return '', []
1774 1774
1775 1775
1776 1776 def latex_matches(self, text:str) -> Tuple[str, Sequence[str]]:
1777 1777 """Match Latex syntax for unicode characters.
1778 1778
1779 1779 This does both ``\\alp`` -> ``\\alpha`` and ``\\alpha`` -> ``Ξ±``
1780 1780 """
1781 1781 slashpos = text.rfind('\\')
1782 1782 if slashpos > -1:
1783 1783 s = text[slashpos:]
1784 1784 if s in latex_symbols:
1785 1785 # Try to complete a full latex symbol to unicode
1786 1786 # \\alpha -> Ξ±
1787 1787 return s, [latex_symbols[s]]
1788 1788 else:
1789 1789 # If a user has partially typed a latex symbol, give them
1790 1790 # a full list of options \al -> [\aleph, \alpha]
1791 1791 matches = [k for k in latex_symbols if k.startswith(s)]
1792 1792 if matches:
1793 1793 return s, matches
1794 1794 return '', ()
1795 1795
1796 1796 def dispatch_custom_completer(self, text):
1797 1797 if not self.custom_completers:
1798 1798 return
1799 1799
1800 1800 line = self.line_buffer
1801 1801 if not line.strip():
1802 1802 return None
1803 1803
1804 1804 # Create a little structure to pass all the relevant information about
1805 1805 # the current completion to any custom completer.
1806 1806 event = SimpleNamespace()
1807 1807 event.line = line
1808 1808 event.symbol = text
1809 1809 cmd = line.split(None,1)[0]
1810 1810 event.command = cmd
1811 1811 event.text_until_cursor = self.text_until_cursor
1812 1812
1813 1813 # for foo etc, try also to find completer for %foo
1814 1814 if not cmd.startswith(self.magic_escape):
1815 1815 try_magic = self.custom_completers.s_matches(
1816 1816 self.magic_escape + cmd)
1817 1817 else:
1818 1818 try_magic = []
1819 1819
1820 1820 for c in itertools.chain(self.custom_completers.s_matches(cmd),
1821 1821 try_magic,
1822 1822 self.custom_completers.flat_matches(self.text_until_cursor)):
1823 1823 try:
1824 1824 res = c(event)
1825 1825 if res:
1826 1826 # first, try case sensitive match
1827 1827 withcase = [r for r in res if r.startswith(text)]
1828 1828 if withcase:
1829 1829 return withcase
1830 1830 # if none, then case insensitive ones are ok too
1831 1831 text_low = text.lower()
1832 1832 return [r for r in res if r.lower().startswith(text_low)]
1833 1833 except TryNext:
1834 1834 pass
1835 1835 except KeyboardInterrupt:
1836 1836 """
1837 1837 If custom completer take too long,
1838 1838 let keyboard interrupt abort and return nothing.
1839 1839 """
1840 1840 break
1841 1841
1842 1842 return None
1843 1843
1844 1844 def completions(self, text: str, offset: int)->Iterator[Completion]:
1845 1845 """
1846 1846 Returns an iterator over the possible completions
1847 1847
1848 1848 .. warning::
1849 1849
1850 1850 Unstable
1851 1851
1852 1852 This function is unstable, API may change without warning.
1853 1853 It will also raise unless use in proper context manager.
1854 1854
1855 1855 Parameters
1856 1856 ----------
1857 1857 text : str
1858 1858 Full text of the current input, multi line string.
1859 1859 offset : int
1860 1860 Integer representing the position of the cursor in ``text``. Offset
1861 1861 is 0-based indexed.
1862 1862
1863 1863 Yields
1864 1864 ------
1865 1865 Completion
1866 1866
1867 1867 Notes
1868 1868 -----
1869 1869 The cursor on a text can either be seen as being "in between"
1870 1870 characters or "On" a character depending on the interface visible to
1871 1871 the user. For consistency the cursor being on "in between" characters X
1872 1872 and Y is equivalent to the cursor being "on" character Y, that is to say
1873 1873 the character the cursor is on is considered as being after the cursor.
1874 1874
1875 1875 Combining characters may span more that one position in the
1876 1876 text.
1877 1877
1878 1878 .. note::
1879 1879
1880 1880 If ``IPCompleter.debug`` is :any:`True` will yield a ``--jedi/ipython--``
1881 1881 fake Completion token to distinguish completion returned by Jedi
1882 1882 and usual IPython completion.
1883 1883
1884 1884 .. note::
1885 1885
1886 1886 Completions are not completely deduplicated yet. If identical
1887 1887 completions are coming from different sources this function does not
1888 1888 ensure that each completion object will only be present once.
1889 1889 """
1890 1890 warnings.warn("_complete is a provisional API (as of IPython 6.0). "
1891 1891 "It may change without warnings. "
1892 1892 "Use in corresponding context manager.",
1893 1893 category=ProvisionalCompleterWarning, stacklevel=2)
1894 1894
1895 1895 seen = set()
1896 1896 profiler:Optional[cProfile.Profile]
1897 1897 try:
1898 1898 if self.profile_completions:
1899 1899 import cProfile
1900 1900 profiler = cProfile.Profile()
1901 1901 profiler.enable()
1902 1902 else:
1903 1903 profiler = None
1904 1904
1905 1905 for c in self._completions(text, offset, _timeout=self.jedi_compute_type_timeout/1000):
1906 1906 if c and (c in seen):
1907 1907 continue
1908 1908 yield c
1909 1909 seen.add(c)
1910 1910 except KeyboardInterrupt:
1911 1911 """if completions take too long and users send keyboard interrupt,
1912 1912 do not crash and return ASAP. """
1913 1913 pass
1914 1914 finally:
1915 1915 if profiler is not None:
1916 1916 profiler.disable()
1917 1917 ensure_dir_exists(self.profiler_output_dir)
1918 1918 output_path = os.path.join(self.profiler_output_dir, str(uuid.uuid4()))
1919 1919 print("Writing profiler output to", output_path)
1920 1920 profiler.dump_stats(output_path)
1921 1921
1922 1922 def _completions(self, full_text: str, offset: int, *, _timeout) -> Iterator[Completion]:
1923 1923 """
1924 1924 Core completion module.Same signature as :any:`completions`, with the
1925 1925 extra `timeout` parameter (in seconds).
1926 1926
1927 1927 Computing jedi's completion ``.type`` can be quite expensive (it is a
1928 1928 lazy property) and can require some warm-up, more warm up than just
1929 1929 computing the ``name`` of a completion. The warm-up can be :
1930 1930
1931 1931 - Long warm-up the first time a module is encountered after
1932 1932 install/update: actually build parse/inference tree.
1933 1933
1934 1934 - first time the module is encountered in a session: load tree from
1935 1935 disk.
1936 1936
1937 1937 We don't want to block completions for tens of seconds so we give the
1938 1938 completer a "budget" of ``_timeout`` seconds per invocation to compute
1939 1939 completions types, the completions that have not yet been computed will
1940 1940 be marked as "unknown" an will have a chance to be computed next round
1941 1941 are things get cached.
1942 1942
1943 1943 Keep in mind that Jedi is not the only thing treating the completion so
1944 1944 keep the timeout short-ish as if we take more than 0.3 second we still
1945 1945 have lots of processing to do.
1946 1946
1947 1947 """
1948 1948 deadline = time.monotonic() + _timeout
1949 1949
1950 1950
1951 1951 before = full_text[:offset]
1952 1952 cursor_line, cursor_column = position_to_cursor(full_text, offset)
1953 1953
1954 1954 matched_text, matches, matches_origin, jedi_matches = self._complete(
1955 1955 full_text=full_text, cursor_line=cursor_line, cursor_pos=cursor_column)
1956 1956
1957 1957 iter_jm = iter(jedi_matches)
1958 1958 if _timeout:
1959 1959 for jm in iter_jm:
1960 1960 try:
1961 1961 type_ = jm.type
1962 1962 except Exception:
1963 1963 if self.debug:
1964 1964 print("Error in Jedi getting type of ", jm)
1965 1965 type_ = None
1966 1966 delta = len(jm.name_with_symbols) - len(jm.complete)
1967 1967 if type_ == 'function':
1968 1968 signature = _make_signature(jm)
1969 1969 else:
1970 1970 signature = ''
1971 1971 yield Completion(start=offset - delta,
1972 1972 end=offset,
1973 1973 text=jm.name_with_symbols,
1974 1974 type=type_,
1975 1975 signature=signature,
1976 1976 _origin='jedi')
1977 1977
1978 1978 if time.monotonic() > deadline:
1979 1979 break
1980 1980
1981 1981 for jm in iter_jm:
1982 1982 delta = len(jm.name_with_symbols) - len(jm.complete)
1983 1983 yield Completion(start=offset - delta,
1984 1984 end=offset,
1985 1985 text=jm.name_with_symbols,
1986 1986 type='<unknown>', # don't compute type for speed
1987 1987 _origin='jedi',
1988 1988 signature='')
1989 1989
1990 1990
1991 1991 start_offset = before.rfind(matched_text)
1992 1992
1993 1993 # TODO:
1994 1994 # Suppress this, right now just for debug.
1995 1995 if jedi_matches and matches and self.debug:
1996 1996 yield Completion(start=start_offset, end=offset, text='--jedi/ipython--',
1997 1997 _origin='debug', type='none', signature='')
1998 1998
1999 1999 # I'm unsure if this is always true, so let's assert and see if it
2000 2000 # crash
2001 2001 assert before.endswith(matched_text)
2002 2002 for m, t in zip(matches, matches_origin):
2003 2003 yield Completion(start=start_offset, end=offset, text=m, _origin=t, signature='', type='<unknown>')
2004 2004
2005 2005
2006 2006 def complete(self, text=None, line_buffer=None, cursor_pos=None) -> Tuple[str, Sequence[str]]:
2007 2007 """Find completions for the given text and line context.
2008 2008
2009 2009 Note that both the text and the line_buffer are optional, but at least
2010 2010 one of them must be given.
2011 2011
2012 2012 Parameters
2013 2013 ----------
2014 2014 text : string, optional
2015 2015 Text to perform the completion on. If not given, the line buffer
2016 2016 is split using the instance's CompletionSplitter object.
2017 2017 line_buffer : string, optional
2018 2018 If not given, the completer attempts to obtain the current line
2019 2019 buffer via readline. This keyword allows clients which are
2020 2020 requesting for text completions in non-readline contexts to inform
2021 2021 the completer of the entire text.
2022 2022 cursor_pos : int, optional
2023 2023 Index of the cursor in the full line buffer. Should be provided by
2024 2024 remote frontends where kernel has no access to frontend state.
2025 2025
2026 2026 Returns
2027 2027 -------
2028 2028 Tuple of two items:
2029 2029 text : str
2030 2030 Text that was actually used in the completion.
2031 2031 matches : list
2032 2032 A list of completion matches.
2033 2033
2034 2034 Notes
2035 2035 -----
2036 2036 This API is likely to be deprecated and replaced by
2037 2037 :any:`IPCompleter.completions` in the future.
2038 2038
2039 2039 """
2040 2040 warnings.warn('`Completer.complete` is pending deprecation since '
2041 2041 'IPython 6.0 and will be replaced by `Completer.completions`.',
2042 2042 PendingDeprecationWarning)
2043 2043 # potential todo, FOLD the 3rd throw away argument of _complete
2044 2044 # into the first 2 one.
2045 2045 return self._complete(line_buffer=line_buffer, cursor_pos=cursor_pos, text=text, cursor_line=0)[:2]
2046 2046
2047 2047 def _complete(self, *, cursor_line, cursor_pos, line_buffer=None, text=None,
2048 2048 full_text=None) -> _CompleteResult:
2049 2049 """
2050 2050 Like complete but can also returns raw jedi completions as well as the
2051 2051 origin of the completion text. This could (and should) be made much
2052 2052 cleaner but that will be simpler once we drop the old (and stateful)
2053 2053 :any:`complete` API.
2054 2054
2055 2055 With current provisional API, cursor_pos act both (depending on the
2056 2056 caller) as the offset in the ``text`` or ``line_buffer``, or as the
2057 2057 ``column`` when passing multiline strings this could/should be renamed
2058 2058 but would add extra noise.
2059 2059
2060 2060 Parameters
2061 2061 ----------
2062 2062 cursor_line :
2063 2063 Index of the line the cursor is on. 0 indexed.
2064 2064 cursor_pos :
2065 2065 Position of the cursor in the current line/line_buffer/text. 0
2066 2066 indexed.
2067 2067 line_buffer : optional, str
2068 2068 The current line the cursor is in, this is mostly due to legacy
2069 2069 reason that readline coudl only give a us the single current line.
2070 2070 Prefer `full_text`.
2071 2071 text : str
2072 2072 The current "token" the cursor is in, mostly also for historical
2073 2073 reasons. as the completer would trigger only after the current line
2074 2074 was parsed.
2075 2075 full_text : str
2076 2076 Full text of the current cell.
2077 2077
2078 2078 Returns
2079 2079 -------
2080 2080 A tuple of N elements which are (likely):
2081 2081 matched_text: ? the text that the complete matched
2082 2082 matches: list of completions ?
2083 2083 matches_origin: ? list same length as matches, and where each completion came from
2084 2084 jedi_matches: list of Jedi matches, have it's own structure.
2085 2085 """
2086 2086
2087 2087
2088 2088 # if the cursor position isn't given, the only sane assumption we can
2089 2089 # make is that it's at the end of the line (the common case)
2090 2090 if cursor_pos is None:
2091 2091 cursor_pos = len(line_buffer) if text is None else len(text)
2092 2092
2093 2093 if self.use_main_ns:
2094 2094 self.namespace = __main__.__dict__
2095 2095
2096 2096 # if text is either None or an empty string, rely on the line buffer
2097 2097 if (not line_buffer) and full_text:
2098 2098 line_buffer = full_text.split('\n')[cursor_line]
2099 2099 if not text: # issue #11508: check line_buffer before calling split_line
2100 2100 text = self.splitter.split_line(line_buffer, cursor_pos) if line_buffer else ''
2101 2101
2102 2102 if self.backslash_combining_completions:
2103 2103 # allow deactivation of these on windows.
2104 2104 base_text = text if not line_buffer else line_buffer[:cursor_pos]
2105 2105
2106 2106 for meth in (self.latex_matches,
2107 2107 self.unicode_name_matches,
2108 2108 back_latex_name_matches,
2109 2109 back_unicode_name_matches,
2110 2110 self.fwd_unicode_match):
2111 2111 name_text, name_matches = meth(base_text)
2112 2112 if name_text:
2113 2113 return _CompleteResult(name_text, name_matches[:MATCHES_LIMIT], \
2114 2114 [meth.__qualname__]*min(len(name_matches), MATCHES_LIMIT), ())
2115 2115
2116 2116
2117 2117 # If no line buffer is given, assume the input text is all there was
2118 2118 if line_buffer is None:
2119 2119 line_buffer = text
2120 2120
2121 2121 self.line_buffer = line_buffer
2122 2122 self.text_until_cursor = self.line_buffer[:cursor_pos]
2123 2123
2124 2124 # Do magic arg matches
2125 2125 for matcher in self.magic_arg_matchers:
2126 2126 matches = list(matcher(line_buffer))[:MATCHES_LIMIT]
2127 2127 if matches:
2128 2128 origins = [matcher.__qualname__] * len(matches)
2129 2129 return _CompleteResult(text, matches, origins, ())
2130 2130
2131 2131 # Start with a clean slate of completions
2132 2132 matches = []
2133 2133
2134 2134 # FIXME: we should extend our api to return a dict with completions for
2135 2135 # different types of objects. The rlcomplete() method could then
2136 2136 # simply collapse the dict into a list for readline, but we'd have
2137 2137 # richer completion semantics in other environments.
2138 2138 completions:Iterable[Any] = []
2139 2139 if self.use_jedi:
2140 2140 if not full_text:
2141 2141 full_text = line_buffer
2142 2142 completions = self._jedi_matches(
2143 2143 cursor_pos, cursor_line, full_text)
2144 2144
2145 2145 if self.merge_completions:
2146 2146 matches = []
2147 2147 for matcher in self.matchers:
2148 2148 try:
2149 2149 matches.extend([(m, matcher.__qualname__)
2150 2150 for m in matcher(text)])
2151 2151 except:
2152 2152 # Show the ugly traceback if the matcher causes an
2153 2153 # exception, but do NOT crash the kernel!
2154 2154 sys.excepthook(*sys.exc_info())
2155 2155 else:
2156 2156 for matcher in self.matchers:
2157 2157 matches = [(m, matcher.__qualname__)
2158 2158 for m in matcher(text)]
2159 2159 if matches:
2160 2160 break
2161 2161
2162 2162 seen = set()
2163 2163 filtered_matches = set()
2164 2164 for m in matches:
2165 2165 t, c = m
2166 2166 if t not in seen:
2167 2167 filtered_matches.add(m)
2168 2168 seen.add(t)
2169 2169
2170 2170 _filtered_matches = sorted(filtered_matches, key=lambda x: completions_sorting_key(x[0]))
2171 2171
2172 2172 custom_res = [(m, 'custom') for m in self.dispatch_custom_completer(text) or []]
2173 2173
2174 2174 _filtered_matches = custom_res or _filtered_matches
2175 2175
2176 2176 _filtered_matches = _filtered_matches[:MATCHES_LIMIT]
2177 2177 _matches = [m[0] for m in _filtered_matches]
2178 2178 origins = [m[1] for m in _filtered_matches]
2179 2179
2180 2180 self.matches = _matches
2181 2181
2182 2182 return _CompleteResult(text, _matches, origins, completions)
2183 2183
2184 2184 def fwd_unicode_match(self, text:str) -> Tuple[str, Sequence[str]]:
2185 2185 """
2186 2186 Forward match a string starting with a backslash with a list of
2187 2187 potential Unicode completions.
2188 2188
2189 2189 Will compute list list of Unicode character names on first call and cache it.
2190 2190
2191 2191 Returns
2192 2192 -------
2193 2193 At tuple with:
2194 2194 - matched text (empty if no matches)
2195 2195 - list of potential completions, empty tuple otherwise)
2196 2196 """
2197 2197 # TODO: self.unicode_names is here a list we traverse each time with ~100k elements.
2198 2198 # We could do a faster match using a Trie.
2199 2199
2200 2200 # Using pygtrie the following seem to work:
2201 2201
2202 2202 # s = PrefixSet()
2203 2203
2204 2204 # for c in range(0,0x10FFFF + 1):
2205 2205 # try:
2206 2206 # s.add(unicodedata.name(chr(c)))
2207 2207 # except ValueError:
2208 2208 # pass
2209 2209 # [''.join(k) for k in s.iter(prefix)]
2210 2210
2211 2211 # But need to be timed and adds an extra dependency.
2212 2212
2213 2213 slashpos = text.rfind('\\')
2214 2214 # if text starts with slash
2215 2215 if slashpos > -1:
2216 2216 # PERF: It's important that we don't access self._unicode_names
2217 2217 # until we're inside this if-block. _unicode_names is lazily
2218 2218 # initialized, and it takes a user-noticeable amount of time to
2219 2219 # initialize it, so we don't want to initialize it unless we're
2220 2220 # actually going to use it.
2221 2221 s = text[slashpos+1:]
2222 2222 candidates = [x for x in self.unicode_names if x.startswith(s)]
2223 2223 if candidates:
2224 2224 return s, candidates
2225 2225 else:
2226 2226 return '', ()
2227 2227
2228 2228 # if text does not start with slash
2229 2229 else:
2230 2230 return '', ()
2231 2231
2232 2232 @property
2233 2233 def unicode_names(self) -> List[str]:
2234 2234 """List of names of unicode code points that can be completed.
2235 2235
2236 2236 The list is lazily initialized on first access.
2237 2237 """
2238 2238 if self._unicode_names is None:
2239 2239 names = []
2240 2240 for c in range(0,0x10FFFF + 1):
2241 2241 try:
2242 2242 names.append(unicodedata.name(chr(c)))
2243 2243 except ValueError:
2244 2244 pass
2245 2245 self._unicode_names = _unicode_name_compute(_UNICODE_RANGES)
2246 2246
2247 2247 return self._unicode_names
2248 2248
2249 2249 def _unicode_name_compute(ranges:List[Tuple[int,int]]) -> List[str]:
2250 2250 names = []
2251 2251 for start,stop in ranges:
2252 2252 for c in range(start, stop) :
2253 2253 try:
2254 2254 names.append(unicodedata.name(chr(c)))
2255 2255 except ValueError:
2256 2256 pass
2257 2257 return names
General Comments 0
You need to be logged in to leave comments. Login now