Mailman 3 January 2011 - docs

[issue10225] Fix doctest runable examples in python manual
by Alexander Belopolsky 12 Jan '11

12 Jan '11

Alexander Belopolsky <belopolsky(a)users.sourceforge.net> added the comment: I have updated Sphinx and rerun py3k doctests. It looks like the newest Sphinx does not check examples unless the file has a .. testsetup:: directive somewhere. This is nice because it focuses on the files that are clearly intended to be doctest-checked. Of course, there are many perfectly good code examples that are now skipped, but this can be addressed in the next step. I am attaching a patch that makes the following command succeed in py3k Doc directory: $ sphinx-build --version Sphinx v1.1pre .. $ sphinx-build -b doctest -d build/doctrees . build/doctest .. Doctest summary =============== 581 tests 0 failures .. Most of the changes in issue10225-py3k.diff are non-controvercial with the exception of code fixes in collections and difflib. In collections, I removed trailing whitespace from generated namedtuple code and in difflib I changed get_close_matches() return value from map object to a list. I would appreciate comments on these two changes. ---------- Added file: http://bugs.python.org/file20375/issue10225-py3k.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10225> _______________________________________

1 0

[issue10225] Fix doctest runable examples in python manual
by Raymond Hettinger 12 Jan '11

12 Jan '11

Changes by Raymond Hettinger <rhettinger(a)users.sourceforge.net>: ---------- assignee: belopolsky -> rhettinger _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10225> _______________________________________

1 0

[issue10225] Fix doctest runable examples in python manual
by Terry J. Reedy 12 Jan '11

12 Jan '11

Terry J. Reedy <tjreedy(a)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(a)bugs.python.org> <http://bugs.python.org/issue10225> _______________________________________

2 1

[issue10225] Fix doctest runable examples in python manual
by Raymond Hettinger 12 Jan '11

12 Jan '11

Raymond Hettinger <rhettinger(a)users.sourceforge.net> added the comment: You're welcome to discuss this with me on IRC at some point. For now, the important thing is that I put a good deal of time and effort working on the sorting howto and I like it as it stands (your notions of precedent or consistency not withstanding). ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10225> _______________________________________

1 0

[issue10225] Fix doctest runable examples in python manual
by Raymond Hettinger 12 Jan '11

12 Jan '11

Raymond Hettinger <rhettinger(a)users.sourceforge.net> added the comment: Terry, I'm unhappy with the changes to the sorting how-to. IMO, it was a not a net win (transforming code that already ran fine in something doctest would swallow). The code snippets now have the visual clutter of the ">>>" and "..." PS1 and PS2 prompts and they can no longer be readily cut and pasted into the interpreter so that people can experiment with them. ---------- nosy: +rhettinger _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10225> _______________________________________

1 0

[issue4395] Document auto __ne__ generation; provide a use case for non-trivial __ne__
by Éric Araujo 12 Jan '11

12 Jan '11

Changes by Éric Araujo <merwok(a)netwok.org>: ---------- nosy: +docs@python -georg.brandl stage: -> needs patch type: -> behavior versions: +Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue4395> _______________________________________

1 0

[issue10885] multiprocessing docs
by Éric Araujo 12 Jan '11

12 Jan '11

Changes by Éric Araujo <merwok(a)netwok.org>: ---------- nosy: +asksol, jnoller _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10885> _______________________________________

1 0

[issue7057] tkinter doc: more 3.x updates
by Éric Araujo 11 Jan '11

11 Jan '11

Éric Araujo <merwok(a)netwok.org> added the comment: > I used 'manN' FYI, there is a :file:`man{n}` construct where braces mark up replaceable text, like the var element in HTML. ---------- nosy: +docs@python, eric.araujo -georg.brandl _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7057> _______________________________________

1 0

[issue10225] Fix doctest runable examples in python manual
by Terry J. Reedy 11 Jan '11

11 Jan '11

Terry J. Reedy <tjreedy(a)udel.edu> added the comment: Doctest runs on .rst files, which are plain text files, finds and reports errors, and reports no errors when the errors are fixed. See #10875 where is was very helpful. So your last comment puzzles me. In any case, your patch is too big to digest at once. I extracted the part for howto/sorting.rst and tried to apply to 3.2, but the file has changed too much (at least for TortoiseSVN). So I pasted the '... 's (and adjusted spacing) where needed, and did the two other changes you had. This left just two failures -- for the 2.7 code using 'cmp=xxx' args. With '# doctest: +SKIP' added twice, doctest passes. Patch commited for 3.2 as r87946. > instances when human and computer reader's interests are in conflict. What is one (or more) that you were thinking of? ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10225> _______________________________________

2 1

[issue7229] Manual entry for time.daylight can be misleading
by anatoly techtonik 11 Jan '11

11 Jan '11

anatoly techtonik <techtonik(a)gmail.com> added the comment: Classic user developer impedance mismatch. =) I agree that Python should guard its users against crazy standards that creep into standard lib, because nobody had time to think about pythonic API. I propose the following change: http://docs.python.org/library/time.html#time.altzone - UTC offset of the local DST timezone if one is defined. Only use this if daylight is nonzero. + UTC offset of the current timezone with Daylight Savings Time (DST) correction. To check if DST is currently active, use `time.localtime(t).tm_isdst` http://docs.python.org/library/time.html#time.daylight - Nonzero if a DST timezone is defined. + Flag indicating that current timezone has Daylight Savings Time (DST) offset. To check if DST is currently active, use `time.localtime(t).tm_isdst` http://docs.python.org/library/time.html#time.timezone - UTC offset of the local (non-DST) timezone + UTC offset of the current timezone. It doesn't include Daylight Savings Time (DST) correction. See `time.altzone` for that. BTW, isn't the following check redundant? if time.localtime(t).tm_isdst and time.daylight: ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________

2 3