Debian Codegraph @

Doc/library/rlcompleter.rst

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