Mailman 3 June 2018 - docs

[issue14911] generator.throw() documentation inaccurate
by Kristján Valur Jónsson Oct. 17, 2018

Oct. 17, 2018

New submission from Kristján Valur Jónsson <kristjan(a)ccpgames.com>: the documentation for generator.throw() does not mention the fact that it has the same semantics for the three arguments as a "raise" expression has. The first two arguments can be: throw(exc_type, None) throw(exc_type, value) throw(exc_type, exc_instance) throw(exc_instance, None) ---------- assignee: docs@python components: Documentation messages: 161565 nosy: docs@python, kristjan.jonsson priority: normal severity: normal status: open title: generator.throw() documentation inaccurate versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________

5 12

[issue11233] clarifying Availability: Unix
by Sandro Tosi Oct. 15, 2018

Oct. 15, 2018

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: Hi, following up http://mail.python.org/pipermail/docs/2011-February/003083.html we have a chat on #python-dev on the topic, the situation is - all started with os.lchmod() and as.lchflags() methods not available on a Debian system - that's because POSIX does not require those functions and then Linux systems don't provide them - so we then thought about clarifying, only for those 2 methods, that they might not be available with a format like "availability: some unix systems" - then we noticed that on top of os doc there's a notice "An “Availability: Unix” note means that this function is commonly found on Unix systems. It does not make any claims about its existence on a specific operating system." and so we thought about linking every 'Availability: Unix' to that note - or transform that not in a footnote and link every 'Availability: Unix' for functions that might not be present to that footnote. It's enough for the conversation dump: ideas/suggestions? :) ---------- assignee: docs@python components: Documentation messages: 128746 nosy: docs@python, sandro.tosi priority: normal severity: normal status: open title: clarifying Availability: Unix _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________

11 25

[issue23554] EchoServerClientProtocol class should be called EchoServerProtocol
by Giovanni Cannata Oct. 15, 2018

Oct. 15, 2018

New submission from Giovanni Cannata: In 18.5.4.3.2. TCP echo server protocol the class in the example code is called EchoServerClientProtocol. It should be EchoServerProtocol. (The client protocol example is correctly called EchoClientProtocol). ---------- assignee: docs@python components: Documentation messages: 236932 nosy: docs@python, gc priority: normal severity: normal status: open title: EchoServerClientProtocol class should be called EchoServerProtocol versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23554> _______________________________________

6 9

[issue28234] In xml.etree.ElementTree docs there are many absent Element class links
by py.user Oct. 9, 2018

Oct. 9, 2018

New submission from py.user: https://docs.python.org/3/library/xml.etree.elementtree.html#reference 1. Comment 2. iselement() 3. ProcessingInstruction 4. SubElement 5. Element.find() 6. ElementTree._setroot() 7. TreeBuilder Applied a patch to the issue that adds Element class links. ---------- assignee: docs@python components: Documentation, Library (Lib), XML files: element-link.diff keywords: patch messages: 277121 nosy: docs@python, py.user priority: normal severity: normal status: open title: In xml.etree.ElementTree docs there are many absent Element class links type: behavior versions: Python 3.6 Added file: http://bugs.python.org/file44775/element-link.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28234> _______________________________________

3 9

[issue33014] Clarify doc string for str.isidentifier()
by David Beazley Oct. 8, 2018

Oct. 8, 2018

New submission from David Beazley <dave(a)dabeaz.com>: This is a minor nit, but the doc string for str.isidentifier() states: Use keyword.iskeyword() to test for reserved identifiers such as "def" and "class". At first glance, I thought that it meant you'd do this (doesn't work): 'def'.iskeyword() As opposed to this: import keyword keyword.iskeyword('def') Perhaps a clarification that "keyword" refers to the keyword module could be added. Or better yet, just make 'iskeyword()` a string method ;-). ---------- assignee: docs@python components: Documentation messages: 313335 nosy: dabeaz, docs@python priority: normal severity: normal status: open title: Clarify doc string for str.isidentifier() versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33014> _______________________________________

9 27

[issue31865] html.unescape does not work as per documentation
by Jun Hui Lee Oct. 2, 2018

Oct. 2, 2018

