Mailman 3 October 2011 - docs

[issue12602] Missing cross-references in Doc/using
by Éric Araujo 10 Oct '11

10 Oct '11

Éric Araujo <merwok(a)netwok.org> added the comment: > For new doc editors, it would be nicer if the filename (directory name, actually) > had been changed to 'py_setup' or even 'py_usage'. py_setup would conflict with pysetup, the installer part of distutils2/packaging. py_ seems redundant to me, we are in the Python docs. > Looking in the first chapter, which you finally referenced, I do see an entry for > '<script>', with the brackets, that can be both a target and container of links. That > usage, with a generic argument name in angle brackets, may be unique in the docs. (I > looked at trace, profile, pydoc, timeit, test, and doctest docs.) So don't be so > surprised that others are not familiar with it. I however am familiar with the use of <brackets>, $SHELL-LIKE-DOLLAR, OPTPARSE-LIKE-ALLCAPS or even {str-format-like-braces} to mark up metavariables. “Use python -m <module> or python -c "YOUR CODE HERE" or python path/to/script” is no problem; maybe it is because other documentation (man pages?) I’m familiar with use it. (I even see them in email, like in “$deity knows etc.”) > +1 on the links suggested in the original message. I’ll put up a patch for review. > -1 on a link to the tracker issue. I’ll see if I can add a few lines with the gist of the bug report, then. ---------- assignee: -> eric.araujo _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12602> _______________________________________

1 0

[issue12602] Missing cross-references in Doc/using
by Mike Hoy 10 Oct '11

10 Oct '11

Changes by Mike Hoy <mhoy09(a)gmail.com>: ---------- nosy: -mikehoy _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12602> _______________________________________

1 0

[issue13075] PEP-0001 contains dead links
by Elmar Zander 10 Oct '11

10 Oct '11

New submission from Elmar Zander <elmar(a)zandere.de>: The links in section "Resources" of PEP-0001 are all dead. They point to www.python.org/dev/<whatever> and all return a 404. Most of them can still be found via google archive.org, but that's not really how it should be. Maybe some of them are already superseded, but even then I think they have at least historical value and should be kept on python.org. ---------- assignee: docs@python components: Documentation messages: 144680 nosy: docs@python, ezander priority: normal severity: normal status: open title: PEP-0001 contains dead links _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13075> _______________________________________

6 8

[issue13138] ElementTree's Element.iter() lacks versionadded
by Andreas Stührk 09 Oct '11

09 Oct '11

New submission from Andreas Stührk <andy-python(a)hammerhartes.de>: See http://docs.python.org/whatsnew/2.7.html#updated-module-elementtree-1-3 ---------- assignee: docs@python components: Documentation files: Element_iter_versionadded.patch keywords: patch messages: 145199 nosy: Trundle, docs@python priority: normal severity: normal status: open title: ElementTree's Element.iter() lacks versionadded versions: Python 2.7 Added file: http://bugs.python.org/file23352/Element_iter_versionadded.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13138> _______________________________________

3 3

[issue12779] Update packaging documentation
by Paul Moore 09 Oct '11

09 Oct '11

Changes by Paul Moore <p.f.moore(a)gmail.com>: ---------- nosy: +pmoore _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12779> _______________________________________

1 0

[issue13094] Need Programming FAQ entry for the behavior of closures
by Éric Araujo 09 Oct '11

09 Oct '11

Changes by Éric Araujo <merwok(a)netwok.org>: ---------- assignee: -> docs@python components: +Documentation -None nosy: +eric.araujo versions: +Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13094> _______________________________________

1 0

[issue10526] Minor typo in What's New in Python 2.7
by Petter Remen 09 Oct '11

09 Oct '11

New submission from Petter Remen <petter.remen(a)gmail.com>: There's a word missing in section "PEP 372: Adding an Ordered Dictionary to collections" The ConfigParser module uses them by default, meaning that configuration files can now read, modified, and then written [...] ~~~~~~~~ should be "now be read". ---------- assignee: docs@python components: Documentation messages: 122347 nosy: Petter.Remen, docs@python priority: normal severity: normal status: open title: Minor typo in What's New in Python 2.7 versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10526> _______________________________________

3 2

[issue12192] Doc that collection mutation methods return item or None
by Terry J. Reedy 08 Oct '11

