Mailman 3 March 2011 - 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

[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

[issue10376] ZipFile unzip is unbuffered
by James Hutchison June 23, 2012

June 23, 2012

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 June 8, 2012

June 8, 2012

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

[issue8617] Non-existent variables documented
by Dave Abrahams May 9, 2012

May 9, 2012

New submission from Dave Abrahams <dave(a)boostpro.com>: http://docs.python.org/library/site.html#module-site mentions two variables that don't appear in my Python 2.6.5 installation's site module: PYTHONNOUSERSITE New in version 2.6. PYTHONUSERBASE New in version 2.6. ---------- assignee: docs@python components: Documentation messages: 104985 nosy: dabrahams, docs@python priority: normal severity: normal status: open title: Non-existent variables documented versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8617> _______________________________________

6 13

[issue10423] s/args/options in arpgarse "Upgrading optparse code"
by Steven Bethard March 30, 2012

March 30, 2012

New submission from Steven Bethard <steven.bethard(a)gmail.com>: >From a personal email: ---------------------------------------------------------------------- I'm not signed up for all the Python issue tracking stuff, but thought I'd let you know about a problem with the argparse doc page: http://docs.python.org/library/argparse.html It says at the end: Replace options, args = parser.parse_args() with args = parser.parse_args() and add additional ArgumentParser.add_argument() calls for the positional arguments. But I think it should be options = parser.parse_args(), not args. ---------------------------------------------------------------------- They're not options, so I don't like encouraging people to continue to call them options, but the docs should at least make clear that the namespace object that used to be called "options" is now called "args". ---------- assignee: docs@python components: Documentation messages: 121219 nosy: bethard, docs@python priority: normal severity: normal stage: needs patch status: open title: s/args/options in arpgarse "Upgrading optparse code" versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10423> _______________________________________

5 8

[issue11310] Document byte[s|array]() and byte[s|array](count) in docstrings
by Terry J. Reedy March 30, 2012

March 30, 2012

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: The entry for bytearray(source...) says " The optional source parameter can be used to initialize the array in a few different ways: ... If it is an integer, the array will have that size and will be initialized with null bytes. ... Without an argument, an array of size 0 is created. " [integer must be non-negative -- patch adds this] The entry for bytes(source...) refers back to the bytearray entry. The docstrings for bytes and bytearray omit both possibilities. Attached is a possible patch to include them. ---------- assignee: docs@python components: Documentation files: zbytes.diff keywords: patch messages: 129299 nosy: docs@python, terry.reedy priority: normal severity: normal status: open title: Document byte[s|array]() and byte[s|array](count) in docstrings versions: Python 3.2, Python 3.3 Added file: http://bugs.python.org/file20877/zbytes.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11310> _______________________________________

3 2

[issue10713] re module doesn't describe string boundaries for \b
by Ralph Corderoy Feb. 29, 2012

Feb. 29, 2012

New submission from Ralph Corderoy <ralph-pythonbugs(a)inputplus.co.uk>: The re module defines \b in a regexp to need \w one side and \W the other. What about when the end of the string or line is involved? perlre(1) says that's treated as a \W. Python should precisely document that case too. ---------- assignee: docs@python components: Documentation messages: 124097 nosy: docs@python, ralph.corderoy priority: normal severity: normal status: open title: re module doesn't describe string boundaries for \b _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10713> _______________________________________

6 9

[issue9442] Update sys.version doc
by Éric Araujo Feb. 10, 2012

Feb. 10, 2012

New submission from Éric Araujo <merwok(a)netwok.org>: Attaching a patch to edit mention of “build number” in library/sys. I also don’t understand “The first three characters are used to identify the version in the installation directories (where appropriate on each platform)”, maybe someone who does could enlighten me. If #5778 is rejected, the doc will need another update to mention that there may be a newline in sys.version. ---------- assignee: docs@python components: Documentation files: sys.version1.diff keywords: patch messages: 112189 nosy: docs@python, merwok priority: normal severity: normal stage: patch review status: open title: Update sys.version doc versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file18289/sys.version1.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9442> _______________________________________

4 9

[issue9021] no copy.copy problem description
by anatoly techtonik Feb. 9, 2012

Feb. 9, 2012

New submission from anatoly techtonik <techtonik(a)gmail.com>: `copy` module covers very important aspect of Python programming. However its documentation doesn't provide any intro or overview of this problem starting right from details. When people meet `copy` construction in the code - the refer to module documentation and its doesn't completely answer two basic questions they have: 1. why copy module is needed (i.e. what's the problem with var assignment) 2. when and where it should be used ---------- assignee: docs@python components: Documentation messages: 108069 nosy: docs@python, techtonik priority: normal severity: normal status: open title: no copy.copy problem description versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9021> _______________________________________

5 10

[issue9637] docs do not say that urllib uses HTTP_PROXY
by Kirikaza Jan. 10, 2012

Jan. 10, 2012

New submission from Kirikaza <kirikaza(a)rambler.ru>: In practice urllib reads HTTP_PROXY firstly and then if HTTP_PROXY is empty urllib reads http_proxy. Documentation (http://docs.python.org/library/urllib.html) says nothing about HTTP_PROXY. Maybe it affects all the versions of Python. ---------- assignee: docs@python components: Documentation messages: 114319 nosy: docs@python, kirikaza priority: normal severity: normal status: open title: docs do not say that urllib uses HTTP_PROXY versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9637> _______________________________________

5 11

[issue10772] Several actions for argparse arguments missing from docs
by ipatrol Jan. 4, 2012

Jan. 4, 2012

New submission from ipatrol <ipatrol6010(a)yahoo.com>: I actually noticed this while trying to free the -h option for my program. The actions not mentioned are count, help, and parsers. Also for nargs, '...' and 'A...' are not documented either in the Sphinx docs or the leading docstring for the Action class. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 124654 nosy: docs@python, ipatrol priority: normal severity: normal status: open title: Several actions for argparse arguments missing from docs type: behavior versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10772> _______________________________________

9 17

[issue9349] document argparse's help=SUPPRESS
by Steven Bethard Jan. 3, 2012

Jan. 3, 2012

New submission from Steven Bethard <steven.bethard(a)gmail.com>: Argparse supports silencing help for certain options using SUPPRESS. >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', help=argparse.SUPPRESS) >>> parser.print_help() usage: [-h] optional arguments: -h, --help show this help message and exit This should be documented in the description of help= http://docs.python.org/library/argparse.html#help ---------- assignee: docs@python components: Documentation messages: 111320 nosy: bethard, docs@python priority: normal severity: normal status: open title: document argparse's help=SUPPRESS versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9349> _______________________________________

3 2

[issue11231] bytes() constructor is not correctly documented
by STINNER Victor Dec. 17, 2011

Dec. 17, 2011

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: There are 5 different usages of the bytes() constructor: 1) bytes(iterable_of_ints) -> bytes 2) bytes(string, encoding[, errors]) -> bytes 3) bytes(bytes_or_buffer) -> immutable copy of bytes_or_buffer 4) bytes(memory_view) -> bytes 5) bytes(int) <=> b'\0' * size The docstring describes the four first usages, the documentation only (3). http://docs.python.org/dev/library/functions.html#bytes Note: bytes(3) accepts 2 other arguments, but I don't think that they are used: bytes(3, 'unused encoding', 'unused errors'). ---------- assignee: docs@python components: Documentation messages: 128739 nosy: docs@python, haypo priority: normal severity: normal status: open title: bytes() constructor is not correctly documented versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11231> _______________________________________

