Mailman 3 February 2020 - docs

[issue23677] Mention dict and set comps in library reference
by Frank Millman May 10, 2020

May 10, 2020

New submission from Frank Millman: This is from the documentation at Section 4.6.4. Lists """ Lists may be constructed in several ways: Using a pair of square brackets to denote the empty list: [] Using square brackets, separating items with commas: [a], [a, b, c] Using a list comprehension: [x for x in iterable] Using the type constructor: list() or list(iterable) """ Comprehensions are mentioned as a constructor. This is from the documentation at Section 4.10. Mapping Types """ Dictionaries can be created by placing a comma-separated list of key: value pairs within braces, for example: {'jack': 4098, 'sjoerd': 4127} or {4098: 'jack', 4127: 'sjoerd'}, or by the dict constructor. class dict(**kwarg) class dict(mapping, **kwarg) class dict(iterable, **kwarg) Return a new dictionary initialized from an optional positional argument and a possibly empty set of keyword arguments. """ There is no mention of dictionary comprehensions. For consistency, I believe that the documentation for Dicts and Sets should mention comprehensions. ---------- assignee: docs@python components: Documentation messages: 238186 nosy: FrankMillman, docs@python priority: normal severity: normal status: open title: Mention dict and set comps in library reference versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23677> _______________________________________

8 11

[issue26817] Docs for StringIO should link to io.BytesIO
by Thomas Guettler May 10, 2020

May 10, 2020

New submission from Thomas Guettler: I think a warning at the top of StringIO docs is needed. And it should link to io.BytesIO. Maybe even deprecate StringIO and cStringIO in Python2? StringIO docs: https://docs.python.org/2/library/stringio.html io.BytesIO docs: https://docs.python.org/2/library/io.html#io.BytesIO I would like to see this at the top of StringIO: {{{ Please use io.BytesIO and io.StringIO since this module is not supported in Python3 }} ---------- assignee: docs@python components: Documentation messages: 263917 nosy: docs@python, guettli priority: normal severity: normal status: open title: Docs for StringIO should link to io.BytesIO versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26817> _______________________________________

3 2

[issue21596] asyncio.wait fails when futures list is empty
by Sebastian Kreft May 4, 2020

May 4, 2020

New submission from Sebastian Kreft: Passing an empty list/set of futures to asyncio.wait raises an Exception, which is a little annoying in some use cases. Probably this was the intended behavior as I see there's a test case for that. If such, then I would propose to document that behavior. ---------- assignee: docs@python components: Documentation messages: 219290 nosy: Sebastian.Kreft.Deezer, docs@python priority: normal severity: normal status: open title: asyncio.wait fails when futures list is empty versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21596> _______________________________________

5 9

[issue33649] asyncio docs overhaul
by Yury Selivanov May 4, 2020

May 4, 2020

New submission from Yury Selivanov <yselivanov(a)gmail.com>: An overhaul of asyncio documentation is long overdue. Here's the structure for it that I have in mind: - Introduction (what is asyncio and async/await) - A quick tutorial (show how to use asyncio.run() and basic functions like asyncio.sleep() and teach that asyncio programs are all about async/await and *not* about callbacks or event loops) - High-level APIs (Tasks, Streams, Subprocesses, few other functions) - Low-level APIs - Preface (talk a bit about everything: what's an event loop, what is a Future and a Transport) - Futures - Event loop APIs - Transports and Protocols (when to use and when not to use them) - Tutorials - High-level networking server - HTTP application - Low-level protocol implementation using Transports - etc ---------- assignee: docs@python components: Documentation, asyncio messages: 317709 nosy: akuchling, asvetlov, docs@python, yselivanov priority: normal severity: normal status: open title: asyncio docs overhaul type: enhancement versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33649> _______________________________________

17 74

[issue39435] pickle: inconsistent arguments pickle.py vs _pickle.c vs docs
by Guido Imperiale May 2, 2020

May 2, 2020

New submission from Guido Imperiale <crusaderky(a)gmail.com>: (1) In the documentation for loads(), the name for the first argument of loads is 'bytes_object'. The actual signature, both in pickle.py and _pickle.c, it is instead 'data'. (2) In the documentation and in pickle.py, the default value for the 'buffers' parameter is None. However, in _pickle.c, it is an empty tuple (); this is also reflected by running the interpreter: In [1]: inspect.signature(pickle.loads).parameters['buffers'] Out[1]: <Parameter "buffers=()"> Thanks to @hauntsaninja for spotting these in https://github.com/python/typeshed/pull/3636 ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 360569 nosy: crusaderky, docs@python priority: normal severity: normal status: open title: pickle: inconsistent arguments pickle.py vs _pickle.c vs docs versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39435> _______________________________________

6 14

[issue8940] *HTTPServer need a summary page with API inheritance table
by anatoly techtonik April 27, 2020

April 27, 2020

New submission from anatoly techtonik <techtonik(a)gmail.com>: The abundance of methods and hierarchy depth of various servers from "Internet Protocols and Support" section makes it extremely hard to navigate information. You need a strong OOP background to be able to use this doc effectively, as examples are not intuitive otherwise. Usually you need a decent IDE (such as Eclipse) to get a picture of class hierarchy and a table of all available methods with a mark where they were inherited from. Such table (at least Class Hierarchy view screenshot from Eclipse) should be available in reference for descendant classes. ---------- assignee: docs@python components: Documentation messages: 107321 nosy: docs@python, techtonik priority: normal severity: normal status: open title: *HTTPServer need a summary page with API inheritance table versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8940> _______________________________________

