cpython/Doc/library/readline.rst

248 lines
7.1 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:01 -03:00
:mod:`readline` --- GNU readline interface
==========================================
.. module:: readline
:platform: Unix
:synopsis: GNU readline support for Python.
2007-12-08 11:26:16 -04:00
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
2007-08-15 11:28:01 -03:00
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 programmaticly load configuration strings
you can check for the text "libedit" in :const:`readline.__doc__`
to differentiate between GNU readline and libedit.
2007-08-15 11:28:01 -03:00
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
2007-08-15 11:28:01 -03:00
.. 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
2007-08-15 11:28:01 -03:00
.. 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
histfile = os.path.join(os.environ["HOME"], ".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")):
Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74492 | r.david.murray | 2009-08-17 21:26:49 +0200 (Mo, 17 Aug 2009) | 2 lines Issue 6685: 'toupper' -> 'upper' in cgi doc example explanation. ........ r74531 | vinay.sajip | 2009-08-21 00:04:32 +0200 (Fr, 21 Aug 2009) | 1 line Added section on exceptions raised during logging. ........ r74545 | georg.brandl | 2009-08-24 19:14:29 +0200 (Mo, 24 Aug 2009) | 1 line #6772: mention utf-8 as utf8 alias. ........ r74546 | georg.brandl | 2009-08-24 19:20:40 +0200 (Mo, 24 Aug 2009) | 1 line #6725: spell "namespace" consistently. ........ r74547 | georg.brandl | 2009-08-24 19:22:05 +0200 (Mo, 24 Aug 2009) | 1 line #6718: fix example. ........ r74548 | georg.brandl | 2009-08-24 19:24:27 +0200 (Mo, 24 Aug 2009) | 1 line #6677: mention "deleting" as an alias for removing files. ........ r74549 | benjamin.peterson | 2009-08-24 19:42:36 +0200 (Mo, 24 Aug 2009) | 1 line fix pdf building by teaching latex the right encoding package ........ r74550 | georg.brandl | 2009-08-24 19:48:40 +0200 (Mo, 24 Aug 2009) | 1 line #6677: note that rmdir only removes empty directories. ........ r74553 | r.david.murray | 2009-08-27 03:04:59 +0200 (Do, 27 Aug 2009) | 2 lines Remove leftover text from end of sentence. ........ r74554 | georg.brandl | 2009-08-27 20:59:02 +0200 (Do, 27 Aug 2009) | 1 line Typo fix. ........ r74555 | georg.brandl | 2009-08-27 21:02:43 +0200 (Do, 27 Aug 2009) | 1 line #6787: reference fix. ........ r74588 | georg.brandl | 2009-08-30 10:35:01 +0200 (So, 30 Aug 2009) | 1 line #6803: fix old name. ........ r74603 | georg.brandl | 2009-08-31 08:38:29 +0200 (Mo, 31 Aug 2009) | 1 line other -> others where multiple arguments are accepted. ........ r74608 | senthil.kumaran | 2009-08-31 18:40:27 +0200 (Mo, 31 Aug 2009) | 3 lines Doc fix for the issue2637. ........ r74614 | georg.brandl | 2009-09-01 09:40:54 +0200 (Di, 01 Sep 2009) | 1 line #6813: better documentation for numberless string formats. ........ r74616 | georg.brandl | 2009-09-01 09:46:26 +0200 (Di, 01 Sep 2009) | 1 line #6808: clarification. ........ r74617 | georg.brandl | 2009-09-01 09:53:37 +0200 (Di, 01 Sep 2009) | 1 line #6765: hint that log(x, base) is not very sophisticated. ........ r74618 | georg.brandl | 2009-09-01 10:00:47 +0200 (Di, 01 Sep 2009) | 1 line #6810: add a link to the section about frame objects instead of just a description where to find it. ........ r74631 | georg.brandl | 2009-09-02 22:37:16 +0200 (Mi, 02 Sep 2009) | 1 line #6821: fix signature of PyBuffer_Release(). ........ r74632 | georg.brandl | 2009-09-03 09:27:26 +0200 (Do, 03 Sep 2009) | 1 line #6828: fix wrongly highlighted blocks. ........ r74633 | georg.brandl | 2009-09-03 14:31:39 +0200 (Do, 03 Sep 2009) | 1 line #6757: complete the list of types that marshal can serialize. ........ r74652 | georg.brandl | 2009-09-04 13:25:37 +0200 (Fr, 04 Sep 2009) | 1 line #6756: add some info about the "acct" parameter. ........ r74653 | georg.brandl | 2009-09-04 13:32:18 +0200 (Fr, 04 Sep 2009) | 1 line #6777: dont discourage usage of Exception.args or promote usage of Exception.message. ........ r74666 | georg.brandl | 2009-09-05 11:04:09 +0200 (Sa, 05 Sep 2009) | 1 line #6841: remove duplicated word. ........ r74671 | georg.brandl | 2009-09-05 18:47:17 +0200 (Sa, 05 Sep 2009) | 1 line #6843: add link from filterwarnings to where the meaning of the arguments is covered. ........ r74737 | georg.brandl | 2009-09-09 18:49:13 +0200 (Mi, 09 Sep 2009) | 1 line Properly document copy and deepcopy as functions. ........ r74739 | georg.brandl | 2009-09-11 09:55:20 +0200 (Fr, 11 Sep 2009) | 1 line Move function back to its section. ........ r74779 | michael.foord | 2009-09-13 18:13:36 +0200 (So, 13 Sep 2009) | 1 line Change to tutorial wording for reading text / binary files on Windows. Issue #6301. ........ r74781 | michael.foord | 2009-09-13 18:46:19 +0200 (So, 13 Sep 2009) | 1 line Note that sys._getframe is not guaranteed to exist in all implementations of Python, and a corresponding note in inspect.currentframe. Issue 6712. ........ r74782 | michael.foord | 2009-09-13 19:07:46 +0200 (So, 13 Sep 2009) | 1 line Tutorial tweaks. Issue 6849. ........ r74784 | georg.brandl | 2009-09-13 20:15:07 +0200 (So, 13 Sep 2009) | 1 line Typo fix. ........ r74791 | georg.brandl | 2009-09-14 16:08:54 +0200 (Mo, 14 Sep 2009) | 1 line #6574: list the future features in a table. ........ r74793 | georg.brandl | 2009-09-14 16:50:47 +0200 (Mo, 14 Sep 2009) | 1 line #6908: fix association of hashlib hash attributes. ........ r74818 | georg.brandl | 2009-09-16 11:23:04 +0200 (Mi, 16 Sep 2009) | 1 line #6880: add reference to classes section in exceptions section, which comes earlier. ........ r74819 | georg.brandl | 2009-09-16 11:24:57 +0200 (Mi, 16 Sep 2009) | 1 line #6876: fix base class constructor invocation in example. ........ r74820 | georg.brandl | 2009-09-16 11:30:48 +0200 (Mi, 16 Sep 2009) | 1 line #6891: comment out dead link to Unicode article. ........ r74822 | georg.brandl | 2009-09-16 12:12:06 +0200 (Mi, 16 Sep 2009) | 1 line #5621: refactor description of how class/instance attributes interact on a.x=a.x+1 or augassign. ........ r74832 | georg.brandl | 2009-09-16 17:57:46 +0200 (Mi, 16 Sep 2009) | 1 line Rewrap long lines. ........
2009-10-27 11:50:20 -03:00
code.InteractiveConsole.__init__(self, locals, filename)
2007-08-15 11:28:01 -03:00
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)