\section{\module{readline} ---         GNU readline interface} \declaremodule{builtin}{readline}  \platform{Unix}\sectionauthor{Skip Montanaro}{skip@mojam.com}\modulesynopsis{GNU readline support for Python.}  The \module{readline} module defines a number of functions tofacilitate completion and reading/writing of history files from thePython interpreter.  This module can be used directly or via the\refmodule{rlcompleter} module.  Settings made using this module affect the behaviour of both the interpreter's interactive prompt and the prompts offered by the \function{raw_input()} and \function{input()}built-in functions. The \module{readline} module defines the following functions:  \begin{funcdesc}{parse_and_bind}{string}Parse and execute single line of a readline init file.\end{funcdesc} \begin{funcdesc}{get_line_buffer}{}Return the current contents of the line buffer.\end{funcdesc} \begin{funcdesc}{insert_text}{string}Insert text into the command line.\end{funcdesc} \begin{funcdesc}{read_init_file}{\optional{filename}}Parse a readline initialization file.The default filename is the last filename used.\end{funcdesc} \begin{funcdesc}{read_history_file}{\optional{filename}}Load a readline history file.The default filename is \file{\~{}/.history}.\end{funcdesc} \begin{funcdesc}{write_history_file}{\optional{filename}}Save a readline history file.The default filename is \file{\~{}/.history}.\end{funcdesc} \begin{funcdesc}{clear_history}{}Clear the current history.  (Note: this function is not available ifthe installed version of GNU readline doesn't support it.)\versionadded{2.4}\end{funcdesc} \begin{funcdesc}{get_history_length}{}Return the desired length of the history file.  Negative values implyunlimited history file size.\end{funcdesc} \begin{funcdesc}{set_history_length}{length}Set the number of lines to save in the history file.\function{write_history_file()} uses this value to truncate thehistory file when saving.  Negative values imply unlimited historyfile size.\end{funcdesc} \begin{funcdesc}{get_current_history_length}{}Return the number of lines currently in the history.  (This is differentfrom \function{get_history_length()}, which returns the maximum number oflines that will be written to a history file.)  \versionadded{2.3}\end{funcdesc} \begin{funcdesc}{get_history_item}{index}Return the current contents of history item at \var{index}.\versionadded{2.3}\end{funcdesc} \begin{funcdesc}{remove_history_item}{pos}Remove history item specified by its position from the history.\versionadded{2.4}\end{funcdesc} \begin{funcdesc}{replace_history_item}{pos, line}Replace history item specified by its position with the given line.\versionadded{2.4}\end{funcdesc} \begin{funcdesc}{redisplay}{}Change what's displayed on the screen to reflect the current contentsof the line buffer.  \versionadded{2.3}\end{funcdesc} \begin{funcdesc}{set_startup_hook}{\optional{function}}Set or remove the startup_hook function.  If \var{function} is specified,it will be used as the new startup_hook function; if omitted or\code{None}, any hook function already installed is removed.  Thestartup_hook function is called with no arguments justbefore readline prints the first prompt.\end{funcdesc} \begin{funcdesc}{set_pre_input_hook}{\optional{function}}Set or remove the pre_input_hook function.  If \var{function} is specified,it will be used as the new pre_input_hook function; if omitted or\code{None}, any hook function already installed is removed.  Thepre_input_hook function is called with no arguments after the first prompthas been printed and just before readline starts reading input characters.\end{funcdesc} \begin{funcdesc}{set_completer}{\optional{function}}Set or remove the completer function.  If \var{function} is specified,it will be used as the new completer function; if omitted or\code{None}, any completer function already installed is removed.  Thecompleter function is called as \code{\var{function}(\var{text},\var{state})}, for \var{state} in \code{0}, \code{1}, \code{2}, ...,until it returns a non-string value.  It should return the nextpossible completion starting with \var{text}.\end{funcdesc} \begin{funcdesc}{get_completer}{}Get the completer function, or \code{None} if no completer functionhas been set.  \versionadded{2.3}\end{funcdesc} \begin{funcdesc}{get_begidx}{}Get the beginning index of the readline tab-completion scope.\end{funcdesc} \begin{funcdesc}{get_endidx}{}Get the ending index of the readline tab-completion scope.\end{funcdesc} \begin{funcdesc}{set_completer_delims}{string}Set the readline word delimiters for tab-completion.\end{funcdesc} \begin{funcdesc}{get_completer_delims}{}Get the readline word delimiters for tab-completion.\end{funcdesc} \begin{funcdesc}{add_history}{line}Append a line to the history buffer, as if it was the last line typed.\end{funcdesc} \begin{seealso}  \seemodule{rlcompleter}{Completion of Python identifiers at the                          interactive prompt.}\end{seealso}  \subsection{Example \label{readline-example}} The following example demonstrates how to use the\module{readline} module's history reading and writing functions toautomatically load and save a history file named \file{.pyhist} fromthe user's home directory.  The code below would normally be executedautomatically during interactive sessions from the user's\envvar{PYTHONSTARTUP} file. \begin{verbatim}import oshistfile = os.path.join(os.environ["HOME"], ".pyhist")try:    readline.read_history_file(histfile)except IOError:    passimport atexitatexit.register(readline.write_history_file, histfile)del os, histfile\end{verbatim} The following example extends the \class{code.InteractiveConsole} class tosupport history save/restore. \begin{verbatim}import codeimport readlineimport atexitimport os class HistoryConsole(code.InteractiveConsole):    def __init__(self, locals=None, filename="<console>",                 histfile=os.path.expanduser("~/.console-history")):        code.InteractiveConsole.__init__(self)        self.init_history(histfile)     def init_history(self, histfile):        readline.parse_and_bind("tab: complete")        if hasattr(readline, "read_history_file"):            try:                readline.read_history_file(histfile)            except IOError:                pass            atexit.register(self.save_history, histfile)     def save_history(self, histfile):        readline.write_history_file(histfile)\end{verbatim}