Lib/rlcompleter.py

   1 """Word completion for GNU readline 2.0.
   2
   3 This requires the latest extension to the readline module (the
   4 completes keywords, built-ins and globals in __main__; when completing
   5 NAME.NAME..., it evaluates (!) the expression up to the last dot and
   6 completes its attributes.
   7
   8 It's very cool to do "import string" type "string.", hit the
   9 completion key (twice), and see the list of names defined by the
  10 string module!
  11
  12 Tip: to use the tab key as the completion key, call
  13
  14     readline.parse_and_bind("tab: complete")
  15
  16 Notes:
  17
  18 - Exceptions raised by the completer function are *ignored* (and
  19 generally cause the completion to fail).  This is a feature -- since
  20 readline sets the tty device in raw (or cbreak) mode, printing a
  21 traceback wouldn't work well without some complicated hoopla to save,
  22 reset and restore the tty state.
  23
  24 - The evaluation of the NAME.NAME... form may cause arbitrary
  25 application defined code to be executed if an object with a
  26 __getattr__ hook is found.  Since it is the responsibility of the
  27 application (or the user) to enable this feature, I consider this an
  28 acceptable risk.  More complicated expressions (e.g. function calls or
  29 indexing operations) are *not* evaluated.
  30
  31 - GNU readline is also used by the built-in functions input() and
  32 raw_input(), and thus these also benefit/suffer from the completer
  33 features.  Clearly an interactive application can benefit by
  34 specifying its own completer function and using raw_input() for all
  35 its input.
  36
  37 - When the original stdin is not a tty device, GNU readline is never
  38 used, and this module (and the readline module) are silently inactive.
  39
  40 """
  41
  42 import readline
  43 import __builtin__
  44 import __main__
  45
  46 __all__ = ["Completer"]
  47
  48 class Completer:
  49
  50     def complete(self, text, state):
  51         """Return the next possible completion for 'text'.
  52
  53         This is called successively with state == 0, 1, 2, ... until it
  54         returns None.  The completion should begin with 'text'.
  55
  56         """
  57         if state == 0:
  58             if "." in text:
  59                 self.matches = self.attr_matches(text)
  60             else:
  61                 self.matches = self.global_matches(text)
  62         try:
  63             return self.matches[state]
  64         except IndexError:
  65             return None
  66
  67     def global_matches(self, text):
  68         """Compute matches when text is a simple name.
  69
  70         Return a list of all keywords, built-in functions and names
  71         currently defines in __main__ that match.
  72
  73         """
  74         import keyword
  75         matches = []
  76         n = len(text)
  77         for list in [keyword.kwlist,
  78                      __builtin__.__dict__.keys(),
  79                      __main__.__dict__.keys()]:
  80             for word in list:
  81                 if word[:n] == text and word != "__builtins__":
  82                     matches.append(word)
  83         return matches
  84
  85     def attr_matches(self, text):
  86         """Compute matches when text contains a dot.
  87
  88         Assuming the text is of the form NAME.NAME....[NAME], and is
  89         evaluatable in the globals of __main__, it will be evaluated
  90         and its attributes (as revealed by dir()) are used as possible
  91         completions.  (For class instances, class members are are also
  92         considered.)
  93
  94         WARNING: this can still invoke arbitrary C code, if an object
  95         with a __getattr__ hook is evaluated.
  96
  97         """
  98         import re
  99         m = re.match(r"(\w+(\.\w+)*)\.(\w*)", text)
 100         if not m:
 101             return
 102         expr, attr = m.group(1, 3)
 103         object = eval(expr, __main__.__dict__)
 104         words = dir(object)
 105         if hasattr(object,'__class__'):
 106             words.append('__class__')
 107             words = words + get_class_members(object.__class__)
 108         matches = []
 109         n = len(attr)
 110         for word in words:
 111             if word[:n] == attr and word != "__builtins__":
 112                 matches.append("%s.%s" % (expr, word))
 113         return matches
 114
 115 def get_class_members(klass):
 116     ret = dir(klass)
 117     if hasattr(klass,'__bases__'):
 118         for base in klass.__bases__:
 119             ret = ret + get_class_members(base)
 120     return ret
 121
 122 readline.set_completer(Completer().complete)