6 9

[issue8646] PyUnicode_EncodeDecimal is undocumented
by Daniel Stutzbach Nov. 22, 2011

Nov. 22, 2011

New submission from Daniel Stutzbach <daniel(a)stutzbachenterprises.com>: PyUnicode_EncodeDecimal is undocumented (although it's referenced in passing in the documentation for PyLong_FromUnicode). There's a lengthy comment in unicodeobject.h describing PyUnicode_EncodeDecimal, which could be converted more or less directly into documentation. ---------- assignee: docs@python components: Documentation messages: 105205 nosy: docs@python, stutzbach priority: normal severity: normal stage: needs patch status: open title: PyUnicode_EncodeDecimal is undocumented versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8646> _______________________________________

4 6

[issue10526] Minor typo in What's New in Python 2.7
by Petter Remen Oct. 9, 2011

Oct. 9, 2011

New submission from Petter Remen <petter.remen(a)gmail.com>: There's a word missing in section "PEP 372: Adding an Ordered Dictionary to collections" The ConfigParser module uses them by default, meaning that configuration files can now read, modified, and then written [...] ~~~~~~~~ should be "now be read". ---------- assignee: docs@python components: Documentation messages: 122347 nosy: Petter.Remen, docs@python priority: normal severity: normal status: open title: Minor typo in What's New in Python 2.7 versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10526> _______________________________________

3 2

[issue11155] multiprocessing.Queue's put() signature differs from docs
by Erik Cederstrand Sept. 5, 2011

Sept. 5, 2011

New submission from Erik Cederstrand <ec(a)1calendar.dk>: In Python 2.6.6 on OSX: >>> import inspect >>> from multiprocessing import Queue >>> q = Queue() >>> print(inspect.getargspec(q.put)) ArgSpec(args=['self', 'obj', 'block', 'timeout'], varargs=None, keywords=None, defaults=(True, None)) >>> from Queue import Queue >>> q = Queue() >>> print(inspect.getargspec(q.put)) ArgSpec(args=['self', 'item', 'block', 'timeout'], varargs=None, keywords=None, defaults=(True, None)) Notice the 'obj' argument in the multiprocessing version and the 'item' argument in the Queue version. I think 'obj' should be renamed to 'item' to be in line with the other implementation and to agree with the docs: (http://docs.python.org/library/multiprocessing.html?highlight=multiprocessi…): put(item[, block[, timeout]]) ---------- assignee: docs@python components: Documentation messages: 128200 nosy: Erik.Cederstrand, docs@python priority: normal severity: normal status: open title: multiprocessing.Queue's put() signature differs from docs versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11155> _______________________________________

6 14

[issue11360] In documentation of getopt, advertise argparse instead of optparse
by Daniel Haertle Sept. 4, 2011

Sept. 4, 2011

New submission from Daniel Haertle <haertle(a)uni-bonn.de>: At the beginning of http://docs.python.org/dev/library/getopt.html the line "A more convenient, flexible, and powerful alternative is the optparse module." routes the user to optparse. Since optparse is deprecated in favor of argparse, this line is no more up-to-date. The best is to remove this line completely, since there already is a note routing to argparse. ---------- assignee: docs@python components: Documentation messages: 129753 nosy: Danh, docs@python priority: normal severity: normal status: open title: In documentation of getopt, advertise argparse instead of optparse versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11360> _______________________________________

3 4

[issue10454] Clarify compileall options
by Éric Araujo Sept. 2, 2011

Sept. 2, 2011

New submission from Éric Araujo <merwok(a)netwok.org>: This is the help text of compileall: usage: python compileall.py [-l] [-f] [-q] [-d destdir] [-x regexp] [-i list] [directory|file ...] -l: don't recurse down -f: force rebuild even if timestamps are up-to-date -q: quiet operation -d destdir: purported directory name for error messages if no directory arguments, -l sys.path is assumed -x regexp: skip files matching the regular expression regexp the regexp is searched for in the full path of the file -i list: expand list with its content (file and directory names) -b: Produce legacy byte-compile file paths 1) I do not understand the help of -d and -i. Experimenting with the script, reading the code and eventually looking at the file history would certainly clear that. 2) The short usage line at the top also lacks mention of “-b”. 3) (minor) I want to rephrase -x, -d and -b. Bug week-end candidate! ---------- assignee: docs@python components: Documentation keywords: easy messages: 121469 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Clarify compileall options type: behavior versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10454> _______________________________________

4 11

[issue11435] Links to source code should now point to hg repo
by SilentGhost Aug. 31, 2011

Aug. 31, 2011

New submission from SilentGhost <ghost.adh(a)gmail.com>: With the conversion to mercurial source links in documentation should now point to hg.python.org Here is the patch. ---------- assignee: docs@python components: Documentation files: docs_sourcename.diff keywords: patch messages: 130268 nosy: SilentGhost, docs@python priority: normal severity: normal stage: patch review status: open title: Links to source code should now point to hg repo Added file: http://bugs.python.org/file21033/docs_sourcename.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11435> _______________________________________

8 25

[issue9302] Distutils document problem?
by Ray.Allen Aug. 26, 2011

Aug. 26, 2011

New submission from Ray.Allen <ysj.ray(a)gmail.com>: The distutils api document for class Extension: http://docs.python.org/dev/py3k/distutils/apiref.html#distutils.core.Extens… Among the argument, in fact, the type of the arguments "sources", "include_dirs", "library_dirs", "libraries", "runtime_library_dirs" must be list, but all of them are marked as "string". I think this is a problem. Here is a patch for this, against py3k. ---------- assignee: docs@python components: Documentation files: distutils_apiref.diff keywords: patch messages: 110724 nosy: docs@python, ysj.ray priority: normal severity: normal status: open title: Distutils document problem? versions: Python 3.2 Added file: http://bugs.python.org/file18061/distutils_apiref.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________

5 18

General FAQ - How Stable, rewording
by Regis Frey Aug. 20, 2011

Aug. 20, 2011

http://docs.python.org/faq/general.html#how-stable-is-python "Python 2 code will generally not run unchanged in Python 3." would read more clearly as "Python 2 code often requires changes to run in Python 3." -- Regis Frey darkfirestudios.com

2 1

Suggested improvement for Python Tutorial part 7.2 - 'Reading and writing files'
by Mark Ballard Aug. 20, 2011

Aug. 20, 2011

Hello May I, a mere beginner, be so bold as to suggest a modification of your excellent Python Tutorial? I think certain modifications of section 7.2 ( http://docs.python.org/tutorial/inputoutput.html) would be of great assistance to beginners. First of all, the order in which the different file operations are presented could be changed for greater comprehension. Section 7.2 begins the beginners' introduction to file objects (after a quick introduction to opening/creating files) by giving a rather sizable description of read functions, with examples. Since the beginner at this stage hasn't learned the first thing about writing to files, she is unlikely to have any test files on which to perform the given read functions. This section on reading files is therefore redundant until the beginner has got to the section further on that describes how to write files, after which she must return to the start of the section to do the read samples and effectively read the section backwards. It would be more helpful to have the write tutorial before the read tutorial. In addition to this confusion of ordering, I had some trouble following the given read and write examples. Please refer to this example transcript of my attempt to follow the instructions in section 7.2: * STEP 1 - I open a file for reading and writing and write to the file >>> f = open('/tmp/workfile', 'r+') >>> print f <open file '/tmp/workfile', mode 'r+' at 0xb76a31d8> >>> f.read() '' >>> f.write('this is first line of file\n') * STEP 2 - I attempt to read what I've written, but without success >>> f.readline() '' >>> f.readlines() [] * STEP 3 - Bemused, I try writing and reading some more >>> f.write('this is a test') >>> f.readlines() [] * BREAKOUT - Unable to find any explanation in 7.2 I go for help elsewhere After some time, I find it in the Python Tutor mail list (here: http://mail.python.org/pipermail/tutor/2003-July/024154.html) * STEP 4 - Using f.close() I successfully read what I've written But only one of my previously written lines is there >>> f.close() >>> f = open('/tmp/workfile', 'r+') >>> f.readlines() ['this is first line of file\n'] * STEP 5 - Bemused, I try writing another line And use the knowledge gleaned from the Python Tutor Mail list to reset the file pointer >>> f.write('this is second line\n') >>> f.readlines() [] >>> f.seek(0) >>> f.readlines() ['this is first line of file\n'] * STEP 6 - But where are the other lines I've written? >>> f.readlines() [] * STEP 7 - Bemused, I write yet another line to the file, reset the pointer and read it back >>> f.write('this is what where?\n') >>> f.seek(0) >>> f.readlines() ['this is first line of file\n', 'this is what where?\n'] >>> For what to me is an inexplicable reason, my last attempt at writing to this file seemed to be successful: it read back. But all my previous attempts to write a second line have been lost in the ether. Now I'm sure I'll work this out eventually. But perhaps the tutorial could clarify some of these points. I would like to suggest that one way to improve 7.2 would be to include at the beginning of the section, after a simple introduction of write and read with basic one line examples, a description of the file pointer and why its important in reading back what one has written. It may then use multiple line writes and reads to demonstrate how these differ. And perhaps then some word on these phantom writes? Kind regards Mark.

2 1

Broken link in Python manual
by Łukasz Czerwiński Aug. 19, 2011

Aug. 19, 2011

Hello, In the beginning of http://docs.python.org/library/xmlrpclib.html#multicall-objects there is a broken link in sentence: > > In http://www.xmlrpc.com/discuss/msgReader%241208, an approach is > presented to encapsulate multiple calls to a remote server into a single > request. Best wishes, Łukasz Czerwiński

2 2