ꦫꦣꦺꦤ꧀ꦄꦤ꧀ꦠꦱꦺꦤ

PATH: usr / share / doc / python-docs-2.7.5 / html / _sources / library

:mod:`readline` --- GNU readline interface
==========================================

.. module:: readline
   :platform: Unix
   :synopsis: GNU readline support for Python.
.. sectionauthor:: Skip Montanaro <skip@pobox.com>

The :mod:`readline` module defines a number of functions to facilitate
completion and reading/writing of history files from the Python interpreter.
This module can be used directly or via the :mod:`rlcompleter` module.  Settings
made using  this module affect the behaviour of both the interpreter's
interactive prompt  and the prompts offered by the :func:`raw_input` and
:func:`input` built-in functions.

.. note::

On MacOS X the :mod:`readline` module can be implemented using
  the ``libedit`` library instead of GNU readline.

The configuration file for ``libedit`` is different from that
  of GNU readline. If you programmatically load configuration strings
  you can check for the text "libedit" in :const:`readline.__doc__`
  to differentiate between GNU readline and libedit.

The :mod:`readline` module defines the following functions:

.. function:: parse_and_bind(string)

Parse and execute single line of a readline init file.

.. function:: get_line_buffer()

Return the current contents of the line buffer.

.. function:: insert_text(string)

Insert text into the command line.

.. function:: read_init_file([filename])

Parse a readline initialization file. The default filename is the last filename
   used.

.. function:: read_history_file([filename])

Load a readline history file. The default filename is :file:`~/.history`.

.. function:: write_history_file([filename])

Save a readline history file. The default filename is :file:`~/.history`.

.. function:: clear_history()

Clear the current history.  (Note: this function is not available if the
   installed version of GNU readline doesn't support it.)

.. versionadded:: 2.4

.. function:: get_history_length()

Return the desired length of the history file.  Negative values imply unlimited
   history file size.

.. function:: set_history_length(length)

Set the number of lines to save in the history file. :func:`write_history_file`
   uses this value to truncate the history file when saving.  Negative values imply
   unlimited history file size.

.. function:: get_current_history_length()

Return the number of lines currently in the history.  (This is different from
   :func:`get_history_length`, which returns the maximum number of lines that will
   be written to a history file.)

.. versionadded:: 2.3

.. function:: get_history_item(index)

Return the current contents of history item at *index*.

.. versionadded:: 2.3

.. function:: remove_history_item(pos)

Remove history item specified by its position from the history.

.. versionadded:: 2.4

.. function:: replace_history_item(pos, line)

Replace history item specified by its position with the given line.

.. versionadded:: 2.4

.. function:: redisplay()

Change what's displayed on the screen to reflect the current contents of the
   line buffer.

.. versionadded:: 2.3

.. function:: set_startup_hook([function])

Set or remove the startup_hook function.  If *function* is specified, it will be
   used as the new startup_hook function; if omitted or ``None``, any hook function
   already installed is removed.  The startup_hook function is called with no
   arguments just before readline prints the first prompt.

.. function:: set_pre_input_hook([function])

Set or remove the pre_input_hook function.  If *function* is specified, it will
   be used as the new pre_input_hook function; if omitted or ``None``, any hook
   function already installed is removed.  The pre_input_hook function is called
   with no arguments after the first prompt has been printed and just before
   readline starts reading input characters.

.. function:: set_completer([function])

Set or remove the completer function.  If *function* is specified, it will be
   used as the new completer function; if omitted or ``None``, any completer
   function already installed is removed.  The completer function is called as
   ``function(text, state)``, for *state* in ``0``, ``1``, ``2``, ..., until it
   returns a non-string value.  It should return the next possible completion
   starting with *text*.

.. function:: get_completer()

Get the completer function, or ``None`` if no completer function has been set.

.. versionadded:: 2.3

.. function:: get_completion_type()

Get the type of completion being attempted.

.. versionadded:: 2.6

.. function:: get_begidx()

Get the beginning index of the readline tab-completion scope.

.. function:: get_endidx()

Get the ending index of the readline tab-completion scope.

.. function:: set_completer_delims(string)

Set the readline word delimiters for tab-completion.

.. function:: get_completer_delims()

Get the readline word delimiters for tab-completion.

.. function:: set_completion_display_matches_hook([function])

Set or remove the completion display function.  If *function* is
   specified, it will be used as the new completion display function;
   if omitted or ``None``, any completion display function already
   installed is removed.  The completion display function is called as
   ``function(substitution, [matches], longest_match_length)`` once
   each time matches need to be displayed.

.. versionadded:: 2.6

.. function:: add_history(line)

Append a line to the history buffer, as if it was the last line typed.

.. seealso::

Module :mod:`rlcompleter`
      Completion of Python identifiers at the interactive prompt.

.. _readline-example:

Example
-------

The following example demonstrates how to use the :mod:`readline` module's
history reading and writing functions to automatically load and save a history
file named :file:`.pyhist` from the user's home directory.  The code below would
normally be executed automatically during interactive sessions from the user's
:envvar:`PYTHONSTARTUP` file. ::

import os
   import readline
   histfile = os.path.join(os.path.expanduser("~"), ".pyhist")
   try:
       readline.read_history_file(histfile)
   except IOError:
       pass
   import atexit
   atexit.register(readline.write_history_file, histfile)
   del os, histfile

The following example extends the :class:`code.InteractiveConsole` class to
support history save/restore. ::

import code
   import readline
   import atexit
   import os

class HistoryConsole(code.InteractiveConsole):
       def __init__(self, locals=None, filename="<console>",
                    histfile=os.path.expanduser("~/.console-history")):
           code.InteractiveConsole.__init__(self, locals, filename)
           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)

