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