Doc/library/rlcompleter.rst

   1
   2 :mod:`rlcompleter` --- Completion function for GNU readline
   3 ===========================================================
   4
   5 .. module:: rlcompleter
   6    :synopsis: Python identifier completion, suitable for the GNU readline library.
   7 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
   8
   9
  10 The :mod:`rlcompleter` module defines a completion function suitable for the
  11 :mod:`readline` module by completing valid Python identifiers and keywords.
  12
  13 When this module is imported on a Unix platform with the :mod:`readline` module
  14 available, an instance of the :class:`Completer` class is automatically created
  15 and its :meth:`complete` method is set as the :mod:`readline` completer.
  16
  17 Example::
  18
  19    >>> import rlcompleter
  20    >>> import readline
  21    >>> readline.parse_and_bind("tab: complete")
  22    >>> readline. <TAB PRESSED>
  23    readline.__doc__          readline.get_line_buffer(  readline.read_init_file(
  24    readline.__file__         readline.insert_text(      readline.set_completer(
  25    readline.__name__         readline.parse_and_bind(
  26    >>> readline.
  27
  28 The :mod:`rlcompleter` module is designed for use with Python's interactive
  29 mode.  A user can add the following lines to his or her initialization file
  30 (identified by the :envvar:`PYTHONSTARTUP` environment variable) to get
  31 automatic :kbd:`Tab` completion::
  32
  33    try:
  34        import readline
  35    except ImportError:
  36        print "Module readline not available."
  37    else:
  38        import rlcompleter
  39        readline.parse_and_bind("tab: complete")
  40
  41 On platforms without :mod:`readline`, the :class:`Completer` class defined by
  42 this module can still be used for custom purposes.
  43
  44
  45 .. _completer-objects:
  46
  47 Completer Objects
  48 -----------------
  49
  50 Completer objects have the following method:
  51
  52
  53 .. method:: Completer.complete(text, state)
  54
  55    Return the *state*th completion for *text*.
  56
  57    If called for *text* that doesn't include a period character (``'.'``), it will
  58    complete from names currently defined in :mod:`__main__`, :mod:`__builtin__` and
  59    keywords (as defined by the :mod:`keyword` module).
  60
  61    If called for a dotted name, it will try to evaluate anything without obvious
  62    side-effects (functions will not be evaluated, but it can generate calls to
  63    :meth:`__getattr__`) up to the last part, and find matches for the rest via the
  64    :func:`dir` function.  Any exception raised during the evaluation of the
  65    expression is caught, silenced and :const:`None` is returned.
  66