Mailman 3 October 2012 - docs

[issue14013] tarfile should expose supported formats
by Éric Araujo 23 Jun '14

23 Jun '14

New submission from Éric Araujo <merwok(a)netwok.org>: shutil contains high-level functions to create a zipfile or a tarball. When a new format is added to the tarfile module, then shutil needs to be updated manually. If tarfile exposed the names of the compressors it supports, then shutil could just automatically support everything that tarfile supports instead of having to re-do import dances for optional modules (bz2, lzma, zlib) and also duplicate formats in its doc. This may also be useful for other code wanting to do some introspection. Attached patch implements tarfile.formats, a list of strings (I thought about using a frozenset but then followed the precedent set by the 3.3 crypt module). Tests and docs not updated, I wanted to get Lars’ approval on the principle first. One could argue that this is not needed: compression modules are not added often; updating shutil after updating tarfile is not hard; it is not that useful to have access to the list of supported formats. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 153350 nosy: docs@python, eric.araujo, lars.gustaebel, nadeem.vawda priority: normal severity: normal stage: patch review status: open title: tarfile should expose supported formats type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14013> _______________________________________

3 4

[issue13779] os.walk: bottom-up
by patrick vrijlandt 16 Jun '14

16 Jun '14

New submission from patrick vrijlandt <patrick.vrijlandt(a)gmail.com>: PythonWin 3.2 (r32:88445, Feb 20 2011, 21:29:02) [MSC v.1500 32 bit (Intel)] on win32. Portions Copyright 1994-2008 Mark Hammond - see 'Help/About PythonWin' for further copyright information. >>> import os >>> os.makedirs("g:/a/b/c") >>> os.listdir("g:/a") ['b'] >>> for root, dirs, files in os.walk("g:/a", topdown = False): ... print(root, dirs, files, os.listdir(root)) ... os.rmdir(root) ... g:/a\b\c [] [] [] g:/a\b ['c'] [] [] g:/a ['b'] [] [] >>> >From the documentation of os.walk: If topdown is False, the triple for a directory is generated after the triples for all of its subdirectories (directories are generated bottom-up). As the above example shows, the directories are generated in the correct order, "generated" referring to yield from generator os.walk. However, the generated (files? and) dirs do not necessarily reflect the current situation as produced by os.listdir. Therefore, this does not clear the entire directory tree as I would expect. >>> os.makedirs("g:/a/b/c") >>> for root, dirs, files in os.walk("g:/a", topdown = False): ... print(root, dirs, files, os.listdir(root)) ... if not (files + dirs): ... os.rmdir(root) ... g:/a\b\c [] [] [] g:/a\b ['c'] [] [] g:/a ['b'] [] ['b'] I think that at least the documentation should be more clear on this issue. I would like even better, if files + dirs would match os.listdir on the moment they are generated (=yielded). ---------- assignee: docs@python components: Documentation messages: 151169 nosy: docs@python, patrick.vrijlandt priority: normal severity: normal status: open title: os.walk: bottom-up type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13779> _______________________________________

6 10

[issue12617] Mutable Sequence Type can work not only with iterable in slice[i:j] = t
by py.user 14 Jun '14

14 Jun '14

New submission from py.user <port139(a)yandex.ru>: 1) 4.6.4 Mutable Sequence Types | s[i:j] = t | slice of s from i to j is replaced | | | by the contents of the iterable t | >>> lst = list('abc') >>> barr = bytearray(b'abc') >>> lst[:1] = 4 Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: can only assign an iterable >>> barr[:1] = 4 >>> barr bytearray(b'\x00\x00\x00\x00bc') >>> there is no info about this feature in the documentation 2) 4.6.4 Mutable Sequence Types | s.extend(x) | same as s[len(s):len(s)] = x | >>> lst = list('abc') >>> barr = bytearray(b'abc') >>> lst.extend(4) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: 'int' object is not iterable >>> barr.extend(4) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: 'int' object is not iterable >>> lst[len(lst):len(lst)] = 4 Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: can only assign an iterable >>> barr[len(barr):len(barr)] = 4 >>> barr bytearray(b'abc\x00\x00\x00\x00') >>> barr.extend(x) != barr[len(barr):len(barr)] = x ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 140924 nosy: docs@python, py.user priority: normal severity: normal status: open title: Mutable Sequence Type can work not only with iterable in slice[i:j] = t type: behavior versions: Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12617> _______________________________________

6 5

[issue10503] os.getuid() documentation should be clear on what kind of uid it is referring
by Giampaolo Rodola' 07 Jun '14

07 Jun '14

