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