[+] ..
[-] fpformat.txt [edit]
[-] string.txt [edit]
[-] aetypes.txt [edit]
[-] textwrap.txt [edit]
[-] codecs.txt [edit]
[-] array.txt [edit]
[-] urllib2.txt [edit]
[-] pickle.txt [edit]
[-] 2to3.txt [edit]
[-] ossaudiodev.txt [edit]
[-] markup.txt [edit]
[-] sha.txt [edit]
[-] stat.txt [edit]
[-] itertools.txt [edit]
[-] numeric.txt [edit]
[-] gzip.txt [edit]
[-] pkgutil.txt [edit]
[-] subprocess.txt [edit]
[-] token.txt [edit]
[-] debug.txt [edit]
[-] dummy_thread.txt [edit]
[-] mimify.txt [edit]
[-] bastion.txt [edit]
[-] popen2.txt [edit]
[-] autogil.txt [edit]
[-] importlib.txt [edit]
[-] io.txt [edit]
[-] msilib.txt [edit]
[-] development.txt [edit]
[-] hotshot.txt [edit]
[-] constants.txt [edit]
[-] curses.ascii.txt [edit]
[-] os.txt [edit]
[-] easydialogs.txt [edit]
[-] mutex.txt [edit]
[-] md5.txt [edit]
[-] stdtypes.txt [edit]
[-] bz2.txt [edit]
[-] imgfile.txt [edit]
[-] aetools.txt [edit]
[-] internet.txt [edit]
[-] xml.dom.pulldom.txt [edit]
[-] cookie.txt [edit]
[-] sunau.txt [edit]
[-] archiving.txt [edit]
[-] modules.txt [edit]
[-] base64.txt [edit]
[-] ttk.txt [edit]
[-] tty.txt [edit]
[-] cookielib.txt [edit]
[-] pydoc.txt [edit]
[-] misc.txt [edit]
[-] fm.txt [edit]
[-] whichdb.txt [edit]
[-] imghdr.txt [edit]
[-] datatypes.txt [edit]
[-] dis.txt [edit]
[-] datetime.txt [edit]
[-] userdict.txt [edit]
[-] py_compile.txt [edit]
[-] imputil.txt [edit]
[-] xml.dom.minidom.txt [edit]
[-] multiprocessing.txt [edit]
[-] functools.txt [edit]
[-] audioop.txt [edit]
[-] language.txt [edit]
[-] miniaeframe.txt [edit]
[-] ssl.txt [edit]
[-] copy_reg.txt [edit]
[-] heapq.txt [edit]
[-] syslog.txt [edit]
[-] fileformats.txt [edit]
[-] simplexmlrpcserver.txt [edit]
[-] numbers.txt [edit]
[-] pipes.txt [edit]
[-] shutil.txt [edit]
[-] zlib.txt [edit]
[-] optparse.txt [edit]
[-] allos.txt [edit]
[-] custominterp.txt [edit]
[-] windows.txt [edit]
[-] dbm.txt [edit]
[-] select.txt [edit]
[-] time.txt [edit]
[-] index.txt [edit]
[-] undoc.txt [edit]
[-] plistlib.txt [edit]
[-] htmllib.txt [edit]
[-] warnings.txt [edit]
[-] functions.txt [edit]
[-] argparse.txt [edit]
[-] distutils.txt [edit]
[-] macpath.txt [edit]
[-] fnmatch.txt [edit]
[-] tabnanny.txt [edit]
[-] calendar.txt [edit]
[-] jpeg.txt [edit]
[-] zipimport.txt [edit]
[-] unix.txt [edit]
[-] chunk.txt [edit]
[-] smtplib.txt [edit]
[-] tokenize.txt [edit]
[-] asynchat.txt [edit]
[-] decimal.txt [edit]
[-] cd.txt [edit]
[-] pickletools.txt [edit]
[-] statvfs.txt [edit]
[-] gettext.txt [edit]
[-] sqlite3.txt [edit]
[-] imageop.txt [edit]
[-] dl.txt [edit]
[-] logging.handlers.txt [edit]
[-] zipfile.txt [edit]
[-] copy.txt [edit]
[-] sched.txt [edit]
[-] nis.txt [edit]
[-] timeit.txt [edit]
[-] weakref.txt [edit]
[-] mailbox.txt [edit]
[-] othergui.txt [edit]
[-] sgmllib.txt [edit]
[-] mimewriter.txt [edit]
[-] email.charset.txt [edit]
[-] mmap.txt [edit]
[-] xmlrpclib.txt [edit]
[-] robotparser.txt [edit]
[-] xml.sax.reader.txt [edit]
[-] hmac.txt [edit]
[-] collections.txt [edit]
[-] mimetools.txt [edit]
[-] aifc.txt [edit]
[-] modulefinder.txt [edit]
[-] socketserver.txt [edit]
[-] grp.txt [edit]
[-] getopt.txt [edit]
[-] __future__.txt [edit]
[-] binascii.txt [edit]
[-] symtable.txt [edit]
[-] crypt.txt [edit]
[-] email.encoders.txt [edit]
[-] imaplib.txt [edit]
[-] spwd.txt [edit]
[-] wsgiref.txt [edit]
[-] errno.txt [edit]
[-] email-examples.txt [edit]
[-] sun.txt [edit]
[-] doctest.txt [edit]
[-] resource.txt [edit]
[-] asyncore.txt [edit]
[-] curses.panel.txt [edit]
[-] imp.txt [edit]
[-] htmlparser.txt [edit]
[-] thread.txt [edit]
[-] posix.txt [edit]
[-] repr.txt [edit]
[-] macostools.txt [edit]
[-] colorsys.txt [edit]
[-] bdb.txt [edit]
[-] stringio.txt [edit]
[-] mm.txt [edit]
[-] cgi.txt [edit]
[-] math.txt [edit]
[-] httplib.txt [edit]
[-] urlparse.txt [edit]
[-] aepack.txt [edit]
[-] colorpicker.txt [edit]
[-] binhex.txt [edit]
[-] tk.txt [edit]
[-] xml.txt [edit]
[-] webbrowser.txt [edit]
[-] contextlib.txt [edit]
[-] types.txt [edit]
[-] shelve.txt [edit]
[-] platform.txt [edit]
[-] readline.txt [edit]
[-] locale.txt [edit]
[-] sets.txt [edit]
[-] macosa.txt [edit]
[-] bisect.txt [edit]
[-] email.parser.txt [edit]
[-] xml.sax.txt [edit]
[-] xml.etree.elementtree.txt [edit]
[-] netrc.txt [edit]
[-] new.txt [edit]
[-] bsddb.txt [edit]
[-] fl.txt [edit]
[-] curses.txt [edit]
[-] hashlib.txt [edit]
[-] tarfile.txt [edit]
[-] ftplib.txt [edit]
[-] telnetlib.txt [edit]
[-] macos.txt [edit]
[-] multifile.txt [edit]
[-] dbhash.txt [edit]
[-] netdata.txt [edit]
[-] fileinput.txt [edit]
[-] python.txt [edit]
[-] mac.txt [edit]
[-] filesys.txt [edit]
[-] scrolledtext.txt [edit]
[-] compiler.txt [edit]
[-] tkinter.txt [edit]
[-] random.txt [edit]
[-] mailcap.txt [edit]
[-] fpectl.txt [edit]
[-] fcntl.txt [edit]
[-] ipc.txt [edit]
[-] formatter.txt [edit]
[-] profile.txt [edit]
[-] xml.dom.txt [edit]
[-] email.iterators.txt [edit]
[-] logging.config.txt [edit]
[-] rlcompleter.txt [edit]
[-] idle.txt [edit]
[-] gdbm.txt [edit]
[-] ast.txt [edit]
[-] someos.txt [edit]
[-] cmd.txt [edit]
[-] re.txt [edit]
[-] docxmlrpcserver.txt [edit]
[-] pdb.txt [edit]
[-] rexec.txt [edit]
[-] commands.txt [edit]
[-] restricted.txt [edit]
[-] crypto.txt [edit]
[-] dumbdbm.txt [edit]
[-] email.txt [edit]
[-] linecache.txt [edit]
[-] os.path.txt [edit]
[-] cgitb.txt [edit]
[-] _winreg.txt [edit]
[-] carbon.txt [edit]
[-] turtle.txt [edit]
[-] xml.sax.handler.txt [edit]
[-] json.txt [edit]
[-] email.generator.txt [edit]
[-] struct.txt [edit]
[-] mhlib.txt [edit]
[-] uuid.txt [edit]
[-] threading.txt [edit]
[-] mimetypes.txt [edit]
[-] traceback.txt [edit]
[-] filecmp.txt [edit]
[-] sndhdr.txt [edit]
[-] logging.txt [edit]
[-] getpass.txt [edit]
[-] dummy_threading.txt [edit]
[-] abc.txt [edit]
[-] shlex.txt [edit]
[-] email.mime.txt [edit]
[-] fractions.txt [edit]
[-] email.header.txt [edit]
[-] marshal.txt [edit]
[-] symbol.txt [edit]
[-] wave.txt [edit]
[-] urllib.txt [edit]
[-] queue.txt [edit]
[-] operator.txt [edit]
[-] compileall.txt [edit]
[-] sysconfig.txt [edit]
[-] quopri.txt [edit]
[-] inspect.txt [edit]
[-] xdrlib.txt [edit]
[-] __builtin__.txt [edit]
[-] ic.txt [edit]
[-] signal.txt [edit]
[-] dircache.txt [edit]
[-] rfc822.txt [edit]
[-] glob.txt [edit]
[-] stringprep.txt [edit]
[-] tix.txt [edit]
[-] i18n.txt [edit]
[-] email.util.txt [edit]
[-] anydbm.txt [edit]
[-] code.txt [edit]
[-] __main__.txt [edit]
[-] difflib.txt [edit]
[-] unicodedata.txt [edit]
[-] sunaudio.txt [edit]
[-] msvcrt.txt [edit]
[-] site.txt [edit]
[-] codeop.txt [edit]
[-] uu.txt [edit]
[-] winsound.txt [edit]
[-] smtpd.txt [edit]
[-] al.txt [edit]
[-] user.txt [edit]
[-] poplib.txt [edit]
[-] nntplib.txt [edit]
[-] keyword.txt [edit]
[-] ctypes.txt [edit]
[-] socket.txt [edit]
[-] simplehttpserver.txt [edit]
[-] sys.txt [edit]
[-] pyexpat.txt [edit]
[-] configparser.txt [edit]
[-] persistence.txt [edit]
[-] trace.txt [edit]
[-] runpy.txt [edit]
[-] csv.txt [edit]
[-] test.txt [edit]
[-] framework.txt [edit]
[-] gc.txt [edit]
[-] cmath.txt [edit]
[-] exceptions.txt [edit]
[-] pyclbr.txt [edit]
[-] sgi.txt [edit]
[-] parser.txt [edit]
[-] future_builtins.txt [edit]
[-] pwd.txt [edit]
[-] strings.txt [edit]
[-] frameworks.txt [edit]
[-] email.message.txt [edit]
[-] cgihttpserver.txt [edit]
[-] intro.txt [edit]
[-] email.errors.txt [edit]
[-] pprint.txt [edit]
[-] pty.txt [edit]
[-] xml.sax.utils.txt [edit]
[-] posixfile.txt [edit]
[-] tempfile.txt [edit]
[-] termios.txt [edit]
[-] gl.txt [edit]
[-] gensuitemodule.txt [edit]
[-] atexit.txt [edit]
[-] basehttpserver.txt [edit]
[-] unittest.txt [edit]