[docs] [issue10225] Fix doctest runable examples in python manual

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

There are two reasons I forward ported the changes.

1. Without running doctest on doc examples, they sometimes have errors either originally, after patches to the doc, or after patches to Python. On other issues, I found 4 errors in the json doc (probably original; my fixes were augmented and committed by GB, I believe), and several in the re howto (due to non-update after re changes). There have been other error reports on the tracker and I presume more (other than missing '...') shown in AB's patch. (I just started with the first file changed in the patch.) So I thought it pretty well settled that getting doc examples correct (and test-ready) is be a good idea.

2. Examples with output always start with '>>> ' to differentiate input from output. I thought it pretty standard that continuation lines start with '... '. This is true of all applicable examples in re howto, module chapters for difflib, json, bisect, and 4 of 5 applicable examples in the Built-in Types chapter. Other chapters for binhex, itertools, and tkinter have no multiline interactive examples, so provide no precedent either way.

What is the alternative? The current sorting howto is not consistent:

For some examples, '... ' is just deleted:
>>> student_tuples = [
    ('john', 'A', 15),
    ('jane', 'B', 12),
    ('dave', 'B', 10),
]

For others, '... ' is replaced with '    ':
>>> class Student:
        def __init__(self, name, grade, age):
            self.name = name
            self.grade = grade
            self.age = age

The cmp_to_key function def is a special case: there is no output in the same box with the def and so (normally) should not have prompts. The only reason I followed AB's patch here and added them is because the definition is used in the next box. If the next example were changed for 3.2 to use the new-in-3.2  functools.cmp_to_key(), then the def would not be needed.  (I already planned to suggest thisOr the followup example could just be marked SKIP. With either change, I would remove the prompts added to this function, which are the ones I presume bother you the most.


Summary: according to my current (and subject-to-update ;-) understanding of precedent and policy, the changes other than for cmp_to_key seem correct. The rationale for cmp_to_key changes could easily be negated, in which case they should be reverted.

I will put my thoughts on cut-and-paste in a separate message.

----------
nosy: +georg.brandl

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10225>
_______________________________________