Mailman 3 November 2015 - docs

[issue18956] Document useful functions in ‘pydoc’ module
by Ben Finney 29 Apr '16

29 Apr '16

New submission from Ben Finney: The library documentation for ‘pydoc’ expects that the ‘pydoc’ module will only ever be run as a command-line program. This ignores the general usefulness of several of the functions in that module when imported from the library. The documentation should describe at least the following functions: * pydoc.getdoc * pydoc.synopsis * pydoc.splitdoc The following would be useful also: * pydoc.classname * pydoc.cram * pydoc.allmethods ---------- assignee: docs@python components: Documentation messages: 197138 nosy: bignose, docs@python priority: normal severity: normal status: open title: Document useful functions in ‘pydoc’ module type: enhancement versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18956> _______________________________________

3 3

[issue20598] argparse docs: '7'.split() is confusing magic
by Thomas Guettler 26 Apr '16

26 Apr '16

New submission from Thomas Guettler: I think the docs of argparse still contain confusing magic: parser.parse_args('7'.split()) You know what it does and I know it. But a lot of people new to Python, don't understand what this should be. Please use: parser.parse_args(['7']) Close this ticket, if you don't care for people new to Python. ---------- assignee: docs@python components: Documentation messages: 210950 nosy: docs@python, guettli priority: normal severity: normal status: open title: argparse docs: '7'.split() is confusing magic versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________

11 19

[issue24296] Queue documentation note needed
by Sandy Chapman 26 Apr '16

26 Apr '16

New submission from Sandy Chapman: The example at the bottom of the following page should have a warning added: https://docs.python.org/2/library/queue.html The warning should be such that the user is informed that the threads in the example are not cleaned up and will continue to run. Any future additions to the queue will then be processed immediately by those threads. ---------- assignee: docs@python components: Documentation messages: 244156 nosy: Sandy Chapman, docs@python priority: normal severity: normal status: open title: Queue documentation note needed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24296> _______________________________________

3 4

[issue24715] Sorting HOW TO: bad example for reverse sort stability
by Jakub Wilk 26 Apr '16

26 Apr '16

New submission from Jakub Wilk: https://docs.python.org/3/howto/sorting.html#odd-and-ends gives the following example for reverse sort stability: >>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)] >>> assert sorted(data, reverse=True) == list(reversed(sorted(reversed(data)))) But here all the keys are different, so the result would be the same even if the sort algorithm weren't stable. You probably wanted to pass to key=itemgetter(0) to both sorted() calls. ---------- assignee: docs@python components: Documentation messages: 247328 nosy: docs@python, jwilk priority: normal severity: normal status: open title: Sorting HOW TO: bad example for reverse sort stability _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24715> _______________________________________

4 6

[issue23986] Inaccuracy about "in" keyword for list and tuple
by wim glenn 26 Apr '16

26 Apr '16

New submission from wim glenn: The comparisons section of the python 2 docs says: --- https://docs.python.org/2/reference/expressions.html#comparisons For the list and tuple types, x in y is true if and only if there exists an index i such that x == y[i] is true. --- But it's not strictly speaking correct. Simplest counter-example: x = float('nan') y = [x] The python 3 docs instead mention correct equivalent which is any(x is e or x == e for e in y) ---------- assignee: docs@python components: Documentation messages: 241317 nosy: docs@python, wim.glenn priority: normal severity: normal status: open title: Inaccuracy about "in" keyword for list and tuple type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23986> _______________________________________

6 6

[issue23662] Cookie.domain is undocumented
by Malcolm Smith 25 Apr '16

25 Apr '16

New submission from Malcolm Smith: This is a fundamental attribute of a cookie, which will be set even if the server doesn't specify it, yet it doesn't appear in the documentation either of 2.x cookielib or 3.x http.cookiejar. ---------- assignee: docs@python components: Documentation messages: 238087 nosy: Malcolm Smith, docs@python priority: normal severity: normal status: open title: Cookie.domain is undocumented versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23662> _______________________________________

5 5

[issue24911] Context manager of socket.socket is not documented
by zodalahtathi 24 Apr '16

24 Apr '16

New submission from zodalahtathi: socket.socket has a context manager to automatically close the socket with the `with` statement: https://hg.python.org/cpython/file/d1bf181afa82/Lib/socket.py#l138 However it is not documented, unlike socket.create_connection. ---------- assignee: docs@python components: Documentation messages: 248979 nosy: docs@python, zodalahtathi priority: normal severity: normal status: open title: Context manager of socket.socket is not documented versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24911> _______________________________________

6 10

[issue23806] documentation for no_proxy is missing from the python3 urllib documentation
by R. David Murray 24 Apr '16

24 Apr '16

New submission from R. David Murray: no_proxy (and what notation it supports) is mentioned in the python2 urllib docs, but not in the python3 docs. ---------- assignee: docs@python components: Documentation messages: 239493 nosy: docs@python, r.david.murray priority: normal severity: normal stage: needs patch status: open title: documentation for no_proxy is missing from the python3 urllib documentation type: behavior versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23806> _______________________________________

5 5

[issue19731] Fix copyright footer
by Antoine Pitrou 24 Apr '16

24 Apr '16

New submission from Antoine Pitrou: Marc-André pointed out that the copyright footer has the wrong date. See attached patch. ---------- assignee: docs@python components: Documentation files: copyright.patch keywords: patch messages: 203959 nosy: docs@python, lemburg, pitrou priority: low severity: normal status: open title: Fix copyright footer versions: Python 2.7, Python 3.3, Python 3.4 Added file: http://bugs.python.org/file32791/copyright.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19731> _______________________________________

5 5

[issue18572] Remove redundant note about surrogates in string escape doc
by Steven D'Aprano 24 Apr '16

24 Apr '16

New submission from Steven D'Aprano: The documentation for string escapes suggests that \uxxxx escapes can be used to generate characters in the Supplementary Multilingual Planes by using surrogate pairs: "Individual code units which form parts of a surrogate pair can be encoded using this escape sequence." http://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-l… E.g. in Python 3.2: py> '\uD80C\uDC80' == '\U00013080' True but that is no longer the case in Python 3.3. I suggest the documentation should just remove that note. ---------- assignee: docs@python components: Documentation messages: 193787 nosy: docs@python, stevenjd priority: normal severity: normal status: open title: Remove redundant note about surrogates in string escape doc versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18572> _______________________________________

6 8