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).

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

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;

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?

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).

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.