Issue #7117, continued: Change round implementation to use the correctly-rounded
[python.git] / Doc / library / rlcompleter.rst
blob85a9d79260dfb294067ab2f82ac65eb06fefbc93
2 :mod:`rlcompleter` --- Completion function for GNU readline
3 ===========================================================
5 .. module:: rlcompleter
6    :synopsis: Python identifier completion, suitable for the GNU readline library.
7 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
10 The :mod:`rlcompleter` module defines a completion function suitable for the
11 :mod:`readline` module by completing valid Python identifiers and keywords.
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.
17 Example::
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.
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::
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")
41 On platforms without :mod:`readline`, the :class:`Completer` class defined by
42 this module can still be used for custom purposes.
45 .. _completer-objects:
47 Completer Objects
48 -----------------
50 Completer objects have the following method:
53 .. method:: Completer.complete(text, state)
55    Return the *state*\ th completion for *text*.
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).
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.