Mailman 3 February 2012 - docs

[issue10405] IDLE breakpoint facility undocumented
by Ned Deily Oct. 20, 2012

Oct. 20, 2012

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

[issue12947] Examples in library/doctest.html lack the flags
by Éric Araujo Oct. 11, 2012

Oct. 11, 2012

New submission from Éric Araujo <merwok(a)netwok.org>: The docs for the doctest module contains examples that use doctest flags to control behavior, but the HTML version does not contain the flags, making the examples useless. I don’t know if this is a bug with the HTML builder or something we can fix in markup. ---------- assignee: docs@python components: Documentation messages: 143775 nosy: docs@python, eric.araujo, georg.brandl priority: normal severity: normal status: open title: Examples in library/doctest.html lack the flags versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12947> _______________________________________

10 35

[issue11710] Landing pages in docs for standard library packages
by Nick Coghlan Oct. 6, 2012

Oct. 6, 2012

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 Sept. 26, 2012

Sept. 26, 2012

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 Aug. 28, 2012

Aug. 28, 2012

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

[issue12415] Missing: How to checkout the Doc sources
by Philip Olson Aug. 20, 2012

Aug. 20, 2012

New submission from Philip Olson <philip(a)roshambo.org>: I was unable to determine how to download the Python documentation source files (for building via Sphinx) but did figure out the following: hg clone http://hg.python.org/cpython cd cpython/Doc make html Where to get the Doc sources deserves a mention here: http://docs.python.org/dev/documenting/building.html I don't know this topic so won't propose a patch, but building.txt should mention where/how to get 'Doc' before the 'cd Doc' example. ---------- assignee: docs@python components: Documentation messages: 139147 nosy: docs@python, philip priority: normal severity: normal status: open title: Missing: How to checkout the Doc sources _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________

5 20

[issue13799] Base 16 should be hexadecimal in Unicode HOWTO
by Ramchandra Apte Aug. 20, 2012

Aug. 20, 2012

New submission from Ramchandra Apte <maniandram01(a)gmail.com>: "base 16" should be "hexadecimal" in the Unicode HOWTO in both Python 2 and 3 docs. ---------- assignee: docs@python components: Documentation messages: 151354 nosy: docs@python, ramchandra.apte priority: normal severity: normal status: open title: Base 16 should be hexadecimal in Unicode HOWTO type: enhancement versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13799> _______________________________________

7 9

[issue13823] xml.etree.ElementTree.ElementTree.write - argument checking
by patrick vrijlandt July 15, 2012

July 15, 2012

New submission from patrick vrijlandt <patrick.vrijlandt(a)gmail.com>: (1) The docs say: xml_declaration controls if an XML declaration should be added to the file. Use False for never, True for always, None for only if not US-ASCII or UTF-8 or Unicode (default is None). The method also accepts other values, like xml_declaration = "yes". This behavior should be documented, or raise a ValueError (up to effbot, I think) (2) The docs say (in a note): The encoding string included in XML output should conform to the appropriate standards. For example, “UTF-8” is valid, but “UTF8” is not. See http://www.w3.org/ But the method accepts both values, (“UTF-8” and “UTF8”). Since this will result in invalid xml, (but not invalid python) it should probably raise ValueError too. (3) Open issue 9458 also refers to this method. It might be wise to raise ValueError if the encoding does not match the (mode of the) file target (binary or text). ---------- assignee: docs@python components: Documentation, XML messages: 151612 nosy: docs@python, patrick.vrijlandt priority: normal severity: normal status: open title: xml.etree.ElementTree.ElementTree.write - argument checking versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13823> _______________________________________

3 3

[issue13686] Some notes on the docs of multiprocessing
by Eli Bendersky July 13, 2012

July 13, 2012

New submission from Eli Bendersky <eliben(a)gmail.com>: I've decided to study the multiprocessing module a bit, and carefully went over the docs (for 2.7). Some small fixes I will commit myself, but a few issues came up on which I'd like some opinion from others. In rough order of appearance in the doc: 1. In the documentation of the 'name' argument of the multiprocessing.Process constructor, it mentions that the length of the generated name depends on the "generation", without elaborating. It could be better to briefly describe the algorithm in a sentence or two. 2. Section 16.6.2.1. is called "Process and exceptions". It only documents one exception from multiprocessing: BufferTooShort. Other exception classes exported by the module aren't documented similarly: ProcessError, TiemoutError, AuthenticationError. 3. AuthenticationError is documented as multiprocessing.connection.AuthenticationError, although in reality it exists in the root multiprocessing module, and multiprocessing.connection just imports it 4. The doc of JoinableQueue.task_done() says "Used by queue consumer threads". Shouldn't that be "consumer processes"? 5. The doc of active_children() should probably mention that it returns a list of Process objects (similarly to what current_process() says) 6. multiprocessing.freeze_support() says "If the freeze_support() line is omitted then trying to run the frozen executable will raise RuntimeError.". *Who* will raise the error? 7. class multiprocessing.Event says "This method returns..." - what method? Seems like an irrelevant documentation piece was intermixed here 8. 16.6.2.7. Managers starts by saying that Managers provide a way to create data which can be shared between different processes. Since it comes right after the section about Shared objects, I think it would be nice to mention in a sentence or two what Managers give above normal synchonized objects in multiprocessing (i.e. sharing between different machines) 9. In the programming guidelines about "Avoid shared state" it says "It is probably best to stick to using queues or pipes for communication between processes rather than using the lower level synchronization primitives from the threading module.". Surely not the "threading" module is meant here? ---------- assignee: docs@python components: Documentation messages: 150409 nosy: docs@python, eli.bendersky, pitrou priority: normal severity: normal status: open title: Some notes on the docs of multiprocessing type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13686> _______________________________________

4 7

[issue11786] ConfigParser.[Raw]ConfigParser optionxform()
by Adam Groszer July 7, 2012

July 7, 2012

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