Mailman 3 August 2010 - docs

[issue9677] "Global Module Index" link dead
by Brett Cannon 01 Sep '10

01 Sep '10

New submission from Brett Cannon <brett(a)python.org>: When you build the HTML docs the "Global Module Index" link does not work while the "modules" link in the upper-right corner does. ---------- assignee: docs@python components: Documentation messages: 114832 nosy: brett.cannon, docs@python priority: high severity: normal stage: needs patch status: open title: "Global Module Index" link dead versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9677> _______________________________________

3 2

[issue1397474] timeit execution enviroment
by Terry J. Reedy 31 Aug '10

31 Aug '10

Terry J. Reedy <tjreedy(a)udel.edu> added the comment: I agree that the Timer doc is deficient in not saying that timing is done within a function defined within the timeit module. It is also deficient in not mentioning the secret of how to successfully pass user-defined functions until the very bottom instead of where that option is described. (I had missed this very point until recently.) The discussion of possible new features for 3.2 (more likely later) does not affect 2.7/3.1 and should not stop a change in 3.2 either. I propose that the Timer doc be revised to the following: PROPOSED REPLACEMENT ''' Class for timing execution speed of small code snippets. The constructor creates a function that executes the *setup* statement once and then times some number of executions of the *stmt* statement (see Timer.timeit). Both statements default to 'pass'. The *timer* parameter defaults to a platform-dependent timer function (see the module doc string). Both *stmt* and *setup* may contain multiple statements separated by ; or newlines as long as they don’t contain multi-line string literals. Both *stmt* and *setup* can also be objects that are callable without arguments. Passing testfunc rather than 'testfunc()' may reduce the timing overhead. However, if testfunc is a Python function, passing its quoted code should have even less overhead because doing so eliminates an extra function call. To give *stmt* (whether it is a callable name or code string) access to pre-defined user objects, such as testfunc, *setup* must include an import, such as 'from __main__ import testfunc'. Note that 'from __main__ import *' does not work because * imports are not legal within functions. To measure the execution time of *stmt*, use the timeit() method. The repeat() method is a convenience to call timeit() multiple times and return a list of results. ''' Note 1. testfunc , 'testfunc()' , and 'from ....' should be marked up as code. Perhaps the first two should be double quoted also, depending of the style convention. What must be clear is the difference between passing an unquoted function name and a string. Note 2. The 'may reduce' comment: timeit.timeit(str) (for instance) runs noticeably faster than timeit.timeit('str()'). I presume this is because callables get bound to a local name and local name lookup is faster than builtin lookup. This difference does not apply to imported user names. The existing statement "Note that the timing overhead is a little larger in this case because of the extra function calls." is confusing to me because it does not specify the alternative to 'this case' and there are two possibilities, which I specified. Note 3. The comment about * imports should be deleted for 2.7 version. ADDITIONAL CHANGE Add the following to the very bottom as part of the final example: " t = Timer(test, "from __main__ import test") print(t.timeit()) # should be nearly the same " ---------- keywords: +patch nosy: +terry.reedy stage: -> needs patch type: -> behavior versions: +Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1397474> _______________________________________

1 0

multiprocessing doc typo
by Justin Peel 30 Aug '10

30 Aug '10

I guess this is a bug, though I'd call it more of a typo. On the multiprocessing page, http://docs.python.org/library/multiprocessing.html, near the bottom of the page there is text that says "An showing how to use queues" which should be "An example showing how to use queues". Justin

1 0

[issue9715] io doc improvements
by Antoine Pitrou 30 Aug '10

30 Aug '10

New submission from Antoine Pitrou <pitrou(a)free.fr>: This is an improvement patch for the :mod:`io` documentation. It adds an user-friendly overview, and makes a couple of other fixes/improvements. There's a problem where I want to make a link to a glossary term while using the plural form ("abstract base classes"), and it doesn't work. Can someone help me? ---------- assignee: docs@python components: Documentation, IO files: iodoc.patch keywords: patch messages: 115208 nosy: benjamin.peterson, docs@python, pitrou priority: normal severity: normal stage: patch review status: open title: io doc improvements type: behavior versions: Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file18679/iodoc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9715> _______________________________________

