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