Mailman 3 February 2011 - docs

[issue9724] help('nonlocal') missing
by Cherniavsky Beni April 27, 2011

April 27, 2011

New submission from Cherniavsky Beni <cben(a)users.sf.net>: >>> help('nonlocal') no Python documentation found for 'nonlocal' As a language keyword, it clearly should have documentation. ---------- assignee: docs@python components: Documentation messages: 115266 nosy: cben, docs@python priority: normal severity: normal status: open title: help('nonlocal') missing versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9724> _______________________________________

5 5

[issue9264] trace.py documentation is incomplete
by Eli Bendersky April 27, 2011

April 27, 2011

New submission from Eli Bendersky <eliben(a)gmail.com>: The documentation of the standard 'trace' module (Doc/library/trace.rst) is sorely lacking. Arguments are not explained, some key methods are not documented at all, and the CoverageResults class isn't documented. Usage of these appears in the example but leaves the user confused as the only source of documentation for the example is the source code of the module. I'm attaching a patch that fixes this issue, by providing documentation for the missing parts. The patch was generated vs. the latest SVN trunk. ---------- assignee: docs@python components: Documentation files: tracedoc.3.patch keywords: patch messages: 110344 nosy: docs@python, eli.bendersky, tjreedy priority: normal severity: normal status: open title: trace.py documentation is incomplete type: behavior versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file18009/tracedoc.3.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9264> _______________________________________

6 35

[issue11300] mmap() large file failures on Mac OS X docfix
by Steffen Daode Nurpmeso April 19, 2011

April 19, 2011