3 8

[issue7950] subprocess.Popen documentation should contain a good warning about the security implications when using shell=True
by Chris Rebert 28 Aug '10

28 Aug '10

Chris Rebert <pybugs(a)rebertia.com> added the comment: Adjusted patch per R. David's comment. I obviously think it should be a full red warning box (that's how it is in my patch), but my opinion clearly isn't an outside one. Also, Ping/Bump on finally getting this applied. ---------- Added file: http://bugs.python.org/file18670/subprocess.rst.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7950> _______________________________________

1 0

typo
by LEE DANIEL JOON 28 Aug '10

28 Aug '10

http://docs.python.org/tutorial/classes.html -- (where one at least one of the parent classes can be accessed through multiple paths from the bottommost class). ++ (where at least one of the parent classes can be accessed through multiple paths from the bottommost class).

1 0

transpose of a matrix represented with nested lists
by Wacek Kusnierczyk 28 Aug '10

28 Aug '10

Hello, In section 5.1 [1] of Python 3 online documentation, you discuss ways to transpose a matrix represented as a nested list. The following example is given: mat = [ ... [1, 2, 3], ... [4, 5, 6], ... [7, 8, 9], ... ] list(zip(*mat)) [(1, 4, 7), (2, 5, 8), (3, 6, 9)] That's correct only if further code ignores the distinction between tuples and lists. In the code as it is, the 'list' part is actually redundant, as zip will return a list anyway. To transpose a matrix using zip, the following seems more accurate: map(list, zip(*m)) Regards, vQ [1] http://docs.python.org/py3k/tutorial/datastructures.html#nested-list-compre…

1 0

V2.6 PDF documentation
by John Hughes 27 Aug '10

27 Aug '10

Hello, I can't seem to find the 2.6 version of the Python documentation in PDF format on the python.org website. Is there some way I could get to it? Thanks. John Hughes Senior Software Engineer Department of Electrical and Computer Engineering University of Arizona

1 0

shutil.copytree error interface is ambiguously docced
by Joshua Rodman 26 Aug '10

26 Aug '10

shutil.copytree() says: """ shutil.copytree(src, dst[, symlinks=False[, ignore=None]])¶ Recursively copy an entire directory tree rooted at src. The destination directory, named by dst, must not already exist; it will be created as well as missing parent directories. Permissions and times of directories are copied with copystat(), individual files are copied using copy2(). If symlinks is true, symbolic links in the source tree are represented as symbolic links in the new tree; if false or omitted, the contents of the linked files are copied to the new tree. If ignore is given, it must be a callable that will receive as its arguments the directory being visited by copytree(), and a list of its contents, as returned by os.listdir(). Since copytree() is called recursively, the ignore callable will be called once for each directory that is copied. The callable must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. ignore_patterns() can be used to create such a callable that ignores names based on glob-style patterns. If exception(s) occur, an Error is raised with a list of reasons. The source code for this should be considered an example rather than the ultimate tool. """ Naively, this reads as copytree aborting on exception. "If exceptions(s) occur, an Error is raised with a list of reasons." This suggests the copy operation does not complete. I suggest changing this to: If exceptions(s) occur during the copy operation, an Error is raised on completion with a list of all the encountered reasons during the copy operation. Preferably the format of the Error object or a pointer to the error object defintion would be included as well. -josh -- scooby snacks.

1 0

[issue5904] strftime docs do not explain locale effect on result string
by Éric Araujo 26 Aug '10

26 Aug '10

Changes by Éric Araujo <merwok(a)netwok.org>: ---------- assignee: georg.brandl -> docs@python nosy: +docs@python _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue5904> _______________________________________

1 0