Mailman 3 October 2012 - docs

[issue11807] Documentation of add_subparsers lacks information about parametres
by Filip Gruszczyński Oct. 6, 2013

Oct. 6, 2013

New submission from Filip Gruszczyński <gruszczy(a)gmail.com>: In argparse documentation parametres of add_subparsers are not listed. And yet there are some really useful parametres like parser_class. It would be useful, it they were described there well and one wouldn't have to look into the code to find them :-) I'll be happy to provide documentation patch tomorrow. ---------- assignee: docs@python components: Documentation messages: 133379 nosy: docs@python, gruszczy priority: normal severity: normal status: open title: Documentation of add_subparsers lacks information about parametres versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11807> _______________________________________

3 8

[issue15213] _PyOS_URandom documentation
by Christian Heimes Oct. 6, 2013

Oct. 6, 2013

New submission from Christian Heimes <lists(a)cheimes.de>: The comment for Python/random.c:_PyOS_URandom() states > Fill buffer with size pseudo-random bytes, not suitable for cryptographic use, from the operating random number generator (RNG). which is not correct as all paths use a RNG that is suitable for most cryptographic purposes except long living private keys for asymmetric encryption. Also the function isn't documented although it's an official API function and plays a vital role on the new hash randomization. ---------- assignee: docs@python components: Documentation messages: 164218 nosy: christian.heimes, docs@python, haypo, pitrou priority: low severity: normal status: open title: _PyOS_URandom documentation versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15213> _______________________________________

5 6

[issue12350] Improve stat_result.st_blocks and st_blksize documentation
by Lars Wirzenius Oct. 6, 2013

Oct. 6, 2013

New submission from Lars Wirzenius <liw(a)liw.fi>: Attached patch adds a few words to the os.stat documentation for the st_blocks and st_blksize fields to clarify them. ---------- assignee: docs@python components: Documentation files: stat_result.patch keywords: patch messages: 138467 nosy: docs@python, liw priority: normal severity: normal status: open title: Improve stat_result.st_blocks and st_blksize documentation versions: Python 2.7 Added file: http://bugs.python.org/file22382/stat_result.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________

4 10

[issue16195] Difficult or impossible to figure out how garbage collector and weak references should interact for user-defined extension types
by Jean-Paul Calderone Oct. 5, 2013

Oct. 5, 2013