New submission from Steffen Daode Nurpmeso <sdaoden(a)googlemail.com>: Issue 11277 was closed upon the generally accepted conclusion that the failure is that mmap(2) on Mac OS X has a long time known bug (see msg129107, or directly http://lists.apple.com/archives/darwin-development/2003/Jun/msg00141.html). Issue 11277 fixed the problem in the test suite, but it does give end-users no hint that such a problem exists (on the documentation side). And it's my believe that a beginner or even a non-low-level programmer may be lost in an equal situation. (Though one could argue that such a HE should not use mmap(2), but everyone has a first-time somewhen, say.) In addition, there are many people who don't have the chance to work/test on multiple operating systems and/or hardware, and who need the hand of people who are experienced and can give hints on stupidiness or however this word is correctly spelled. (Am i preaching already?) Because Python is expected to be a user-friendly language i do request a documentation patch which gives a hint. I'll apply a patch, but i'm somewhat new to Python and rST etc., so it surely needs a hand. (Maybe even its speech is too aggressive??) ---------- assignee: docs@python components: Documentation files: doc_lib_mmap.patch keywords: patch messages: 129221 nosy: docs@python, sdaoden priority: normal severity: normal status: open title: mmap() large file failures on Mac OS X docfix type: feature request versions: Python 3.2, Python 3.3 Added file: http://bugs.python.org/file20867/doc_lib_mmap.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11300> _______________________________________

1 1

[issue11186] pydoc: HTMLDoc.index() doesn't support PEP 383
by STINNER Victor April 15, 2011

April 15, 2011

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: If you have an undecodable filenames on UNIX, Python 3 escapes undecodable bytes using surrogates. pydoc: HTMLDoc.index() uses indirectly os.listdir() which does such operation, and later filenames are encoded to UTF-8 (the whole HTML content is encoded to UTF-8). In practice, you cannot import such .py file, you run them using "python script.py", so we can maybe just ignore modules with undecodable filenames. For example: def isUndecodableFilename(filename): return any((0xD800 <= ord(ch) <= 0xDFFF) for ch in filename) Or we can escape the surrogate characters, but I don't know how. Write "\uDC80" in a HTML document is not a good idea, especially in an URL (e.g. Firefox replaces \ by / in URLs). ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 128382 nosy: docs@python, haypo priority: normal severity: normal status: open title: pydoc: HTMLDoc.index() doesn't support PEP 383 versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11186> _______________________________________

3 6

[issue9101] reference json format in file formats chapter
by anatoly techtonik April 14, 2011

April 14, 2011

New submission from anatoly techtonik <techtonik(a)gmail.com>: Quite often people use .json files for storing configuration. Having a reference to json module from chapter "14. File Formats" would be a good pointer for those looking to .ini alternatives. ---------- assignee: docs@python components: Documentation messages: 108833 nosy: docs@python, techtonik priority: normal severity: normal status: open title: reference json format in file formats chapter versions: Python 2.6, Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9101> _______________________________________

7 22

[issue11282] unittest document not keep consist with code
by Ray.Allen April 3, 2011

April 3, 2011

New submission from Ray.Allen <ysj.ray(a)gmail.com>: r88451: Remove unittest methods scheduled for removal in 3.3 This commit remove assertSameElements() and assertDictContainsSubset(). But shouldn't some modification be done in the unittest library documentation? I wonder if we should remove the docs about the two methods. Now the doc only said "Deprecated since version 3.2." ---------- assignee: docs@python components: Documentation messages: 129036 nosy: docs@python, ysj.ray priority: normal severity: normal status: open title: unittest document not keep consist with code versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11282> _______________________________________

7 13

[issue9331] sys.setprofile is not described as CPython implementation detail
by Alexander Belopolsky March 29, 2011

March 29, 2011

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: Unlike sys.settrace, sys.setprofile is not described as CPython implementation detail in Doc/library/sys.rst. ---------- assignee: docs@python components: Documentation messages: 111199 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: sys.setprofile is not described as CPython implementation detail type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9331> _______________________________________

2 1

[issue10617] Collections ABCs can’t be linked to
by Éric Araujo March 28, 2011

March 28, 2011

New submission from Éric Araujo <merwok(a)netwok.org>: ABCs in collections.rst are marked up with a class role, not a class directive, which means that constructs using the class role do not generate a link. ---------- assignee: docs@python components: Documentation messages: 123277 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Collections ABCs can’t be linked to versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________

6 21

[issue9343] Document that argparse "parents" must be fully declared before children
by Steven Bethard March 26, 2011

March 26, 2011

New submission from Steven Bethard <steven.bethard(a)gmail.com>: [From http://code.google.com/p/argparse/issues/detail?id=61] It should be documented clearly that only the arguments present on the parent parser at the time ArgumentParser is called will be included in the parser. >>> parent = argparse.ArgumentParser(add_help=False) >>> child = argparse.ArgumentParser(parents=[parent]) >>> parent.add_argument('--foo', action='store_true') >>> child.parse_args(['--foo']) usage: [-h] : error: unrecognized arguments: --foo ---------- assignee: docs@python components: Documentation messages: 111306 nosy: bethard, docs@python priority: normal severity: normal status: open title: Document that argparse "parents" must be fully declared before children versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9343> _______________________________________

3 4

[issue10771] descriptor protocol documentation has two different definitions of "owner" class
by Devin Jeanpierre March 22, 2011

March 22, 2011

New submission from Devin Jeanpierre <jeanpierreda(a)gmail.com>: In trunk/Doc/reference/datamodel.rst , under _Implementing Descriptors_, the documentation states: `The following methods only apply when an instance of the class containing the method (a so-called *descriptor* class) appears in the class dictionary of another new-style class, known as the *owner* class. [...]` Immediately below, in the documentation for __get__, it says, `*owner* is always the owner class [...]`. These two uses of "the owner class" are incompatible, because there is only one class which matches the first use: the class where the descriptor was initially assigned to a class attribute; however, for the second use, any descendant class may be called "the owner class". This is demonstrated in the attached doctest file. It is kind of hard to create a better definition for "owner" as used in `__get__`, though. It can't be said to be the class with the descriptor in its class dict, because it can be present in the class dict of some class in the MRO of the owner. It can't be said to be an attribute, because it has to be in a class dict of an ancestor node. It might be possible to change the definition to call the owner class something like, "the class from which the descriptor was invoked", and if that isn't clear enough, provide examples (TypeDescriptor from the attached doctest file might work as an example); however, this would involve reworking the structure of the paragraph substantially. I personally would prefer this option. The paragraph is already badly structured; for example, it defines two terms in a single and rather complex sentence, and should probably be split up into a list of definitions rather than an explanatory jumble paragraph. In addition, this paragraph is the only place in the documentation where this idea of "the owner class" is used in this way. In the descriptions of the descriptor protocol methods below it, "the owner class" always refers to the class from which the attribute was accessed, or the type from which an instance had the attribute accessed. Alternatively, it could be simpler to replace all references below from "the owner class" to "any class with the owner class in the MRO". ---------- assignee: docs@python components: Documentation files: descriptor.py.doctest messages: 124630 nosy: Devin Jeanpierre, docs@python priority: normal severity: normal status: open title: descriptor protocol documentation has two different definitions of "owner" class versions: Python 2.7 Added file: http://bugs.python.org/file20160/descriptor.py.doctest _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10771> _______________________________________

4 5