Bug in readline module documentation example

[bazwal]

BPO	31537
Nosy	@Mariatta, @infinitewarp
PRs	bpo-31537: Fix bug in readline documentation example code #3925 [3.6] bpo-31537: Update readline documentation example. (GH-3925) #3948

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2017-10-10.22:04:12.494>
created_at = <Date 2017-09-20.20:18:47.693>
labels = ['type-bug', '3.7', 'docs']
title = 'Bug in readline module documentation example'
updated_at = <Date 2017-10-10.22:04:12.492>
user = 'https://bugs.python.org/bazwal'

bugs.python.org fields:

activity = <Date 2017-10-10.22:04:12.492>
actor = 'Mariatta'
assignee = 'docs@python'
closed = True
closed_date = <Date 2017-10-10.22:04:12.494>
closer = 'Mariatta'
components = ['Documentation']
creation = <Date 2017-09-20.20:18:47.693>
creator = 'bazwal'
dependencies = []
files = []
hgrepos = []
issue_num = 31537
keywords = ['patch']
message_count = 5.0
messages = ['302655', '303923', '304088', '304090', '304091']
nosy_count = 4.0
nosy_names = ['bazwal', 'docs@python', 'Mariatta', 'infinitewarp']
pr_nums = ['3925', '3948']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue31537'
versions = ['Python 3.6', 'Python 3.7']

[bazwal]

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

[infinitewarp]

I ran into the same bug in the documentation recently. I've opened a pull request here that fixes it:

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

[Mariatta]

New changeset eeb5ffd by Mariatta (Brad Smith) in branch 'master':
bpo-31537: Update readline documentation example. (GH-3925)
eeb5ffd

[Mariatta]

New changeset 10eb14e by Mariatta (Miss Islington (bot)) in branch '3.6':
bpo-31537: Update readline documentation example. (GH-3925) (GH-3948)
10eb14e

[Mariatta]

Fixed. Thanks!