Mailman 3 June 2010 - docs

[issue8983] Docstrings should refer to help(name), not name.__doc__
by Alexander Belopolsky 17 Aug '10

17 Aug '10

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: Inspired by issue issue8973, I did $ grep -in "see.*\.__doc__" Modules/*.c Surprisingly, there were not as many results as I feared. As I explained in the referenced issue, "See name.__doc__", while technically correct, is not user friendly. If you copy name.__doc__ to >>> prompt, you get an ugly repr of a multiline string. I suggest s/name.__doc__/help(struct)/. Here are the grep results Modules/_threadmodule.c:904:Create a new lock object. See LockType.__doc__ for information about locks."); Modules/pwdmodule.c:103:See pwd.__doc__ for more on password database entries."); Modules/pwdmodule.c:124:See pwd.__doc__ for more on password database entries."); Modules/pwdmodule.c:155:See pwd.__doc__ for more on password database entries."); Modules/spwdmodule.c:111:See spwd.__doc__ for more on shadow password database entries."); Modules/spwdmodule.c:143:See spwd.__doc__ for more on shadow password database entries."); ---------- assignee: docs@python components: Documentation messages: 107661 nosy: belopolsky, docs@python, mark.dickinson priority: normal severity: normal stage: needs patch status: open title: Docstrings should refer to help(name), not name.__doc__ type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8983> _______________________________________

3 6

[issue8834] Define order of Misc/ACKS entries
by Alexander Belopolsky 11 Aug '10

11 Aug '10

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: This is a semi-serious feature request following a brief discussion on #python-dev IRC. Brett Cannon pointed out on python-checkins list [1] that the names should be alphabetized. However, given that the names are international, it is not obvious what it means. I propose to add a comment at the top of Misc/ACKS that the list is maintained in "rough alphabetical order" but not define it any further. [1] http://mail.python.org/pipermail/python-checkins/2010-May/093650.html ---------- assignee: docs@python components: Documentation messages: 106615 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: Define order of Misc/ACKS entries type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8834> _______________________________________

6 10

[issue9037] Add explanation as to how to raise a custom exception in the extending python intermezzo on exceptions
by Jonathan G. Underwood 03 Aug '10

03 Aug '10

New submission from Jonathan G. Underwood <jonathan.underwood(a)gmail.com>: In the documentation section on Extending Python with C or C++ there is an Intermezzo on Errors and Exceptions which shows how to create a custom exception in an extension module. I was just following these instructions for the first time and got to the end and was left wondering how to actually raise the custom exception in my new module, and it wasn't immediately obvious, so I propose to add a brief explanation to the end of that section explaining how. Patch attached. ---------- assignee: docs@python components: Documentation files: extending_how_to_raise_exception.patch keywords: patch messages: 108239 nosy: docs@python, jonathan.underwood priority: normal severity: normal status: open title: Add explanation as to how to raise a custom exception in the extending python intermezzo on exceptions type: feature request versions: Python 2.7 Added file: http://bugs.python.org/file17725/extending_how_to_raise_exception.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9037> _______________________________________

2 1

[issue8562] hasattr(open, 'newlines') example gives incorrect results from PEP0278
by AdamN 02 Aug '10

02 Aug '10

New submission from AdamN <adam(a)varud.com>: This bug from the Ubuntu list is being moved here: https://bugs.launchpad.net/ubuntu/+source/python-defaults/+bug/570737 Newlines support is enabled on Ubuntu but the example from: http://www.python.org/dev/peps/pep-0278/ Does not give the correct results (of True): if hasattr(open, 'newlines'): print 'We have universal newline support' I don't know if this is a documentation problem or whether there is another attr that matters here. ---------- assignee: docs@python components: Documentation, Windows messages: 104454 nosy: adamnelson, docs@python priority: normal severity: normal status: open title: hasattr(open,'newlines') example gives incorrect results from PEP0278 type: behavior versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8562> _______________________________________

4 3

[issue9106] remove numbers from 3-.. level entries in docs toc
by anatoly techtonik 02 Aug '10

02 Aug '10

New submission from anatoly techtonik <techtonik(a)gmail.com>: It seems that left side ToC menu will be more clear without numeric prefixes from chapter on 3-.. nesting levels. How about to remove them? For example - the ToC menu now starting from root level: 15.6. logging — Logging facility for Python * 15.6.1. Logging tutorial o 15.6.1.1. Simple examples o 15.6.1.2. Loggers o 15.6.1.3. Handlers o 15.6.1.4. Formatters o 15.6.1.5. Configuring Logging o 15.6.1.6. Configuring Logging for a Library * 15.6.2. Logging Levels * 15.6.3. Useful Handlers ... will look like: 15.6. logging — Logging facility for Python * 1. Logging tutorial o 1.1. Simple examples o 1.2. Loggers o 1.3. Handlers o 1.4. Formatters o 1.5. Configuring Logging o 1.6. Configuring Logging for a Library * 2. Logging Levels * 3. Useful Handlers ... ---------- assignee: docs@python components: Documentation messages: 108850 nosy: docs@python, techtonik priority: normal severity: normal status: open title: remove numbers from 3-.. level entries in docs toc versions: Python 2.6, Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9106> _______________________________________

6 12

[issue8602] documentation of bz2 module mildly erroneous
by Matt Wartell 01 Aug '10

01 Aug '10

New submission from Matt Wartell <matt.wartell+pt(a)gmail.com>: This is related to http://bugs.python.org/issue8601 "bz2.BZ2File should support "with" protocol per PEP 343" The documentation at http://docs.python.org/library/bz2.html states: "This module provides a comprehensive interface for the bz2 compression library. It implements a complete file interface,..." although bz2.BZ2File does not support the __enter__ and __exit__ methods so arguably doesn't implement the "complete file interface". If issue8601 is declined then the documentation should probably note this exception. ---------- assignee: docs@python components: Documentation messages: 104818 nosy: Matt.Wartell, docs@python priority: normal severity: normal status: open title: documentation of bz2 module mildly erroneous type: behavior versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8602> _______________________________________

3 5

[issue8638] Remove suggestion for name mangling from the tutorial
by Lucian Ursu 31 Jul '10

31 Jul '10

New submission from Lucian Ursu <lucian_ursu(a)yahoo.com>: I suggest that name mangling should not be recommended as a way of having private attributes. Instead, one underscore should be suggested as a signal that the attribute is private. This suggestion comes after discussing with some of the helpers from #python. Basically, they said that name mangling should never be used, so it would be appropriate to remove this recommendation from the tutorial. ---------- assignee: docs@python components: Documentation messages: 105161 nosy: LucianU, docs@python priority: normal severity: normal status: open title: Remove suggestion for name mangling from the tutorial type: feature request versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8638> _______________________________________

8 8

[issue3874] documentation bug: HTMLParser needs to document unknown_decl
by Terry J. Reedy 27 Jul '10

27 Jul '10

Terry J. Reedy <tjreedy(a)udel.edu> added the comment: I understand that getting no response to a submission is not pleasant. I do not like it either. That is partly why I have started reviewing old issues. In the past couple of weeks, I have gotten old two orphaned patches applied by updating the headers, reading the patch, and adding a first-response approval message that got the attention of someone with code-commit privileges. I hope you agree that late is better than never. I just discovered the nosy-count box on the search page. 351 open issues with a nosy count of 1 (which means no response unless someone responded and then removed themself) is too many. We need more issue reviewers. As to your message: this is *our* tracker, not my tracker. My participation is as much voluntary as yours. I hope you do not really give up on improving Python and its documentation. I did not expect that you *should* have known submission details. That is why I tried to inform you. In particular, when an issue is marked as 'documentation', it is automatically assigned to 'docs@python', a pseudo-user standing in for people who handle doc revisions. Now they will see this issue, whereas they would not have before. Please excuse me for not remembering the title as I responded to the message. It is best if message text stands alone. Again, I hope you would agree that an somewhat ignorant response may be better than none. In order for the doc maintainers to add an entry, someone knowledgeable must write it. Your paragraph of explanation is a start, but more editing is needed. Looking at dir(html.parser.HTMLParser) and help(...), I see that there are several public internal methods. Some have doc strings that show up with help(), some do not. I thing all should. Some are defined on HTMLParser and some inherited from the undocumented (I believe) _markupbase.ParserBase. I see that there are also several (completely undocumented except fir dir()) private ('_xyz') internal methods. This implies to me that the public internal methods were made public rather than private because there might be reason to override them. If so, perhaps there should be a new subsection on public internal methods to explain what is what with them. What do you think? Document just one, some, or all? ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue3874> _______________________________________

2 1

[issue8888] Promote SafeConfigParser and warn about ConfigParser
by Éric Araujo 25 Jul '10

25 Jul '10

New submission from Éric Araujo <merwok(a)netwok.org>: Problems like #8880 could be prevented with a deprecation notice for the ConfigParser class, in favor of SafeConfigParser. (Not sure if R. David Murray meant just a recommendation or a real deprecation.) ---------- assignee: docs@python components: Documentation messages: 106943 nosy: docs@python, merwok, r.david.murray priority: normal severity: normal status: open title: Promote SafeConfigParser and warn about ConfigParser versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8888> _______________________________________

3 2

[issue9007] CGIHTTPServer
by anatoly techtonik 21 Jul '10

21 Jul '10

New submission from anatoly techtonik <techtonik(a)gmail.com>: CGIHTTPServer only supports Python CGI scripts. That should be reflected in documentation. ---------- assignee: docs@python components: Documentation messages: 107911 nosy: docs@python, techtonik priority: normal severity: normal status: open title: CGIHTTPServer versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9007> _______________________________________

2 3