New submission from Giampaolo Rodola' <g.rodola(a)gmail.com>: http://docs.python.org/library/os.html#os.getuid os.getuid() documentation just states: > Return the current process’s user id. It is not clear, however, whether "user id" refers to real, effective or saved user id. As per: http://linux.about.com/library/cmd/blcmdl2_getuid.htm ...it should refer to _real_ user id. ---------- assignee: docs@python components: Documentation messages: 122117 nosy: docs@python, giampaolo.rodola priority: normal severity: normal status: open title: os.getuid() documentation should be clear on what kind of uid it is referring versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10503> _______________________________________

5 6

[issue15871] Online docs: make index search always available.
by Terry J. Reedy 13 May '14

13 May '14

New submission from Terry J. Reedy: For the Windows Help version of the docs, the left side box has 4 tabs: Contents, Index, Search, Favorites. I now mostly use the Index tab. That means that I can enter an indexed keyword, topic, or object name and jump from place to place in the docs. The left margin of the online docs only has a text search box equivalent to the Windows search tab (which I essentially never use). The index is only available on the front page, possibly not even visible without scrolling. Consequently, people, especially beginners, tend to use the text search box when they should be using the index. The result is often useless. The issue came up on python-list about a beginner entering 'print' and getting nothing useful. With the Windows doc, 'print' in the index search immediately brings up print (builtin function) (twice, I did not look into why). The same thing in the search lists 153 pages, with the builtin functions page at 75. Not too surprising, as it is a long page with only 3 occurrences of 'print'. Also not useful. So I think the online docs should also have an always available index search box in addition to the text search box (which should be properly labeled as such). 'Enter a module, class, for function name.' should be applied to index search, not text search. An alternative is for the one box to give both index search results and text search results, but doing the latter when one only wants the former is a waste of both server and reader resources. ---------- assignee: docs@python components: Documentation messages: 169930 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl, terry.reedy priority: normal severity: normal status: open title: Online docs: make index search always available. type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15871> _______________________________________

7 14

[issue13030] Be more generic when identifying the Windows main dir in installation doc
by Sandro Tosi 06 May '14

06 May '14

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: Given I have no knowledge of the windows system, I'm just proxying http://mail.python.org/pipermail/docs/2011-September/005793.html : >>> Under: http://docs.python.org/install/index.html#inst-how-install-works It notes "Windows prefix\Lib\site-packages C:\PythonXY\Lib\site-packages" for default values on Windows. In the paragraph following the table is the text: "prefix and exec-prefix stand for the directories that Python is installed to, and where it finds its libraries at run-time. They are always the same under Windows, and very often the same under Unix and Mac OS X. " I don't know if it's hardcoded into Python distributions to use C, but it's not correct. The correct way to identify what most people think of as C is via the %SYSTEMROOT% environment variable, so the path described would be "%SYSTEMROOT%\PythonXY\Lib\site-packages" (This is still not the correct way to do things on Windows, but it at least shouldn't break on systems with a %SYSTEMROOT% other than C. I've seen configurations like that on systems which boot multiple versions of Windows.) <<< ---------- assignee: docs@python components: Documentation messages: 144422 nosy: brian.curtin, docs@python, sandro.tosi, tim.golden priority: normal severity: normal stage: needs patch status: open title: Be more generic when identifying the Windows main dir in installation doc type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13030> _______________________________________

4 5

[issue9307] Py_TPFLAGS_LONG_SUBCLASS is not documented
by Alexander Belopolsky 28 Apr '14

28 Apr '14

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: Is there a reason for not documenting Py_TPFLAGS_LONG_SUBCLASS (Py_TPFLAGS_INT_SUBCLASS in 2.x)? This flag is used in PyLong_Check, but neither this flag or its inheritance properties are explained anywhere in the docs. See also issue5476. ---------- assignee: docs@python components: Documentation messages: 110787 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Py_TPFLAGS_LONG_SUBCLASS is not documented type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9307> _______________________________________

6 8

[issue9364] some problems with the documentation of pydoc
by Eli Bendersky 19 Apr '14

19 Apr '14

