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