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