classification
Title: readline documenation needs work
Type: enhancement Stage:
Components: Documentation Versions: Python 3.2, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Alexander.Belopolsky, eric.araujo, georg.brandl, ronaldoussoren, stefanholek
Priority: normal Keywords:

Created on 2009-09-20 14:13 by ronaldoussoren, last changed 2010-10-29 10:07 by admin.

Messages (6)
msg92893 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2009-09-20 14:13
The documentation for the readline module is a bit too minimal.

1) function 'add_history' is described at the end of the documentation,
   not near the other functions for manipulation the history stack.

2) the index for remove_history_item and replace_history_item is 0-
based,
   while the index for get_history_item is 1-based.

The latter is a confusing API in the underlying readline library and 
should IMO be described in Python's documentation.

(If readline were a new addition to the stdlib I'd prefer to fix the 
interface, but that would have too many backward compatibility issues at 
this point in time).
msg100466 - (view) Author: Stefan Holek (stefanholek) Date: 2010-03-05 11:28
It is history_base-based, not 1-based. The history_base changes when the history is stifled and old entries "drop off" the list.

http://tiswww.case.edu/php/chet/readline/history.html#IDX36
msg100757 - (view) Author: Stefan Holek (stefanholek) Date: 2010-03-09 21:24
To be zero-based, get_history_item would need to look like:

diff --git a/rl/readline.c b/rl/readline.c
index 33e9905..800bc00 100644
--- a/rl/readline.c
+++ b/rl/readline.c
@@ -559,7 +559,7 @@ get_history_item(PyObject *self, PyObject *args)
 
        if (!PyArg_ParseTuple(args, "i:index", &idx))
                return NULL;
-       if ((hist_ent = history_get(idx)))
+       if ((hist_ent = history_get(history_base + idx)))
                return PyString_FromString(hist_ent->line);
        else {
                Py_RETURN_NONE;
msg100759 - (view) Author: Alexander Belopolsky (Alexander.Belopolsky) Date: 2010-03-09 21:36
On Tue, Mar 9, 2010 at 4:24 PM, stefanholek <report@bugs.python.org> wrote:
..
> To be zero-based, get_history_item would need to look like:
..
> +       if ((hist_ent = history_get(history_base + idx)))

Did you test this with libedit?
msg100762 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2010-03-09 22:00
Changing get_history_item to be 0-based would be a backward incompatible change.

The point of my report is that the documentation of the readline documentation should mention how the APIs actually behave, you currently have to hunt down that information in the documentation from libreadline.

Stefan's message does point to a potentional issue though: history_base is  not exposed to python code, and hence Python code cannot use the correct offset.  I don't understand the documentation for history_get in that same document though, it says "get the item at `offset`, starting from `history_base`". I don't understand if that means that `offset` must be at least `history_base` or something else (and won't read the readline sources to find out).
msg100767 - (view) Author: Stefan Holek (stefanholek) Date: 2010-03-09 22:28
I have read the readline source code, and it does mean just that. :-) 

Anyway, this does not really apply to the stdlib because unless someone implements 'stifle_history' and friends 'history_base' is going to be 1 at all times.
History
Date User Action Args
2010-10-29 10:07:21adminsetassignee: georg.brandl -> docs@python
2010-03-09 22:28:59stefanholeksetmessages: + msg100767
2010-03-09 22:00:30ronaldoussorensetmessages: + msg100762
2010-03-09 21:36:41Alexander.Belopolskysetmessages: + msg100759
2010-03-09 21:24:16stefanholeksetmessages: + msg100757
2010-03-06 20:01:40eric.araujosetnosy: + eric.araujo
2010-03-06 18:07:17Alexander.Belopolskysetnosy: + Alexander.Belopolsky
2010-03-05 11:28:07stefanholeksetnosy: + stefanholek
messages: + msg100466
2009-09-20 14:13:31ronaldoussorencreate