New submission from Jean-Paul Calderone: There appears to be very little, if any, documentation about how to handle the list at tp_weaklistoffset for types supporting being weak referenced, particularly with respect to garbage collection. Who owns the list? Who owns the objects in the list? Should the list be traversed by the extension type's tp_traverse? Should it ever be INCREF'd or DECREF'd? Does tp_dealloc have any responsibilities with respect to it? >From looking at CPython's own source, it appears that tp_traverse should not touch it (Yhg1s confirmed this on #python). Cython, at least, appears to have come to an alternate conclusion though - it generates tp_traverse functions which visit the list (and provoke gc assertions to fail on Python 2.7 in debug mode). Some documentation about what is correct to do would be excellent, and would make it easier to explain to Cython developers what they're doing wrong (or confirm that they're doing something right, in which case there are some more bugs to file against the CPython stdlib, since they do something different from Cython). ---------- assignee: docs@python components: Documentation messages: 172639 nosy: docs@python, exarkun priority: normal severity: normal status: open title: Difficult or impossible to figure out how garbage collector and weak references should interact for user-defined extension types _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16195> _______________________________________

6 5

[issue11163] iter() documentation code doesn't work
by Michael Grazebrook Sept. 11, 2013

Sept. 11, 2013

New submission from Michael Grazebrook <michael(a)grazebrook.com>: This code fragment from the documentation of iter() doesn't work as intended. Change "STOP" to "STOP\n". Maybe also check for EOF as it hangs. with open("mydata.txt") as fp: for line in iter(fp.readline, "STOP"): process_line(line) Or maybe this makes a better example because it's clearer wha'ts going on: square_generator = (i * i for i in range(100000)) for n in iter( square_generator.next, 144): print n ---------- assignee: docs@python components: Documentation messages: 128238 nosy: docs@python, mgrazebrook priority: normal severity: normal status: open title: iter() documentation code doesn't work type: behavior versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________

6 10

[issue15233] atexit: guarantee order of execution of registered functions?
by Georg Brandl Aug. 21, 2013

Aug. 21, 2013

New submission from Georg Brandl <georg(a)python.org>: Currently, the atexit docs state "The order in which the functions are called is not defined" in the introduction and "all functions registered are called in last in, first out order" in the docs of the atexit() function. While the latter is correct, I don't think we should guarantee that behaviour by documenting it. Suggestions? ---------- assignee: docs@python components: Documentation messages: 164454 nosy: docs@python, georg.brandl, loewis, pitrou priority: normal severity: normal status: open title: atexit: guarantee order of execution of registered functions? versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15233> _______________________________________

8 23

[issue15939] make *.rst files in Doc/ parseable by doctest
by Chris Jerdonek Aug. 17, 2013

Aug. 17, 2013

New submission from Chris Jerdonek: Currently, when trying to parse the *.rst files in the Doc/ folder (i.e. not actually running them but simply generating unittest.TestCase instances from them by passing them to doctest.DocFileSuite()), five files yield errors. This issue is to make it so that all of the *.rst files in our Doc/ folder are at least parseable by doctest without error. I will submit a patch. Below are the errors that currently occur: (1) test fdoc:library/ctypes.rst crashed -- Traceback (most recent call last): ... ValueError: line 55 of the doctest for ctypes.rst has an invalid option: '+WINDOWS' (2) test fdoc:library/doctest.rst crashed -- Traceback (most recent call last): ... ValueError: line 1592 of the docstring for doctest.rst has inconsistent leading whitespace: ' """))' (3) test fdoc:library/multiprocessing.rst crashed -- Traceback (most recent call last): ... ValueError: line 1016 of the docstring for multiprocessing.rst lacks blank after >>>: '>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>' (4) test fdoc:whatsnew/2.4.rst crashed -- Traceback (most recent call last): ... ValueError: line 1422 of the docstring for 2.4.rst lacks blank after >>>: ' >>>"""' (5) test fdoc:whatsnew/2.7.rst crashed -- Traceback (most recent call last): ... ValueError: line 1531 of the docstring for 2.7.rst lacks blank after .: ' ...' ---------- assignee: docs@python components: Documentation messages: 170441 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: make *.rst files in Doc/ parseable by doctest versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15939> _______________________________________

2 11

[issue16190] Misleading warning in random module docs
by Christian Heimes Aug. 16, 2013

Aug. 16, 2013

New submission from Christian Heimes: The documentation [1] of the random module contains a misleading warning --- Warning: The generators of the random module should not be used for security purposes. Use ssl.RAND_bytes() if you require a cryptographically secure pseudorandom number generator. --- The warning should point users to os.urandom() and random.SystemRandom rather than ssl.RAND_bytes(). On Linux os.urandom() wraps /dev/urandom [2], on Windows it uses CryptGenRandom() [3]. Both are suitable for most cryptographic purposes except for long-lived keys (SSL, SSH, GPG certs etc.). ssl.RAND_bytes() should only be used for such long-lived data and not for salts, session ids and similar. I like to see the warning box in Python 2.7, too. It's still the default for docs.python.org. My inquiry is motivated by #16184. [1] http://docs.python.org/py3k/library/random.html [2] http://linux.die.net/man/4/urandom [3] http://msdn.microsoft.com/en-us/library/windows/desktop/aa379942%28v=vs.85%… ---------- assignee: docs@python messages: 172589 nosy: christian.heimes, docs@python priority: normal severity: normal status: open title: Misleading warning in random module docs type: security versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16190> _______________________________________

9 13

[issue12645] test.support. import_fresh_module - incorrect doc
by Eli Bendersky Aug. 11, 2013

Aug. 11, 2013

New submission from Eli Bendersky <eliben(a)gmail.com>: >From Ezio Melotti's email to python-dev: diff --git a/Doc/library/test.rst b/Doc/library/test.rst --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -447,7 +447,7 @@ Module and package deprecation messages are suppressed during this import if *deprecated* is ``True``. - This function will raise :exc:`unittest.SkipTest` is the named module + This function will raise :exc:`unittest.SkipTest` if the named module Actually I think this is no longer true. import_fresh_module raises an ImportError if *name* can't be imported, or returns None if the fresh module is not found. Its use case is to enable or block accelerations for modules that optionally provide one. All the modules that currently use import_fresh_module are (afaik) always available (json, warnings, heapq), so raising SkipTest when the module is missing is not useful now. It returns None in the case an acceleration is missing, so e.g. in "cjson = import_fresh_module('json', fresh=['_json'])" cjson will be None and it will be possible to do things like @skipUnless(cjson, 'requires _json'). Here raising an ImportError will defeat (part of) the purpose of the function, i.e. avoiding: try: import _json except ImportError: _json = None and raising a SkipTest when the accelerations are missing is not an option if there are other tests (e.g. the tests for the Python implementation). These changes come from http://hg.python.org/cpython/rev/c1a12a308c5b . Before the change import_fresh_module was still returning the module (e.g. json) even when the acceleration (fresh=['_json']) was missing, and the C tests were run twice using the same pure-python module used for the Py ones. The typo and the wrong doc is also on 2.7. ---------- assignee: docs@python components: Documentation keywords: easy messages: 141255 nosy: docs@python, eli.bendersky, ezio.melotti priority: normal severity: normal status: open title: test.support. import_fresh_module - incorrect doc versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________

5 9

[issue10434] Document the rules for "public names"
by Alexander Belopolsky Aug. 1, 2013

Aug. 1, 2013

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: As discussed in "Breaking undocumented API" thread [1] on python-dev, a definition of "public names" is buried deep in the language reference manual: """ The public names defined by a module are determined by checking the module’s namespace for a variable named __all__; if defined, it must be a sequence of strings which are names defined or imported by that module. The names given in __all__ are all considered public and are required to exist. If __all__ is not defined, the set of public names includes all names found in the module’s namespace which do not begin with an underscore character ('_'). __all__ should contain the entire public API. It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module). """ [2] It has been argued that this is not the authoritative definition and alternatives have been suggested such as "any name that does not begin with an underscore except imported modules." mportant for the users and developers of cpython and other python implementations to know what names they can rely upon to stay defined between releases, the rules for "public names" should be documented. I agree that the library manual is a more appropriate place for such documentation. The definition should include the naming conventions and the set of promises that Python makes about public name availability in the future releases. [1] http://mail.python.org/pipermail/python-dev/2010-November/105490.html [2] http://docs.python.org/reference/simple_stmts.html ---------- assignee: docs@python components: Documentation messages: 121297 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Document the rules for "public names" versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10434> _______________________________________

6 7