/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
10The :mod:`rlcompleter` module defines a completion function suitable for the
11:mod:`readline` module by completing valid Python identifiers and keywords.
12
13When this module is imported on a Unix platform with the :mod:`readline` module
14available, an instance of the :class:`Completer` class is automatically created
15and its :meth:`complete` method is set as the :mod:`readline` completer.
16
17Example::
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
28The :mod:`rlcompleter` module is designed for use with Python's interactive
29mode.  A user can add the following lines to his or her initialization file
30(identified by the :envvar:`PYTHONSTARTUP` environment variable) to get
31automatic :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
41On platforms without :mod:`readline`, the :class:`Completer` class defined by
42this module can still be used for custom purposes.
43
44
45.. _completer-objects:
46
47Completer Objects
48-----------------
49
50Completer 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