/Lib/rlcompleter.py

  1"""Word completion for GNU readline 2.0.
  2
  3This requires the latest extension to the readline module. The completer
  4completes keywords, built-ins and globals in a selectable namespace (which
  5defaults to __main__); when completing NAME.NAME..., it evaluates (!) the
  6expression up to the last dot and completes its attributes.
  7
  8It's very cool to do "import sys" type "sys.", hit the
  9completion key (twice), and see the list of names defined by the
 10sys module!
 11
 12Tip: to use the tab key as the completion key, call
 13
 14    readline.parse_and_bind("tab: complete")
 15
 16Notes:
 17
 18- Exceptions raised by the completer function are *ignored* (and
 19generally cause the completion to fail).  This is a feature -- since
 20readline sets the tty device in raw (or cbreak) mode, printing a
 21traceback wouldn't work well without some complicated hoopla to save,
 22reset and restore the tty state.
 23
 24- The evaluation of the NAME.NAME... form may cause arbitrary
 25application defined code to be executed if an object with a
 26__getattr__ hook is found.  Since it is the responsibility of the
 27application (or the user) to enable this feature, I consider this an
 28acceptable risk.  More complicated expressions (e.g. function calls or
 29indexing operations) are *not* evaluated.
 30
 31- GNU readline is also used by the built-in functions input() and
 32raw_input(), and thus these also benefit/suffer from the completer
 33features.  Clearly an interactive application can benefit by
 34specifying its own completer function and using raw_input() for all
 35its input.
 36
 37- When the original stdin is not a tty device, GNU readline is never
 38used, and this module (and the readline module) are silently inactive.
 39
 40"""
 41
 42import __builtin__
 43import __main__
 44
 45__all__ = ["Completer"]
 46
 47class Completer:
 48    def __init__(self, namespace = None):
 49        """Create a new completer for the command line.
 50
 51        Completer([namespace]) -> completer instance.
 52
 53        If unspecified, the default namespace where completions are performed
 54        is __main__ (technically, __main__.__dict__). Namespaces should be
 55        given as dictionaries.
 56
 57        Completer instances should be used as the completion mechanism of
 58        readline via the set_completer() call:
 59
 60        readline.set_completer(Completer(my_namespace).complete)
 61        """
 62
 63        if namespace and not isinstance(namespace, dict):
 64            raise TypeError,'namespace must be a dictionary'
 65
 66        # Don't bind to namespace quite yet, but flag whether the user wants a
 67        # specific namespace or to use __main__.__dict__. This will allow us
 68        # to bind to __main__.__dict__ at completion time, not now.
 69        if namespace is None:
 70            self.use_main_ns = 1
 71        else:
 72            self.use_main_ns = 0
 73            self.namespace = namespace
 74
 75    def complete(self, text, state):
 76        """Return the next possible completion for 'text'.
 77
 78        This is called successively with state == 0, 1, 2, ... until it
 79        returns None.  The completion should begin with 'text'.
 80
 81        """
 82        if self.use_main_ns:
 83            self.namespace = __main__.__dict__
 84
 85        if state == 0:
 86            if "." in text:
 87                self.matches = self.attr_matches(text)
 88            else:
 89                self.matches = self.global_matches(text)
 90        try:
 91            return self.matches[state]
 92        except IndexError:
 93            return None
 94
 95    def _callable_postfix(self, val, word):
 96        if hasattr(val, '__call__'):
 97            word = word + "("
 98        return word
 99
100    def global_matches(self, text):
101        """Compute matches when text is a simple name.
102
103        Return a list of all keywords, built-in functions and names currently
104        defined in self.namespace that match.
105
106        """
107        import keyword
108        matches = []
109        n = len(text)
110        for word in keyword.kwlist:
111            if word[:n] == text:
112                matches.append(word)
113        for nspace in [__builtin__.__dict__, self.namespace]:
114            for word, val in nspace.items():
115                if word[:n] == text and word != "__builtins__":
116                    matches.append(self._callable_postfix(val, word))
117        return matches
118
119    def attr_matches(self, text):
120        """Compute matches when text contains a dot.
121
122        Assuming the text is of the form NAME.NAME....[NAME], and is
123        evaluatable in self.namespace, it will be evaluated and its attributes
124        (as revealed by dir()) are used as possible completions.  (For class
125        instances, class members are also considered.)
126
127        WARNING: this can still invoke arbitrary C code, if an object
128        with a __getattr__ hook is evaluated.
129
130        """
131        import re
132        m = re.match(r"(\w+(\.\w+)*)\.(\w*)", text)
133        if not m:
134            return []
135        expr, attr = m.group(1, 3)
136        try:
137            thisobject = eval(expr, self.namespace)
138        except Exception:
139            return []
140
141        # get the content of the object, except __builtins__
142        words = dir(thisobject)
143        if "__builtins__" in words:
144            words.remove("__builtins__")
145
146        if hasattr(thisobject, '__class__'):
147            words.append('__class__')
148            words.extend(get_class_members(thisobject.__class__))
149        matches = []
150        n = len(attr)
151        for word in words:
152            if word[:n] == attr and hasattr(thisobject, word):
153                val = getattr(thisobject, word)
154                word = self._callable_postfix(val, "%s.%s" % (expr, word))
155                matches.append(word)
156        return matches
157
158def get_class_members(klass):
159    ret = dir(klass)
160    if hasattr(klass,'__bases__'):
161        for base in klass.__bases__:
162            ret = ret + get_class_members(base)
163    return ret
164
165try:
166    import readline
167except ImportError:
168    pass
169else:
170    readline.set_completer(Completer().complete)