New submission from Eli Bendersky <eliben(a)gmail.com>: The first paragraph in its documentation says: """ In the Python interpreter, do "from pydoc import help" to provide online help. Calling help(thing) on a Python object documents the object. """ Which is no longer accurate, because the help() function has long ago become a built-in. Below is an excerpt from Terry Reedy in a private email discussion on this subject, that raises more issues. --------------------------------------------- 1. The output from help(help) could be made more clear. The nature of 'help' has been a point of confusion. A recent python-list post asked something like "What is 'help'?" Now (with some parallel examples: >>> help(int) Help on class int in module builtins: class int(object) [snip] >>> help(1) Help on int object: class int(object) [snip] >>> help(help) Help on _Helper in module site object: class _Helper(builtins.object) | Define the built-in 'help'. | This is a wrapper around pydoc.help (with a twist). | | Methods defined here: | | __call__(self, *args, **kwds) | a. 'module site object' is nonsense, it should just be 'module site', except that to be parallel to what is done for other instances, it should be 'Help on _Helper object'. Why should help special-case itself (with a slightly garbled line?) Is that done in site._Helper or pydoc.help? However, it would be more helpful for all instances to give the location of the class when one asks for help on an instance, just as when one asks for help on the class itself. It is annoying to to have to repeat help(<classname>) just to get that info. So I would like to see "Help on instance of class int in module builtins:" "Help on instance of class _Helper in module site:" This would be a code patch to pydoc.help b. "This is a wrapper around pydoc.help" good so far "(with a twist)" thanks a lot. I think the comment should be either removed or explained. A reference manual should explain, not tease. Replace "Define the built-in 'help'." with something clearer and more accurate, such as "The name 'help' is injected in module builtins after being bound to an instance of this class.". Put this after, not before, the 'wrapper' line. A patch for site._Helper doc string. 2. Improve manual chapter for site module. a. It currently starts "Importing this module will append site-specific paths to the module search path." Add "inject 'help' into builtins and " after append. Then add a short explanation paragraph before the search path stuff. Something like "This module contains a class (_Helper) that wraps function pydoc.help. An instance of the class is bound to name 'help' in the builtins module." A recent discussion on pydev or maybe python-list (in the thread mentioned above?) implied that one could usefully make another instance of _Helper or maybe a subclass thereof. I did not pay enough attention, though, to really get it. b. It currently ends with "XXX Update documentation XXX document python -m site –user-base –user-site" ---------- assignee: docs@python components: Documentation messages: 111426 nosy: docs@python, eli.bendersky, tjreedy priority: normal severity: normal status: open title: some problems with the documentation of pydoc type: behavior versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________

9 21

[issue15840] Ambiguity with regard to the effect of accessing a closed IOBase instance
by Alexander Konovalenko 16 Apr '14

16 Apr '14

New submission from Alexander Konovalenko: Two pieces of the documentation for io.IOBase seem to contradict each other: At http://docs.python.org/library/io.html#io.IOBase: "Note that calling any method (even inquiries) on a closed stream is undefined. Implementations may raise IOError in this case." At http://docs.python.org/library/io.html#io.IOBase.close: "Once the file is closed, any operation on the file (e.g. reading or writing) will raise a ValueError." Perhaps the confusion arises in part because it is not clear when a requirement for all IOBase implementations is documented and when the docs merely describe the default behavior of IOBase that implementations are free to override. Those passages are inconsistent on two points: 1) IOError and ValueError are not subclasses one of another. So what should we expect an IOBase implementation to raise? 2) Undefined behavior means literally anything can happen. Technically, that means calling read() or readable() on a closed file (or other kind of stream) could wreak havoc in a totally unrelated part of the system or segfault the Python interpreter. That is definitely a thing to carefully avoid in any production systems. On the other hand, raising an exception, even if we don't know in advance whether it will be ValueError or IOError, is pretty much defined behavior. An exception is easy to deal with and to contain inside a module. So please clarify how dangerous it actually is to access an IOBase stream after it has been closed. ---------- assignee: docs@python components: Documentation messages: 169660 nosy: alexkon, docs@python priority: normal severity: normal status: open title: Ambiguity with regard to the effect of accessing a closed IOBase instance versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15840> _______________________________________

8 12

[issue16278] os.rename documentation slightly inaccurate
by David Benjamin 14 Apr '14

14 Apr '14

New submission from David Benjamin: This is somewhat of a nitpick. os.rename's documentation says "If dst is a directory, OSError will be raised". On Unix, this isn't completely true. If the source is a directory and the destination is an empty directory, it'll overwrite the former with the latter. (Actually if the source is a directory the inverse is true; if dst is a file, OSError will be raised.) In [1]: import os In [2]: os.mkdir("aaa") In [3]: open("aaa/blah", "w").close() In [4]: os.mkdir("bbb") In [5]: os.rename("aaa", "bbb") In [6]: os.listdir("bbb") Out[6]: ['blah'] ---------- assignee: docs@python components: Documentation messages: 173285 nosy: David.Benjamin, docs@python priority: normal severity: normal status: open title: os.rename documentation slightly inaccurate type: enhancement versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16278> _______________________________________

9 44