Mailman 3 November 2012 - docs

[issue16354] Remember python version choice on docs.python.org
by Wichert Akkerman 03 Nov '12

03 Nov '12

New submission from Wichert Akkerman: docs.python.org was recently change to redirect http://docs.python.org/ to http://docs.python.org/3/ , with an option to switch to documentation for a different version using both (why two ways?) a dropdown and links in the left column. Would it be possible to remember the selection and honour that in the docs.python.org redirect? That would remove the minor annoyance of always ending up at the Python 3 documentation and having to switch back to 2.7. ---------- assignee: docs@python components: Documentation messages: 174106 nosy: docs@python, wichert priority: normal severity: normal status: open title: Remember python version choice on docs.python.org _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16354> _______________________________________

5 7

PEP8 conformance regarding the "Idioms and Anti-Idioms in Python" page
by Matthew Lakier 03 Nov '12

03 Nov '12

This is nothing major, but I guess every bit helps. Under the "Using Backslash to Continue Statements" section of http://docs.python.org/2/howto/doanddont.html (also in the Python 3 docs), the last two code samples: value = foo.bar()['first'][0]*baz.quux(1, 2)[5:9] \ + calculate_number(10, 20)*forbulate(500, 360) and value = (foo.bar()['first'][0]*baz.quux(1, 2)[5:9] + calculate_number(10, 20)*forbulate(500, 360)) have the operator after the line break instead of before, like: value = (foo.bar()['first'][0]*baz.quux(1, 2)[5:9] + calculate_number(10, 20)*forbulate(500, 360)) It would be good if these code samples could be changed to have the operator before the line break in order to conform with PEP8 ("The preferred place to break around a binary operator is after the operator, not before it.") and the rest of the documentation. Thanks!

1 0

[issue15148] shutul.which() docstring could be clearer
by Tshepang Lekhonkhobe 02 Nov '12

02 Nov '12

New submission from Tshepang Lekhonkhobe <tshepang(a)gmail.com>: I find this a little hard to parse (ignoring the obvious typo and the grammar error): """ Given a file, mode, and a path string, return the path whichs conform to the given mode on the path. """ One other suggestion: wouldn't 'file' read better as 'command'? ---------- assignee: docs@python components: Documentation messages: 163515 nosy: docs@python, hynek, tarek, tshepang priority: normal severity: normal status: open title: shutul.which() docstring could be clearer _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________

6 13

[issue8402] Add a function to escape metacharacters in glob/fnmatch
by Serhiy Storchaka 01 Nov '12

01 Nov '12

Changes by Serhiy Storchaka <storchaka(a)gmail.com>: ---------- assignee: docs@python -> components: -Documentation keywords: +needs review resolution: invalid -> stage: -> patch review _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8402> _______________________________________

1 0

[issue16380] true/proper subset
by abcdef 01 Nov '12

01 Nov '12

New submission from abcdef: The documentation http://docs.python.org/2.7/library/stdtypes.html#set-types-set-frozenset http://docs.python.org/3/library/stdtypes.html#set-types-set-frozenset of "<" for sets uses "true subset" and "true superset". The correct termininology is "proper subset" and "proper superset", as evidenced by Google searches http://google.com/search?q="true subset" http://google.com/search?q="proper subset" and most set theory books. ---------- assignee: docs@python components: Documentation messages: 174410 nosy: abcdef, docs@python priority: normal severity: normal status: open title: true/proper subset type: enhancement versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16380> _______________________________________

3 2

[issue14893] Tutorial: Add function annotation example to function tutorial
by Zachary Ware 01 Nov '12

01 Nov '12

New submission from Zachary Ware <zachary.ware(a)gmail.com>: A couple months ago, I had never before heard of function annotations and came across a function that had them (I don't remember where or what it was). I spent a fair bit of time searching fruitlessly to figure out what the heck that "->" in the function definition meant. Then finally, a week or two ago, I came across a mention of pep 3107 and function annotations, and figured out what it was that confused me so thoroughly. In an effort to save others from the same confusion, I've put together a small subsection to add to the tutorial about function definition. The text I'm proposing to add is as follows: """ :ref:`Function annotations <function>` are completely optional, arbitrary metadata information about user-defined functions. Python itself currently does not use annotations for anything, so this section is just for familiarity with the syntax. Annotations are stored in the :attr:`__annotations__` attribute of the function as a dictionary and have no effect on any other part of the function. Parameter annotations are defined by a colon after the parameter name, followed by an expression evaluating to the value of the annotation. Return annotations are defined by a literal ``->``, followed by an expression, between the parameter list and the colon denoting the end of the :keyword:`def` statement. The following example has a positional argument, a keyword argument, and the return value annotated with nonsense:: >>> def f(ham: 42, eggs: int = 'spam') -> "Nothing to see here": ... print("Annotations:", f.__annotations__) # print the function's own annotations ... print("Arguments:", ham, eggs) ... >>> f('wonderful') Annotations: {'eggs': <class 'int'>, 'return': 'Nothing to see here', 'ham': 42} Arguments: wonderful spam """ I'd also like to see a link for "->" in the index, either to this note or to the relevant paragraph of compound_stmts.rst or both. The attached patch attempts to add such a link to this section, but I'm not certain that it's done properly. Thanks :) ---------- assignee: docs@python components: Documentation files: annotations_tutorial.patch keywords: patch messages: 161451 nosy: docs@python, zach.ware priority: normal severity: normal status: open title: Tutorial: Add function annotation example to function tutorial type: enhancement versions: Python 3.2, Python 3.3 Added file: http://bugs.python.org/file25684/annotations_tutorial.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14893> _______________________________________

6 9

Confusion over NotImplemented constant
by Mark Summerfield 01 Nov '12

01 Nov '12

Hi, On this page http://docs.python.org/3/library/constants.html?highlight=notimplemented#No… It says that NotImplemented should be returned by rich comparison special methods. But it doesn't mention using it with the abc module. Yet on this page http://docs.python.org/3/library/abc.html#module-abc It says that __subclasshook__() methods should return NotImplemented. However, on this page http://docs.python.org/3/library/exceptions.html?highlight=notimplemented#N… It says that abstract methods should raise NotImplementedError. Maybe someone could unify the coverage of NotImplemented and NotImplementedError and explain when to use one and when to use the other? -- Mark Summerfield, Qtrac Ltd, www.qtrac.eu C++, Python, Qt, PyQt - training and consultancy "Programming in Go" - ISBN 0321774639 http://www.qtrac.eu/gobook.html

1 0

Wrong calculation in itertools documentation
by Sander De Graaf 01 Nov '12

01 Nov '12

Hi, I'm reading docs.python.org/library/itertools.html @ permutations(). It writes: The number of items returned is n! / (n-r)! ... The number should be n! / r! Thanks, Sander De Graaf

2 2