Mailman 3 April 2011 - docs

[issue9767] Failures in json doc examples
by Terry J. Reedy 27 Oct '12

27 Oct '12

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: I ran doctest on LibRef 17.2 json saved as .txt. There are 4 failures: 2 are clearly doc issues, the other 2 I do not know. I hope someone reads this who is already familiar DOC PATCHES dumps(2 + 1j, cls=ComplexEncoder) should be json.dumps(2 + 1j, cls=ComplexEncoder) and JSONEncoder().encode({"foo": ["bar", "baz"]}) should be json.JSONEncoder().encode({"foo": ["bar", "baz"]}) Needing similar additions in example code (not caught by doctest) are return JSONEncoder.default(self, o) for chunk in JSONEncoder().iterencode(bigobject): Those fixes leave 2 failures I an unclear about and hope a json expert will comment on. 1.''' Failed example: print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)) Expected: { "4": 5, "6": 7 } Got: { "4": 5, "6": 7 } ''' The difference is that json puts a trailing space after '5,'. Should it? or should one be added to the doc? 2. ''' Failed example: list(ComplexEncoder().iterencode(2 + 1j)) Expected: ['[', '2.0', ', ', '1.0', ']'] Got: ['[2.0', ', 1.0', ']'] ''' Without knowing how the default iterencode interacts with the overwridden .default() method, I have no idea. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 115512 nosy: docs@python, terry.reedy priority: normal severity: normal status: open title: Failures in json doc examples type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9767> _______________________________________

3 4

[issue11160] ZipFile.comment expects bytes
by Xuanji Li 25 Oct '12

25 Oct '12

New submission from Xuanji Li <xuanji(a)gmail.com>: The documentation for zipfile describes ZipFile.comment as "The comment text associated with the ZIP file." From reading this I expect that setting it to a string is ok; however ZipFile.comment must actually be set to bytes (or a bytes-like object, I am not very sure). This may also unexpectedly affect old code because I saw one patch on the bug tracker that was written just last year that set ZipFile.comment to a string. IMO there are 2 ways to fix: 1) Change docs to mention that ZipFile.comment only accepts bytes 2) Patch zipfile.py to accept string and try to convert, throwing an error if the conversion fails ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 128217 nosy: docs@python, haypo, xuanji priority: normal severity: normal status: open title: ZipFile.comment expects bytes versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11160> _______________________________________

4 4

[issue10405] IDLE breakpoint facility undocumented
by Ned Deily 21 Oct '12

21 Oct '12

New submission from Ned Deily <nad(a)acm.org>: In neither the IDLE section of the Library Reference nor in IDLE's own help file is there any documentation on how to use its breakpoint capability. Since the menu options only appear if the user knows to Right-click (or Control-click on OS X - see issue10404), it would be easy for a user to never realize that the breakpoint capability exists. ---------- assignee: docs@python components: Documentation, IDLE messages: 121121 nosy: docs@python, kbk, ned.deily, taleinat, terry.reedy priority: normal severity: normal status: open title: IDLE breakpoint facility undocumented versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10405> _______________________________________

5 9

[issue11710] Landing pages in docs for standard library packages
by Nick Coghlan 06 Oct '12

06 Oct '12

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: http://docs.python.org/py3k/urllib errors out rather than returning an index page for the modules that are part of the urllib package. This index page could also link to the HOWTO at http://docs.python.org/py3k/howto/urllib2.html The following packages have the same problem: xml, http, xmlrpc, concurrent These ones look OK: logging, curses, html, tkinter These index pages don't necessarily need to be linked from the contents page, but they should exist so that manually typed URLs for these packages do something useful rather than erroring out with a 404. ---------- assignee: docs@python components: Documentation messages: 132481 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Landing pages in docs for standard library packages versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11710> _______________________________________

6 9

[issue10665] Update and expand unicodedata module documentation
by Alexander Belopolsky 27 Sep '12

27 Sep '12

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: unicodedata module documentation has not been updated to reflect transition to 6.0. Attached patch fixes the version and unicode.org links and starts making the documentation rely less on the unicode.org pages for basic understanding of the provided functionality. I am posting work in progress to solicit feedback on how much of the Unicode Standard information we would want to present here. On of the goals of this patch is to provide a standard reference that can be used throughout the library manual for basic Unicode concepts without sending the reader over to unicode.org. ---------- assignee: docs@python components: Documentation files: unicodedata-doc.diff keywords: patch messages: 123700 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: Update and expand unicodedata module documentation versions: Python 3.2 Added file: http://bugs.python.org/file19990/unicodedata-doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10665> _______________________________________

6 25

[issue11964] Undocumented change to indent param of json.dump in 3.2
by Éric Araujo 28 Aug '12