08 Oct '11

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: BACKGROUND One of most common recurring topics on python-list (perhaps monthly) is newbies tripping over a mutation method returning None when they expect the collection. Today's example: "Puzzled by list-appending behavior". An excerpt from the responses: "On 5/26/2011 11:58 AM, MRAB wrote: > On 26/05/2011 06:17, Chris Rebert wrote: >> list.remove(), list.sort(), and list.extend() similarly return None >> rather than the now-modified list. > I'd just like to point out that it's a convention, not a rigid rule. > Sometimes it's not followed, for example, dict.setdefault." In Python 1, I believe it was true that all mutation methods of mutable builtin collections (ie, lists -- I do not think dicts had any and sets did not exist yet) returned None. With the introduction of list.pop, the return-None rule was 'broken', though the meme continues. However, the flip side of that rule, do-not-return-the-collection, continues to be true. And the return_None rule was not really broken, but broadened to "return None or an item from the collection". I believe this should be better documented than it is now. PROPOSALS 1. State the general rule. A. Tutorial: At the top of chapter 5, just after "This chapter describes some things you’ve learned about already in more detail, and adds some new things as well.", add something like "For lists, sets, and dicts, methods that change the contents or order never return the instance. Instead, they return an item from the instance or, more commonly, None." B. Library Manual: Near the top of 4. Built-in Types, after "The principal built-in types are numerics, sequences, mappings, classes, instances and exceptions.", add something like "Some collection classes are mutable. The methods that add, subtract, or rearrange their members never return the collection instance itself but instead return an item from the instance or None." Comment: This rule applies to special methods like __getitem__ and __setitem__. 'lis.append(item)' is equivalent to lis.__setitem__(len(lis):len(lis), item), so it should not be so surprising that it has the same return. 2. Document None returns explicitly. They are currently documented implicitly, by absence. A. Docstrings: Compare the relevant parts of the output from 'help(list.append)' and 'help(list.pop)' L.append(object) -- append object to end L.pop([index]) -> item -- remove and return item at index Add ' -> None' to specify return for .append. L.append(object) -> None -- append object to end I expect experienced Python programmers may object that this puts too much emphasis on the unimportant null return, but it is important that Python programmers know about it and experience shows that many newbies *need* that emphasis. B. Doc entries: Essentially same suggestion -- add 'Return None.' to appropriate entries in tutorial chapter 5. For library manual, possibly add footnote '(9) Returns None' to the method table in 4.6.4. Mutable Sequence Types. For sets and dicts, add 'and return None' to appropriate entries. ---------- assignee: docs@python components: Documentation messages: 137009 nosy: docs@python, terry.reedy priority: normal severity: normal status: open title: Doc that collection mutation methods return item or None versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12192> _______________________________________

7 8

[issue12602] Missing cross-references in Doc/using
by Terry J. Reedy 08 Oct '11

08 Oct '11

Terry J. Reedy <tjreedy(a)udel.edu> added the comment: As of 2.7/3.2, the doc is named "Python Setup and Usage" at http://docs.python.org/index.html http://docs.python.org/using/cmdline.html (and other chapters) and in the contents list of the Windows help version. For new doc editors, it would be nicer if the filename (directory name, actually) had been changed to 'py_setup' or even 'py_usage'. Looking in the first chapter, which you finally referenced, I do see an entry for '<script>', with the brackets, that can be both a target and container of links. That usage, with a generic argument name in angle brackets, may be unique in the docs. (I looked at trace, profile, pydoc, timeit, test, and doctest docs.) So don't be so surprised that others are not familiar with it. Now that is cleared up: +1 on the links suggested in the original message. -1 on a link to the tracker issue. That is not a coherent document and cannot be edited and improved. If more doc is needed, there should have been and could be a PEP, addition to the <script> entry, or a new chapter section 1.3 Zipfiles. --- >Terry, might that other issue be #12298? Yes. I see you have applied a fix. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12602> _______________________________________

1 0

[issue12602] Missing cross-references in Doc/using
by Éric Araujo 07 Oct '11

07 Oct '11

Éric Araujo <merwok(a)netwok.org> added the comment: Terry, might that other issue be #12298? ---------- title: Missing using docs cross-references -> Missing cross-references in Doc/using _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12602> _______________________________________

1 0