New submission from Jun Hui Lee <cardinleejh(a)gmail.com>: html.unescape(s) Convert all named and numeric character references (e.g. >, >, &x3e;) But running this gives: >>> html.unescape('>, >, &x3e;') '>, >, &x3e;' ---------- assignee: docs@python components: Documentation messages: 304957 nosy: Jun Hui Lee, docs@python priority: normal severity: normal status: open title: html.unescape does not work as per documentation type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31865> _______________________________________

4 10

[issue33117] asyncio example uses non-existing/documented method
by Henrique Fingler Oct. 1, 2018

Oct. 1, 2018

New submission from Henrique Fingler <idnpolar(a)gmail.com>: In the documentation of asyncio.run_coroutine_threadsafe(coro, loop), in Section 19.5.3.6 (https://docs.python.org/3/library/asyncio-task.html#asyncio.run_coroutine_t…), the example code does the following: future = asyncio.run_coroutine_threadsafe(coro, loop) # Wait for the result with an optional timeout argument assert future.result(timeout) == 3 The problem is that the result method of a future, according to the documentation doesn't take parameters. It's in Section 19.5.3.4 (https://docs.python.org/3.8/library/asyncio-task.html#asyncio.Future.done) result() Return the result this future represents. The same function is used in Section 18.5.9.3 (https://docs.python.org/3/library/asyncio-dev.html#concurrency-and-multithr…) This error is present in all Python 3.* docs. From the asyncio source code (https://github.com/python/cpython/blob/master/Lib/asyncio/futures.py), we have this in the Future class definition: class Future: """This class is *almost* compatible with concurrent.futures.Future. Differences: - This class is not thread-safe. - result() and exception() do not take a timeout argument and raise an exception when the future isn't done yet. .... So this example needs to be reworked, I'd do it if I knew more about asyncio. My ideas involve either using a add_done_callback with a flag or just busy waiting until future.done(). ---------- assignee: docs@python components: Documentation messages: 314223 nosy: Henrique Fingler, docs@python priority: normal severity: normal status: open title: asyncio example uses non-existing/documented method versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33117> _______________________________________

5 4

[issue30964] Mention ensurepip in package installation docs
by Nick Coghlan Sept. 25, 2018

Sept. 25, 2018

New submission from Nick Coghlan: The package installation docs at https://github.com/python/cpython/blob/master/Doc/installing/index.rst have a section on "Common Installation Issues": https://docs.python.org/3/installing/#common-installation-issues A new entry should be added to this section to cover the case where pip isn't installed by default (e.g. because it was deselected when running the installer), and to suggest trying "python -m ensurepip --default-pip" as a potential remedy. ---------- assignee: docs@python components: Documentation keywords: easy messages: 298622 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Mention ensurepip in package installation docs type: enhancement versions: Python 2.7, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30964> _______________________________________

4 13

[issue33442] Python 3 doc sidebar dosnt follow page scrolling like 2.7 doc sidebar.
by Pete Moore Sept. 25, 2018

Sept. 25, 2018

New submission from Pete Moore <1petemoore(a)gmail.com>: the 3.x docs sidebar at location https://docs.python.org/3.6/library/logging.html does not follow the user's scrolling movements like the 2.7 docs sidebar at location https://docs.python.org/2.7/library/logging.html ---------- assignee: docs@python components: Documentation messages: 316269 nosy: docs@python, pete312 priority: normal severity: normal status: open title: Python 3 doc sidebar dosnt follow page scrolling like 2.7 doc sidebar. type: behavior versions: Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33442> _______________________________________

3 3

[issue28418] Raise Deprecation warning for tokenize.generate_tokens
by Matthias Bussonnier Sept. 24, 2018

Sept. 24, 2018

New submission from Matthias Bussonnier: the Tokenize module has the following code: # An undocumented, backwards compatible, API for all the places in the standard # library that expect to be able to use tokenize with strings def generate_tokens(readline): return _tokenize(readline, None) So I'm going to assume it is Deprecated... (since 3.0 AFAICT). If it is expected from Python developers to not use it, may I suggest: 1) Marking it as deprecated in the docstring/ 2) Raise a deprecation warning. Indeed not everyone code by looking at the documentation and it is relatively easy to have your IDE/editor/REPL to complete it. Even tools that grab the source (IPython double question mark for example) will not show the comment above which make it kinda pointless. ---------- assignee: docs@python components: Documentation messages: 278500 nosy: docs@python, mbussonn priority: normal severity: normal status: open title: Raise Deprecation warning for tokenize.generate_tokens versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28418> _______________________________________

5 6