28 Aug '12

New submission from Éric Araujo <merwok(a)netwok.org>: I found out that the indent parameter of json.dump was changed in 3.2: it can be a string as well as an int. The docstring was not updated; the reST doc was, but without a versionchanged directive. This probably applies to the doc and docstring of the classes implementing dump, too, and there may be other half-documented changes. ---------- assignee: docs@python components: Documentation, Library (Lib) keywords: easy messages: 134869 nosy: bob.ippolito, docs@python, eric.araujo, rhettinger priority: normal severity: normal stage: needs patch status: open title: Undocumented change to indent param of json.dump in 3.2 versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11964> _______________________________________

7 14

[issue11786] ConfigParser.[Raw]ConfigParser optionxform()
by Adam Groszer 07 Jul '12

07 Jul '12

New submission from Adam Groszer <agroszer(a)gmail.com>: The documentation http://docs.python.org/library/configparser.html states that optionxform() is used only beginning ConfigParser.ConfigParser, whereas it is ALSO in effect for ConfigParser.RawConfigParser. (As I checked in the source) ---------- assignee: docs@python components: Documentation messages: 133148 nosy: Adam.Groszer, docs@python priority: normal severity: normal status: open title: ConfigParser.[Raw]ConfigParser optionxform() type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11786> _______________________________________

5 10

[issue10376] ZipFile unzip is unbuffered
by James Hutchison 23 Jun '12

23 Jun '12

New submission from James Hutchison <jamesghutchison(a)gmail.com>: The Unzip module is always unbuffered (tested v.3.1.2 Windows XP, 32-bit). This means that if one has to do many small reads it is a lot slower than reading a chunk of data to a buffer and then reading from that buffer. It seems logical that the unzip module should default to buffered reading and/or have a buffered argument. Likewise, the documentation should clarify that there is no buffering involved when doing a read, which runs contrary to the default behavior of a normal read. start Zipfile read done 27432 reads done took 0.859 seconds start buffered Zipfile read done 27432 reads done took 0.072 seconds start normal read (default buffer) done 27432 reads done took 0.139 seconds start buffered normal read done 27432 took 0.137 seconds ---------- assignee: docs@python components: Documentation, IO, Library (Lib) messages: 120871 nosy: Jimbofbx, docs@python priority: normal severity: normal status: open title: ZipFile unzip is unbuffered type: performance versions: Python 2.5, Python 2.6, Python 2.7, Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10376> _______________________________________

9 17

[issue8652] Minor improvements to the "Handling Exceptions" part of the tutorial
by Marien Zwart 08 Jun '12

08 Jun '12

New submission from Marien Zwart <m_zwart(a)123mail.org>: Based on questions asked on freenode's #python by people reading the tutorial I would like to suggest two improvements to http://docs.python.org/tutorial/errors.html#handling-exceptions : - Mention the older "except SomeException, e:" syntax too, not just "except SomeException as e:". I have had people ask me to help them upgrade to a newer python because they thought their version of python did not support catching exception instances (their distro python being 2.5). A big fat warning that they're reading the Python 2.6 tutorial (with links to older tutorials) may also work. - Mention "except IOError as e" before mentioning "except IOError as (errno, strerror):". The latter is an advanced and relatively unusual trick, combining regular exception catching and unpacking. Those two concepts need to be explained before the combination is. I have had people ask me how to do "except KeyError as (key, insert_something_here):" because they thought they *always* needed those parens there. (perhaps just not mentioning unpacking here at all, using "except IOError as e:" and then using e.errno would make more sense, especially since "except IOError as (errno, strerror):" is a SyntaxError in python 3 and up (because of the unpacking) and python 2.5.x and down (because of the "as")...) I can try to write a patch to the documentation if you like. ---------- assignee: docs@python components: Documentation messages: 105218 nosy: docs@python, marienz priority: normal severity: normal status: open title: Minor improvements to the "Handling Exceptions" part of the tutorial _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8652> _______________________________________

4 6

[issue11785] email subpackages documentation problems
by ysj.ray 28 May '12

28 May '12

New submission from ysj.ray <ysj.ray(a)gmail.com>: All the module name in the first line of email subpackages' documentation files(Doc/library/email.xxx.rst) are incorrect: all of them are "email" but not "email.xxx" Besides, the Doc/library/email-examples.rst is not a module and it uses ":mod:`email`: xxx" ---------- assignee: docs@python components: Documentation files: email_subpackages_document_problems.diff keywords: patch messages: 133143 nosy: docs@python, ysj.ray priority: normal severity: normal status: open title: email subpackages documentation problems versions: Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file21552/email_subpackages_document_problems.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11785> _______________________________________

5 12