Mailman 3 July 2010 - docs

[issue8983] Docstrings should refer to help(name), not name.__doc__
by Alexander Belopolsky Aug. 16, 2010

Aug. 16, 2010

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 Aug. 10, 2010

Aug. 10, 2010

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

python tutorial more a reference than a tutorial
by Amandeep Singh (amandsin) Aug. 8, 2010

Aug. 8, 2010

Hi, I tried to study your python tutorial, release 2.6.4. But was very disappointed the way it is written. It is more a reference than a tutorial. Language could have been simpler, giving more examples. Thanks, Amandeep

3 4

[issue9238] zipfile incorrectly documented as not supporting archive comments
by Ryan Kelly Aug. 2, 2010

Aug. 2, 2010

New submission from Ryan Kelly <ryan(a)rfk.id.au>: The zipfile module is prominently documented as "This module does not currently handle...ZIP files which have appended comments". But as far as I can tell, it handles them fine - there's even a "comment" property on the ZipFile object that you can set to modify the comment. I attach a simple doc patch that removes the apparently out-of-date information. ---------- assignee: docs@python components: Documentation files: zipfile_comment_doc.patch keywords: patch messages: 110147 nosy: docs@python, rfk priority: normal severity: normal status: open title: zipfile incorrectly documented as not supporting archive comments versions: Python 2.7, Python 3.2 Added file: http://bugs.python.org/file17973/zipfile_comment_doc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9238> _______________________________________

2 1

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

Aug. 2, 2010

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 Aug. 2, 2010

Aug. 2, 2010

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 Aug. 2, 2010

Aug. 2, 2010

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 Aug. 1, 2010

Aug. 1, 2010

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

“Berkeley” misspellings
by Éric Araujo July 31, 2010

July 31, 2010

Hello I found this typo in dbm.rst while reading recent changesets. According to grep, there is no other occurrence anywhere else, apart from another misspelling in Misc/NEWS. Regards

1 0

[issue8910] Write a text file explaining why Lib/test/data exists
by Georg Brandl July 31, 2010

July 31, 2010

Georg Brandl <georg(a)python.org> added the comment: Added in r83362. ---------- nosy: +georg.brandl resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8910> _______________________________________

1 0