classification
Title: Bug in readline module documentation example
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Mariatta, bazwal, docs@python, infinitewarp
Priority: normal Keywords: patch

Created on 2017-09-20 20:18 by bazwal, last changed 2017-10-10 22:04 by Mariatta. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 3925 merged infinitewarp, 2017-10-09 02:54
PR 3948 merged python-dev, 2017-10-10 21:54
Messages (5)
msg302655 - (view) Author: bazwal (bazwal) Date: 2017-09-20 20:18
The second example in the readline module docs uses readline.get_history_length() (lines 8 & 14) where it should use readline.get_current_history_length().
msg303923 - (view) Author: Brad Smith (infinitewarp) * Date: 2017-10-09 02:56
I ran into the same bug in the documentation recently. I've opened a pull request here that fixes it:

https://github.com/python/cpython/pull/3925

As I was trying to figure out why the example was broken, I wrote up a little more context to explain the current behavior and the fix:

https://docs.python.org/3.7/library/readline.html#example
https://docs.python.org/3.6/library/readline.html#example

In the "Example" section, the second example that "supports concurrent interactive sessions, by only appending the new history" will actually *never* write any lines to a custom history file. This is conveniently masked by the fact that the file path used in the example code also happens to be the default path that readline automatically writes history to, but if you specify *any* other file path, you will see that the new file is created but never has any content written to it.

The problem in this example is the use of `get_history_length` to get "previous" and "current" history lengths for determining how many lines to append to the file. Both calls to `get_history_length` always return `-1` here. Thus, when `append_history_file` is called, it always receives a first argument of `0` (because `-1 - -1 == 0`), resulting in zero lines written to the file.

Instead of `get_history_length`, the example code *should* call `get_current_history_length`. Swapping that function call makes the example behave as expected, appending new lines to the file.
msg304088 - (view) Author: Mariatta Wijaya (Mariatta) * (Python committer) Date: 2017-10-10 21:52
New changeset eeb5ffd54e56dd89a99c74eb512c36d62649cfec by Mariatta (Brad Smith) in branch 'master':
bpo-31537: Update readline documentation example. (GH-3925)
https://github.com/python/cpython/commit/eeb5ffd54e56dd89a99c74eb512c36d62649cfec
msg304090 - (view) Author: Mariatta Wijaya (Mariatta) * (Python committer) Date: 2017-10-10 22:03
New changeset 10eb14e2c5fe08c4193668530eaef156e07c3674 by Mariatta (Miss Islington (bot)) in branch '3.6':
bpo-31537: Update readline documentation example. (GH-3925) (GH-3948)
https://github.com/python/cpython/commit/10eb14e2c5fe08c4193668530eaef156e07c3674
msg304091 - (view) Author: Mariatta Wijaya (Mariatta) * (Python committer) Date: 2017-10-10 22:04
Fixed. Thanks!
History
Date User Action Args
2017-10-10 22:04:12Mariattasetstatus: open -> closed
versions: - Python 3.5
messages: + msg304091

resolution: fixed
stage: patch review -> resolved
2017-10-10 22:03:16Mariattasetmessages: + msg304090
2017-10-10 21:54:12python-devsetpull_requests: + pull_request3923
2017-10-10 21:52:59Mariattasetnosy: + Mariatta
messages: + msg304088
2017-10-09 02:56:45infinitewarpsetnosy: + infinitewarp
messages: + msg303923
2017-10-09 02:54:14infinitewarpsetkeywords: + patch
stage: patch review
pull_requests: + pull_request3898
2017-09-20 20:18:47bazwalcreate