[Python-checkins] cpython (2.7): Issue #6953: Rearrange and expand Readline module documentation
martin.panter
python-checkins at python.org
Tue Apr 5 06:31:35 EDT 2016
https://hg.python.org/cpython/rev/6137c46cb8df
changeset: 100850:6137c46cb8df
branch: 2.7
user: Martin Panter <vadmium+py at gmail.com>
date: Tue Apr 05 07:37:22 2016 +0000
summary:
Issue #6953: Rearrange and expand Readline module documentation
* Group functions into six new subsections
* Document the underlying Readline function or variable accessed
* get_history_length() returns the history file limit
* clear_history() is conditionally compiled in
* Clarify zero and one bases for history item indexes
* parse_and_bind() uses its argument directly as an init line
* Change "command line" to "line buffer" for consistency
* read_init_file() also executes the file
* read_history_file() replaces the previous history
* write_history_file() overwrites any existing file
* Differentiate history file lines from history list items, which could be
multi-line
* Add more information about completion, also addressing Issue #10796
* libedit (Editline) may be used on any platform; detection is OS X specific
files:
Doc/library/readline.rst | 180 +++++++++++++++++---------
Misc/NEWS | 7 +
Modules/readline.c | 30 ++--
3 files changed, 140 insertions(+), 77 deletions(-)
diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst
--- a/Doc/library/readline.rst
+++ b/Doc/library/readline.rst
@@ -9,15 +9,18 @@
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
+This module can be used directly, or via the :mod:`rlcompleter` module, which
+supports completion of Python identifiers at the interactive prompt. 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 underlying Readline library API may be implemented by
the ``libedit`` library instead of GNU readline.
+ On MacOS X the :mod:`readline` module detects which library is being used
+ at run time.
The configuration file for ``libedit`` is different from that
of GNU readline. If you programmatically load configuration strings
@@ -25,64 +28,97 @@
to differentiate between GNU readline and libedit.
-The :mod:`readline` module defines the following functions:
+Init file
+---------
+
+The following functions relate to the init file and user configuration:
.. function:: parse_and_bind(string)
- Parse and execute single line of a readline init file.
+ Execute the init line provided in the *string* argument. This calls
+ :c:func:`rl_parse_and_bind` in the underlying library.
+
+
+.. function:: read_init_file([filename])
+
+ Execute a readline initialization file. The default filename is the last filename
+ used. This calls :c:func:`rl_read_init_file` in the underlying library.
+
+
+Line buffer
+-----------
+
+The following functions operate on the line buffer:
.. function:: get_line_buffer()
- Return the current contents of the line buffer.
+ Return the current contents of the line buffer (:c:data:`rl_line_buffer`
+ in the underlying library).
.. function:: insert_text(string)
- Insert text into the command line.
+ Insert text into the line buffer at the cursor position. This calls
+ :c:func:`rl_insert_text` in the underlying library, but ignores
+ the return value.
-.. function:: read_init_file([filename])
+.. function:: redisplay()
- Parse a readline initialization file. The default filename is the last filename
- used.
+ Change what's displayed on the screen to reflect the current contents of the
+ line buffer. This calls :c:func:`rl_redisplay` in the underlying library.
+
+
+History file
+------------
+
+The following functions operate on a history file:
.. function:: read_history_file([filename])
- Load a readline history file. The default filename is :file:`~/.history`.
+ Load a readline history file, and append it to the history list.
+ The default filename is :file:`~/.history`. This calls
+ :c:func:`read_history` in the underlying library.
.. function:: write_history_file([filename])
- Save a readline history file. The default filename is :file:`~/.history`.
+ Save the history list to a readline history file, overwriting any
+ existing file. The default filename is :file:`~/.history`. This calls
+ :c:func:`write_history` in the underlying library.
+
+
+.. function:: get_history_length()
+ set_history_length(length)
+
+ Set or return the desired number of lines to save in the history file.
+ The :func:`write_history_file` function uses this value to truncate
+ the history file, by calling :c:func:`history_truncate_file` in
+ the underlying library. Negative values imply
+ unlimited history file size.
+
+
+History list
+------------
+
+The following functions operate on a global history list:
.. function:: clear_history()
- Clear the current history. (Note: this function is not available if the
- installed version of GNU readline doesn't support it.)
+ Clear the current history. This calls :c:func:`clear_history` in the
+ underlying library. The Python function only exists if Python was
+ compiled for a version of the library that supports 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
+ Return the number of items 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.)
@@ -91,7 +127,8 @@
.. function:: get_history_item(index)
- Return the current contents of history item at *index*.
+ Return the current contents of history item at *index*. The item index
+ is one-based. This calls :c:func:`history_get` in the underlying library.
.. versionadded:: 2.3
@@ -99,42 +136,63 @@
.. function:: remove_history_item(pos)
Remove history item specified by its position from the history.
+ The position is zero-based. This calls :c:func:`remove_history` in
+ the underlying library.
.. versionadded:: 2.4
.. function:: replace_history_item(pos, line)
- Replace history item specified by its position with the given line.
+ Replace history item specified by its position with *line*.
+ The position is zero-based. This calls :c:func:`replace_history_entry`
+ in the underlying library.
.. versionadded:: 2.4
-.. function:: redisplay()
+.. function:: add_history(line)
- Change what's displayed on the screen to reflect the current contents of the
- line buffer.
+ Append *line* to the history buffer, as if it was the last line typed.
+ This calls :c:func:`add_history` in the underlying library.
+
+
+Startup hooks
+-------------
.. 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
+ Set or remove the function invoked by the :c:data:`rl_startup_hook`
+ callback of the underlying library. If *function* is specified, it will
+ be used as the new hook function; if omitted or ``None``, any function
+ already installed is removed. The hook 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
+ Set or remove the function invoked by the :c:data:`rl_pre_input_hook`
+ callback of the underlying library. If *function* is specified, it will
+ be used as the new hook function; if omitted or ``None``, any
+ function already installed is removed. The hook is called
with no arguments after the first prompt has been printed and just before
readline starts reading input characters.
+Completion
+----------
+
+The following functions relate to implementing a custom word completion
+function. This is typically operated by the Tab key, and can suggest and
+automatically complete a word being typed. By default, Readline is set up
+to be used by :mod:`rlcompleter` to complete Python identifiers for
+the interactive interpreter. If the :mod:`readline` module is to be used
+with a custom completer, a different set of word delimiters should be set.
+
+
.. function:: set_completer([function])
Set or remove the completer function. If *function* is specified, it will be
@@ -144,6 +202,12 @@
returns a non-string value. It should return the next possible completion
starting with *text*.
+ The installed completer function is invoked by the *entry_func* callback
+ passed to :c:func:`rl_completion_matches` in the underlying library.
+ The *text* string comes from the first parameter to the
+ :c:data:`rl_attempted_completion_function` callback of the
+ underlying library.
+
.. function:: get_completer()
@@ -154,50 +218,42 @@
.. function:: get_completion_type()
- Get the type of completion being attempted.
+ Get the type of completion being attempted. This returns the
+ :c:data:`rl_completion_type` variable in the underlying library as
+ an integer.
.. versionadded:: 2.6
.. function:: get_begidx()
+ get_endidx()
- Get the beginning index of the readline tab-completion scope.
-
-
-.. function:: get_endidx()
-
- Get the ending index of the readline tab-completion scope.
+ Get the beginning or ending index of the completion scope.
+ These indexes are the *start* and *end* arguments passed to the
+ :c:data:`rl_attempted_completion_function` callback of the
+ underlying library.
.. function:: set_completer_delims(string)
+ get_completer_delims()
- Set the readline word delimiters for tab-completion.
-
-
-.. function:: get_completer_delims()
-
- Get the readline word delimiters for tab-completion.
+ Set or get the word delimiters for completion. These determine the
+ start of the word to be considered for completion (the completion scope).
+ These functions access the :c:data:`rl_completer_word_break_characters`
+ variable in the underlying library.
.. 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
+ installed is removed. This sets or clears the
+ :c:data:`rl_completion_display_matches_hook` callback in the
+ underlying library. 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
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -184,6 +184,13 @@
installing IDLE 2.7 on OS X: default configuration settings are
no longer installed from OS X specific copies.
+Documentation
+-------------
+
+- Issue #6953: Rework the Readline module documentation to group related
+ functions together, and add more details such as what underlying Readline
+ functions and variables are accessed.
+
Tests
-----
diff --git a/Modules/readline.c b/Modules/readline.c
--- a/Modules/readline.c
+++ b/Modules/readline.c
@@ -96,7 +96,7 @@
PyDoc_STRVAR(doc_parse_and_bind,
"parse_and_bind(string) -> None\n\
-Parse and execute single line of a readline init file.");
+Execute the init line provided in the string argument.");
/* Exported function to parse a readline init file */
@@ -115,7 +115,7 @@
PyDoc_STRVAR(doc_read_init_file,
"read_init_file([filename]) -> None\n\
-Parse a readline initialization file.\n\
+Execute a readline initialization file.\n\
The default filename is the last filename used.");
@@ -176,7 +176,7 @@
PyDoc_STRVAR(set_history_length_doc,
"set_history_length(length) -> None\n\
-set the maximal number of items which will be written to\n\
+set the maximal number of lines which will be written to\n\
the history file. A negative length is used to inhibit\n\
history truncation.");
@@ -191,7 +191,7 @@
PyDoc_STRVAR(get_history_length_doc,
"get_history_length() -> int\n\
-return the maximum number of items that will be written to\n\
+return the maximum number of lines that will be written to\n\
the history file.");
@@ -269,7 +269,7 @@
PyDoc_STRVAR(doc_set_startup_hook,
"set_startup_hook([function]) -> None\n\
-Set or remove the startup_hook function.\n\
+Set or remove the function invoked by the rl_startup_hook callback.\n\
The function is called with no arguments just\n\
before readline prints the first prompt.");
@@ -286,7 +286,7 @@
PyDoc_STRVAR(doc_set_pre_input_hook,
"set_pre_input_hook([function]) -> None\n\
-Set or remove the pre_input_hook function.\n\
+Set or remove the function invoked by the rl_pre_input_hook callback.\n\
The function is called with no arguments after the first prompt\n\
has been printed and just before readline starts reading input\n\
characters.");
@@ -325,7 +325,7 @@
PyDoc_STRVAR(doc_get_begidx,
"get_begidx() -> int\n\
-get the beginning index of the readline tab-completion scope");
+get the beginning index of the completion scope");
/* Get the ending index for the scope of the tab-completion */
@@ -339,7 +339,7 @@
PyDoc_STRVAR(doc_get_endidx,
"get_endidx() -> int\n\
-get the ending index of the readline tab-completion scope");
+get the ending index of the completion scope");
/* Set the tab-completion word-delimiters that readline uses */
@@ -368,7 +368,7 @@
PyDoc_STRVAR(doc_set_completer_delims,
"set_completer_delims(string) -> None\n\
-set the readline word delimiters for tab-completion");
+set the word delimiters for completion");
/* _py_free_history_entry: Utility function to free a history entry. */
@@ -408,7 +408,7 @@
int entry_number;
HIST_ENTRY *entry;
- if (!PyArg_ParseTuple(args, "i:remove_history", &entry_number))
+ if (!PyArg_ParseTuple(args, "i:remove_history_item", &entry_number))
return NULL;
if (entry_number < 0) {
PyErr_SetString(PyExc_ValueError,
@@ -438,7 +438,7 @@
char *line;
HIST_ENTRY *old_entry;
- if (!PyArg_ParseTuple(args, "is:replace_history", &entry_number,
+ if (!PyArg_ParseTuple(args, "is:replace_history_item", &entry_number,
&line)) {
return NULL;
}
@@ -479,7 +479,7 @@
PyDoc_STRVAR(doc_add_history,
"add_history(string) -> None\n\
-add a line to the history buffer");
+add an item to the history buffer");
/* Get the tab-completion word-delimiters that readline uses */
@@ -492,7 +492,7 @@
PyDoc_STRVAR(doc_get_completer_delims,
"get_completer_delims() -> string\n\
-get the readline word delimiters for tab-completion");
+get the word delimiters for completion");
/* Set the completer function */
@@ -553,7 +553,7 @@
int idx = 0;
HIST_ENTRY *hist_ent;
- if (!PyArg_ParseTuple(args, "i:index", &idx))
+ if (!PyArg_ParseTuple(args, "i:get_history_item", &idx))
return NULL;
#ifdef __APPLE__
if (using_libedit_emulation) {
@@ -645,7 +645,7 @@
PyDoc_STRVAR(doc_insert_text,
"insert_text(string) -> None\n\
-Insert text into the command line.");
+Insert text into the line buffer at the cursor position.");
/* Redisplay the line buffer */
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list