Andy Maier added the comment: I would like to revive this issue.
>From the discussion, it seems to me that the following changes in the Python >Library documentation would make sense: 1. Move add_history() higher up in the sequence of functions, for example to after write_history_file(). 2. Clarify that the pos arguments of remove_history_item() and replace_history_item() are 0-based. 3. Clarify that the index argument of get_history_item() is 1-based. I do understand Stefan's comment from msg100757 that it is actually 'history_base'-based. On the one hand, history_base is not exposed or implied or even described at the Python level. After searching the GNU readline documentation, it seems that a notion of history base is not described there, either (I may have missed it, though). So either we simply state it is 1-based, or we provide in addition the background story mentioning some notion of history_base that is publicly described. I have the following additional comments: 4. The current documentation is very abridged, probably because it intends to be "just" a description of the Python binding to GNU readline. I think it either needs to evolve into a standalone description (i.e. that does not depend on the description of GNU readline), or it needs to properly reference the description of GNU readline. If we go that route, a simple reference to the document is not sufficient, for one because it is not the only underlying implementation, and second, because it is large and not easy at all to map to the Python readline functions. 5. One needs to understand what the main entities are the module operates on, e.g. init file, history file(s), a (single, global?) history object, the line buffer. Regardless of what we do regarding comment 4., I think the Python docs should describe these main entities in the introduction text. 6. Some more information about the init file is needed. I suspect it is specific to the underlying implementation that is used. If so, add references to the format descriptions for each implementation (by Python OS platform). 7. parse_and_bind(): Change the description to state that it parses and binds the init statement provided in the string argument. That string may or may not come from an init file. The example at the end specifies a statement that is not from an init file. 8. get_line_buffer() talks about "line buffer" and insert_text() talks about "command line". I suspect that means to be the same. If so, use one term consistently. 9. read_init_file(): I suspect it returns a tuple of statements from the init file? In any case, describe how the init file content comes back. Are comments removed? Where is the last filename used remembered, does that survive restarts of the Python runtime? 10. read_history_file(): Add that the history file content is put into a (global?) history object, replacing its prior history. 11. write_history_file(): Add that the (global?) history object is where the information comes from. Is an existing history file replaced? Appended? Exception raised? 12. clear_history(): From the text, I read that if the underlying GNU readline does not support it, this Python function does not exist in the module. If this is not how it works (e.g. if the function exists and raises an exception in the unsupported case), that text should be clarified. Also, mention which version of GNU readline is minimally needed in order to support the function. 13. get_history_length(): It says "get the desired length of the history file", but I think it is really the desired number of lines in the history file (i.e. consistent with set_history_length(). 14. get_history_item() and remove_history_item() talk about "history item", while all other functions talk about "history line" or "line". Use one term consistently. 15. the completion related functions (from set_completer() to set_completion_display_matches_hook()) are really somewhat short: What is the role of a completer function? Which completion types are defined? What is the beginning index of tab-completion? What are word delimiters for tab-completion? 16. Last but not least, the libedit library is mentioned for MacOS. Has that been implemented yet, and is it part of standard Python? If so, mention that. Andy ---------- nosy: +andymaier versions: +Python 3.4, Python 3.5 -Python 3.2 _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue6953> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