6 7

[issue14418] Document differences in SocketServer between Python 2.6 and 2.7
by Geoffrey Bache April 27, 2020

April 27, 2020

New submission from Geoffrey Bache <gjb1002(a)users.sourceforge.net>: Here I'm referring to the section about RequestHandler objects under the SocketServer page. http://docs.python.org/release/2.7.2/library/socketserver.html#requesthandl… This appears to be the same in Python 2.6 and Python 2.7. But the objects don't behave the same, in two respects: 1) For finish() "If setup() or handle() raise an exception, this function will not be called." This is true in Python 2.6. It appears to no longer be true in Python 2.7, where finish() is called in a "finally" clause. 2) For handle(). "The default implementation does nothing". This is true up to a point, but using the default implementation has different effects. Specifically, if I try to read from a socket when the server has not written anything, I get an exception in Python 2.6 and an empty string in Python 2.7. Consider this code: ## server.py from SocketServer import TCPServer, StreamRequestHandler import sys, socket server = TCPServer((socket.gethostname(), 0), StreamRequestHandler) host, port = server.socket.getsockname() address = host + ":" + str(port) print "Started server at", address sys.stdout.flush() server.serve_forever() ## client.py import sys, socket servAddr = sys.argv[1] host, port = servAddr.split(":") serverAddress = (host, int(port)) sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) sock.connect(serverAddress) sock.sendall("Some Message") sock.shutdown(1) response = sock.makefile().read() print "Got reply:", response sock.close() and compare the following: $ python2.7 server.py & Started server at 127.0.1.1:42759 $ python2.7 client.py 127.0.1.1:42759 Got reply: $ python2.6 server.py & Started server at 127.0.1.1:42758 $ python client.py 127.0.1.1:42758 Traceback (most recent call last): File "client.py", line 12, in <module> response = sock.makefile().read() File "/usr/lib/python2.7/socket.py", line 351, in read data = self._sock.recv(rbufsize) socket.error: [Errno 104] Connection reset by peer (doesn't matter which Python runs the client in the last case) I am unsure whether this is a bug in Python 2.6, or really what the reasoning behind the behaviour difference is, but I think this change in behaviour is worth a small note in the documentation (how it will behave if you try to read when nothing has been written) ---------- assignee: docs@python components: Documentation messages: 156869 nosy: docs@python, gjb1002 priority: normal severity: normal status: open title: Document differences in SocketServer between Python 2.6 and 2.7 versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14418> _______________________________________

5 5

[issue26665] pip is not bootstrapped by default
by Axel Luttgens April 27, 2020

April 27, 2020

New submission from Axel Luttgens: Relevant page: https://docs.python.org/2/library/ensurepip.html One may read: In most cases, end users of Python shouldn’t need to invoke this module directly (as pip should be bootstrapped by default), but it may be needed if installing pip was skipped when installing Python (or when creating a virtual environment) or after explicitly uninstalling pip. As far as I correctly read the configure file that comes with the 2.7.11 tarball, the default is to behave as if --with-ensurepip=no had been passed. As a result, that sentence fragment: (as pip should be bootstrapped by default) may appear somewhat ambiguous for those compiling Python themselves. Perhaps could this one avoid some head scratching: (as packagers are expected to have bootstrapped pip) HTH, Axel ---------- assignee: docs@python components: Documentation messages: 262610 nosy: Axel, docs@python priority: normal severity: normal status: open title: pip is not bootstrapped by default type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26665> _______________________________________

4 5

[issue30882] Built-in list disappeared from Python 2.7 intersphinx inventory
by Christoph Deil April 27, 2020

April 27, 2020

New submission from Christoph Deil: We have a project where we sub-class `list`. Since recently our docs build is failing because the intersphinx inventory entry for `list` on Python 2.7 doesn't exist any more. I think this is a regression, because Python 2.7 is supposed to be stable and other functions and classes here are still there, just "list" is missing: https://docs.python.org/2.7/library/functions.html#func-list Just in case someone else sees this issue, the Sphinx warning looks like this: ``` docs/api/pyregion.ShapeList.rst:7: WARNING: py:class reference target not found: list ``` if you have something like ``` class ShapeList(list): """My list sub-class""" ``` ---------- assignee: docs@python components: Documentation messages: 297993 nosy: Christoph.Deil, docs@python priority: normal severity: normal status: open title: Built-in list disappeared from Python 2.7 intersphinx inventory versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30882> _______________________________________

5 4

[issue33586] 2.7.15 missing release notes on download page
by Eric N. Vander Weele April 27, 2020

April 27, 2020

New submission from Eric N. Vander Weele <ericvw(a)gmail.com>: When visiting https://www.python.org/downloads/ and attempting to look at the 2.7.15 release notes, the 'Release Notes' link on the far right of the table, it resolves to https://www.python.org/downloads/. ---------- assignee: docs@python components: Documentation messages: 317185 nosy: docs@python, ericvw priority: normal severity: normal status: open title: 2.7.15 missing release notes on download page versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33586> _______________________________________

4 3