diff --git a/Lib/rlcompleter.py b/Lib/rlcompleter.py new file mode 100644 index 0000000000..bca4a7bc52 --- /dev/null +++ b/Lib/rlcompleter.py @@ -0,0 +1,205 @@ +"""Word completion for GNU readline. + +The completer completes keywords, built-ins and globals in a selectable +namespace (which defaults to __main__); when completing NAME.NAME..., it +evaluates (!) the expression up to the last dot and completes its attributes. + +It's very cool to do "import sys" type "sys.", hit the completion key (twice), +and see the list of names defined by the sys module! + +Tip: to use the tab key as the completion key, call + + readline.parse_and_bind("tab: complete") + +Notes: + +- Exceptions raised by the completer function are *ignored* (and generally cause + the completion to fail). This is a feature -- since readline sets the tty + device in raw (or cbreak) mode, printing a traceback wouldn't work well + without some complicated hoopla to save, reset and restore the tty state. + +- The evaluation of the NAME.NAME... form may cause arbitrary application + defined code to be executed if an object with a __getattr__ hook is found. + Since it is the responsibility of the application (or the user) to enable this + feature, I consider this an acceptable risk. More complicated expressions + (e.g. function calls or indexing operations) are *not* evaluated. + +- When the original stdin is not a tty device, GNU readline is never + used, and this module (and the readline module) are silently inactive. + +""" + +import atexit +import builtins +import __main__ + +__all__ = ["Completer"] + +class Completer: + def __init__(self, namespace = None): + """Create a new completer for the command line. + + Completer([namespace]) -> completer instance. + + If unspecified, the default namespace where completions are performed + is __main__ (technically, __main__.__dict__). Namespaces should be + given as dictionaries. + + Completer instances should be used as the completion mechanism of + readline via the set_completer() call: + + readline.set_completer(Completer(my_namespace).complete) + """ + + if namespace and not isinstance(namespace, dict): + raise TypeError('namespace must be a dictionary') + + # Don't bind to namespace quite yet, but flag whether the user wants a + # specific namespace or to use __main__.__dict__. This will allow us + # to bind to __main__.__dict__ at completion time, not now. + if namespace is None: + self.use_main_ns = 1 + else: + self.use_main_ns = 0 + self.namespace = namespace + + def complete(self, text, state): + """Return the next possible completion for 'text'. + + This is called successively with state == 0, 1, 2, ... until it + returns None. The completion should begin with 'text'. + + """ + if self.use_main_ns: + self.namespace = __main__.__dict__ + + if not text.strip(): + if state == 0: + if _readline_available: + readline.insert_text('\t') + readline.redisplay() + return '' + else: + return '\t' + else: + return None + + if state == 0: + if "." in text: + self.matches = self.attr_matches(text) + else: + self.matches = self.global_matches(text) + try: + return self.matches[state] + except IndexError: + return None + + def _callable_postfix(self, val, word): + if callable(val): + word = word + "(" + return word + + def global_matches(self, text): + """Compute matches when text is a simple name. + + Return a list of all keywords, built-in functions and names currently + defined in self.namespace that match. + + """ + import keyword + matches = [] + seen = {"__builtins__"} + n = len(text) + for word in keyword.kwlist: + if word[:n] == text: + seen.add(word) + if word in {'finally', 'try'}: + word = word + ':' + elif word not in {'False', 'None', 'True', + 'break', 'continue', 'pass', + 'else'}: + word = word + ' ' + matches.append(word) + for nspace in [self.namespace, builtins.__dict__]: + for word, val in nspace.items(): + if word[:n] == text and word not in seen: + seen.add(word) + matches.append(self._callable_postfix(val, word)) + return matches + + def attr_matches(self, text): + """Compute matches when text contains a dot. + + Assuming the text is of the form NAME.NAME....[NAME], and is + evaluable in self.namespace, it will be evaluated and its attributes + (as revealed by dir()) are used as possible completions. (For class + instances, class members are also considered.) + + WARNING: this can still invoke arbitrary C code, if an object + with a __getattr__ hook is evaluated. + + """ + import re + m = re.match(r"(\w+(\.\w+)*)\.(\w*)", text) + if not m: + return [] + expr, attr = m.group(1, 3) + try: + thisobject = eval(expr, self.namespace) + except Exception: + return [] + + # get the content of the object, except __builtins__ + words = set(dir(thisobject)) + words.discard("__builtins__") + + if hasattr(thisobject, '__class__'): + words.add('__class__') + words.update(get_class_members(thisobject.__class__)) + matches = [] + n = len(attr) + if attr == '': + noprefix = '_' + elif attr == '_': + noprefix = '__' + else: + noprefix = None + while True: + for word in words: + if (word[:n] == attr and + not (noprefix and word[:n+1] == noprefix)): + match = "%s.%s" % (expr, word) + try: + val = getattr(thisobject, word) + except Exception: + pass # Include even if attribute not set + else: + match = self._callable_postfix(val, match) + matches.append(match) + if matches or not noprefix: + break + if noprefix == '_': + noprefix = '__' + else: + noprefix = None + matches.sort() + return matches + +def get_class_members(klass): + ret = dir(klass) + if hasattr(klass,'__bases__'): + for base in klass.__bases__: + ret = ret + get_class_members(base) + return ret + +try: + import readline +except ImportError: + _readline_available = False +else: + readline.set_completer(Completer().complete) + # Release references early at shutdown (the readline module's + # contents are quasi-immortal, and the completer function holds a + # reference to globals). + atexit.register(lambda: readline.set_completer(None)) + _readline_available = True diff --git a/Lib/test/test_rlcompleter.py b/Lib/test/test_rlcompleter.py new file mode 100644 index 0000000000..9ea1a2c770 --- /dev/null +++ b/Lib/test/test_rlcompleter.py @@ -0,0 +1,143 @@ +import unittest +from unittest.mock import patch +import builtins +import rlcompleter + +class CompleteMe: + """ Trivial class used in testing rlcompleter.Completer. """ + spam = 1 + _ham = 2 + + +class TestRlcompleter(unittest.TestCase): + def setUp(self): + self.stdcompleter = rlcompleter.Completer() + self.completer = rlcompleter.Completer(dict(spam=int, + egg=str, + CompleteMe=CompleteMe)) + + # forces stdcompleter to bind builtins namespace + self.stdcompleter.complete('', 0) + + def test_namespace(self): + class A(dict): + pass + class B(list): + pass + + self.assertTrue(self.stdcompleter.use_main_ns) + self.assertFalse(self.completer.use_main_ns) + self.assertFalse(rlcompleter.Completer(A()).use_main_ns) + self.assertRaises(TypeError, rlcompleter.Completer, B((1,))) + + def test_global_matches(self): + # test with builtins namespace + self.assertEqual(sorted(self.stdcompleter.global_matches('di')), + [x+'(' for x in dir(builtins) if x.startswith('di')]) + self.assertEqual(sorted(self.stdcompleter.global_matches('st')), + [x+'(' for x in dir(builtins) if x.startswith('st')]) + self.assertEqual(self.stdcompleter.global_matches('akaksajadhak'), []) + + # test with a customized namespace + self.assertEqual(self.completer.global_matches('CompleteM'), + ['CompleteMe(']) + self.assertEqual(self.completer.global_matches('eg'), + ['egg(']) + # XXX: see issue5256 + self.assertEqual(self.completer.global_matches('CompleteM'), + ['CompleteMe(']) + + def test_attr_matches(self): + # test with builtins namespace + self.assertEqual(self.stdcompleter.attr_matches('str.s'), + ['str.{}('.format(x) for x in dir(str) + if x.startswith('s')]) + self.assertEqual(self.stdcompleter.attr_matches('tuple.foospamegg'), []) + expected = sorted({'None.%s%s' % (x, '(' if x != '__doc__' else '') + for x in dir(None)}) + self.assertEqual(self.stdcompleter.attr_matches('None.'), expected) + self.assertEqual(self.stdcompleter.attr_matches('None._'), expected) + self.assertEqual(self.stdcompleter.attr_matches('None.__'), expected) + + # test with a customized namespace + self.assertEqual(self.completer.attr_matches('CompleteMe.sp'), + ['CompleteMe.spam']) + self.assertEqual(self.completer.attr_matches('Completeme.egg'), []) + self.assertEqual(self.completer.attr_matches('CompleteMe.'), + ['CompleteMe.mro(', 'CompleteMe.spam']) + self.assertEqual(self.completer.attr_matches('CompleteMe._'), + ['CompleteMe._ham']) + matches = self.completer.attr_matches('CompleteMe.__') + for x in matches: + self.assertTrue(x.startswith('CompleteMe.__'), x) + self.assertIn('CompleteMe.__name__', matches) + self.assertIn('CompleteMe.__new__(', matches) + + with patch.object(CompleteMe, "me", CompleteMe, create=True): + self.assertEqual(self.completer.attr_matches('CompleteMe.me.me.sp'), + ['CompleteMe.me.me.spam']) + self.assertEqual(self.completer.attr_matches('egg.s'), + ['egg.{}('.format(x) for x in dir(str) + if x.startswith('s')]) + + def test_excessive_getattr(self): + # Ensure getattr() is invoked no more than once per attribute + class Foo: + calls = 0 + @property + def bar(self): + self.calls += 1 + return None + f = Foo() + completer = rlcompleter.Completer(dict(f=f)) + self.assertEqual(completer.complete('f.b', 0), 'f.bar') + self.assertEqual(f.calls, 1) + + # TODO: RUSTPYTHON + @unittest.expectedFailure + def test_uncreated_attr(self): + # Attributes like properties and slots should be completed even when + # they haven't been created on an instance + class Foo: + __slots__ = ("bar",) + completer = rlcompleter.Completer(dict(f=Foo())) + self.assertEqual(completer.complete('f.', 0), 'f.bar') + + @unittest.mock.patch('rlcompleter._readline_available', False) + def test_complete(self): + completer = rlcompleter.Completer() + self.assertEqual(completer.complete('', 0), '\t') + self.assertEqual(completer.complete('a', 0), 'and ') + self.assertEqual(completer.complete('a', 1), 'as ') + self.assertEqual(completer.complete('as', 2), 'assert ') + self.assertEqual(completer.complete('an', 0), 'and ') + self.assertEqual(completer.complete('pa', 0), 'pass') + self.assertEqual(completer.complete('Fa', 0), 'False') + self.assertEqual(completer.complete('el', 0), 'elif ') + self.assertEqual(completer.complete('el', 1), 'else') + self.assertEqual(completer.complete('tr', 0), 'try:') + + def test_duplicate_globals(self): + namespace = { + 'False': None, # Keyword vs builtin vs namespace + 'assert': None, # Keyword vs namespace + 'try': lambda: None, # Keyword vs callable + 'memoryview': None, # Callable builtin vs non-callable + 'Ellipsis': lambda: None, # Non-callable builtin vs callable + } + completer = rlcompleter.Completer(namespace) + self.assertEqual(completer.complete('False', 0), 'False') + self.assertIsNone(completer.complete('False', 1)) # No duplicates + # Space or colon added due to being a reserved keyword + self.assertEqual(completer.complete('assert', 0), 'assert ') + self.assertIsNone(completer.complete('assert', 1)) + self.assertEqual(completer.complete('try', 0), 'try:') + self.assertIsNone(completer.complete('try', 1)) + # No opening bracket "(" because we overrode the built-in class + self.assertEqual(completer.complete('memoryview', 0), 'memoryview') + self.assertIsNone(completer.complete('memoryview', 1)) + self.assertEqual(completer.complete('Ellipsis', 0), 'Ellipsis(') + self.assertIsNone(completer.complete('Ellipsis', 1)) + +if __name__ == '__main__': + unittest.main()