Terry J. Reedy <tjre...@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 <rep...@bugs.python.org>
<http://bugs.python.org/issue10225>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

Reply via email to