classification
Title: readline.insert_text documentation incomplete
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Justin.Lebar, berker.peksag, docs@python, eric.araujo, martin.panter, matheus.v.portela
Priority: normal Keywords:

Created on 2010-11-14 07:12 by Justin.Lebar, last changed 2016-10-01 00:02 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
test_readline.py matheus.v.portela, 2014-03-12 02:42 Using readline.insert_text() to print some string on screen
Messages (8)
msg121178 - (view) Author: Justin Lebar (Justin.Lebar) Date: 2010-11-14 07:12
The readline documentation currently says:

> readline.insert_text(string)
>     Insert text into the command line.

But as far as I can tell, readline.insert_text() does something only when called from startup_hook or pre_input_hook.

Here's an example of someone using the module in a way that works:

http://swapoff.org/svn/cly/tags/0.7/cly/interactive.py
msg121179 - (view) Author: Justin Lebar (Justin.Lebar) Date: 2010-11-14 07:14
Actually, maybe startup_hook doesn't do what it sounds like it does and insert_text() only works from startup_hook.

If this is the case, then the documentation for startup_hook could also be improved:

> The startup_hook function is called with no arguments just before 
> readline prints the first prompt.
msg124655 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-26 01:44
Hi Justin, thanks for the report and patch.  Would you like to turn your suggestion into a patch?  Guidelines are at http://www.python.org/dev/patches/
msg212765 - (view) Author: Matheus Vieira Portela (matheus.v.portela) * Date: 2014-03-05 17:38
Apparently, the documentation was already changed to reflect the behaviour of startup_hook.

Should this issue be closed?
msg212767 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-03-05 18:41
Documentations of insert_test and set_startup_hook functions are unchanged since 2007. See revision 9e1529bf0442 (warning, huge diff!).
msg213194 - (view) Author: Matheus Vieira Portela (matheus.v.portela) * Date: 2014-03-12 02:42
I could get readline.insert_text() to work, ish, without calling startup_hook. The script is attached to this message. Apparently, there is some need to call readline.redisplay() to update what's on screen.

However, I can't really understand what's happening... The script prints "Testing text" only when the input has exactly one character. Also, by calling redisplay() after insert_text(), the string is not on the command line buffer, but already printed on screen. I should take a look on the GNU Readline Library documentation to understand better how it works.

Anyway, I still think the documentation is unclear on these behaviours and should be updated.
msg268971 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-21 05:52
In Issue 6953, I updated the documentation to indicate which underlying Readline functions etc are accessed. So perhaps that helps, so the reader knows what function to look up in the Readline documentation.

Other than that, I’m not sure what else to do. It would be more helpful to suggest an improvement, rather than just quoting the existing documentation back.
msg277785 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-10-01 00:02
I agree with Martin. Closing this as 'out of date' for now, but we can reopen if you could provide more information. Thanks!
History
Date User Action Args
2016-10-01 00:02:51berker.peksagsetstatus: pending -> closed
type: behavior
messages: + msg277785

resolution: out of date
stage: needs patch -> resolved
2016-06-21 05:52:48martin.pantersetstatus: open -> pending

nosy: + martin.panter
messages: + msg268971

stage: needs patch
2014-03-12 02:42:24matheus.v.portelasetfiles: + test_readline.py

messages: + msg213194
2014-03-05 18:41:52berker.peksagsetnosy: + berker.peksag

messages: + msg212767
versions: + Python 3.3, Python 3.4, - Python 3.1, Python 3.2
2014-03-05 17:38:55matheus.v.portelasetnosy: + matheus.v.portela
messages: + msg212765
2010-12-26 01:44:30eric.araujosetnosy: + eric.araujo

messages: + msg124655
versions: + Python 2.7, Python 3.2
2010-11-14 07:14:44Justin.Lebarsetmessages: + msg121179
2010-11-14 07:12:13Justin.Lebarcreate