Mailman 3 August 2017 - docs

[issue14345] Document socket.SOL_SOCKET
by anatoly techtonik 11 Aug '17

11 Aug '17

New submission from anatoly techtonik <techtonik(a)gmail.com>: socket.get/setsockopt() docs can be improved by providing description for SOL_SOCKET constant, and link to source code for other level constants and socket level options. ---------- assignee: docs@python components: Documentation messages: 156140 nosy: docs@python, techtonik priority: normal severity: normal status: open title: Document socket.SOL_SOCKET _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14345> _______________________________________

3 3

[issue30051] Document that the random module doesn't support fork
by STINNER Victor 10 Aug '17

10 Aug '17

STINNER Victor added the comment: Since Raymond and Antoine don't like the documentation idea, I just close my issue. Hopefully, Python 3.7 now reseeds automatically random at fork! ---------- resolution: -> rejected stage: -> resolved status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30051> _______________________________________

1 0

[issue31176] Is a UDP transport also a ReadTransport/WriteTransport?
by twisteroid ambassador 10 Aug '17

10 Aug '17

New submission from twisteroid ambassador: In docs / Library Reference / asyncio / Transports and Protocols, it is mentioned that "asyncio currently implements transports for TCP, UDP, SSL, and subprocess pipes. The methods available on a transport depend on the transport’s kind." It also lists methods available on a BaseTransport, ReadTransport, WriteTransport, DatagramTransport and BaseSubprocessTransport. However, the docs does not explain which transports have methods from which base classes, or in other words which base classes each concrete transport class inherits from. And this may not be obvious: for example, a UDP transport certainly is a DatagramTransport, but is it also a ReadTransport, or a WriteTransport? (I feel like the answer is "no it isn't", but there are plenty of conflicting evidence. The docs show that WriteTransport has write_eof() and can_write_eof() -- methods clearly geared towards stream-like transports, and it duplicates abort() from DatagramTransport, so it would seem like WriteTransport and DatagramTransport are mutually exclusive. On the other hand, the default concrete implementation of _SelectorDatagramTransport actually inherits from Transport which inherits from both ReadTransport and WriteTransport, yet it does not inherit from DatagramTransport; As a result _SelectorDatagramTransport has all the methods from ReadTransport and WriteTransport, but many of them raise NotImplemented. This is why I'm asking this question in the first place: I found that the transport object I got from create_datagram_endpoint() has both pause_reading() and resume_reading() methods that raise NotImplemented, and thought that perhaps some event loop implementations would have these methods working, and I should try to use them. And before you say "UDP doesn't do flow control", asyncio actually does provide flow control for UDP on the writing end: see https://www.mail-archive.com/python-tulip@googlegroups.com/msg00532.html So it's not preposterous that there might be flow control on the reading end as well.) I think it would be nice if the documentation can state the methods implemented for each type of transport, as the designers of Python intended, so there's a clear expectation of what methods will / should be available across different implementations of event loops and transports. Something along the lines of "The methods available on a transport depend on the transport’s kind: TCP transports support methods declared in BaseTransport, ReadTransport and WriteTransport below, etc." ---------- assignee: docs@python components: Documentation, asyncio messages: 300083 nosy: docs@python, twisteroid ambassador, yselivanov priority: normal severity: normal status: open title: Is a UDP transport also a ReadTransport/WriteTransport? type: enhancement versions: Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31176> _______________________________________

1 0

[issue22635] subprocess.getstatusoutput changed behavior in 3.4 (maybe 3.3.4?)
by Nick Coghlan 09 Aug '17

09 Aug '17

Nick Coghlan added the comment: Issue filed with six about this: https://github.com/benjaminp/six/issues/207 It turns out to be somewhat timely on that side as well, as it turns out that six has a not-yet-released change adding "six.moves.commands", which doesn't currently account for this inadvertent incompatibility in the way exit codes are reported. ---------- nosy: +benjamin.peterson _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22635> _______________________________________

1 0

[issue22635] subprocess.getstatusoutput changed behavior in 3.4 (maybe 3.3.4?)
by Gregory P. Smith 09 Aug '17

09 Aug '17

Gregory P. Smith added the comment: I'll get to it. acassaigne's patches are already a good attempt at that, i'll probably find wording tweaks to make as I apply them. ---------- assignee: docs@python -> gregory.p.smith _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22635> _______________________________________

1 0

[issue31152] Tutorial wording implies an understanding of a concept prior to it being introduced
by Lorem Ipsum 09 Aug '17

09 Aug '17

New submission from Lorem Ipsum: Python 3.5.4 Tutorial Section 8.5. User-defined Exceptions Paragraph 2 (https://docs.python.org/3.5/tutorial/errors.html#user-defined-exceptions) states [emphasis mine]: "When creating a module that can raise several distinct errors, a common practice is to create a base class for exceptions defined by that module, and SUBCLASS THAT TO create specific exception classes for different error conditions:" The use of 'subclass' as a verb when it has not been used so prior is confusing, especially to beginners. The concept of a class is not formally covered until Section 9 and up until this point in the tutorial, 'class' has been used as a noun. When read with 'subclass' as a noun, the sentence is nonsensical. It may also be that the comma which precedes 'and' is not proper usage. Suggested improvement: change "subclass that to create specific classes for..." to "then create specific exception subclasses for..." "When creating a module that can raise several distinct errors, a common practice is to create a base class for exceptions defined by that module, and then create specific exception subclasses for different error conditions:" ---------- assignee: docs@python components: Documentation messages: 299962 nosy: Lorem Ipsum, docs@python priority: normal severity: normal status: open title: Tutorial wording implies an understanding of a concept prior to it being introduced type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31152> _______________________________________

3 3

[issue31156] Stopiteration terminates while-loop
by Günter Rote 09 Aug '17

09 Aug '17

New submission from Günter Rote: It should be mentioned in the documentation that A StopIteration exception raised in the body of a while loop will terminate (and is caught by) the while-loop, thus leading to graceful termination. A good place would be here: 1) https://docs.python.org/3/reference/compound_stmts.html#the-while-statement I don't know how such a StopIteration termination of a while loop affects the else-clause. This should be clarified. Here: 2) https://docs.python.org/3/library/exceptions.html#StopIteration it would be good to explicitly state: An enclosing while-loop or for-loop acts like an implicit catch for StopIteration. The StopIteration exception will terminate the loop. (I guess, a for-loop is also just terminated when the StopIteration originates in the BODY of the loop, although this is not the typical case.) ---------- assignee: docs@python components: Documentation messages: 299982 nosy: Günter Rote, docs@python priority: normal severity: normal status: open title: Stopiteration terminates while-loop type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31156> _______________________________________

2 2

[issue31154] Path.replace and Path.rename naming, behavior and documentation
by Alberto Gomez-Casado 09 Aug '17

09 Aug '17

New submission from Alberto Gomez-Casado: I find the naming of Path.replace quite unfortunate, coming from the os.path and basestring mindset, the expectation would be that it would change some substring by another substring in the Path instance. Instead, it _moves_ the file indicated by the Path object in the file system. Most of the methods of Path have no effect in the filesystem, and we have here one with a slightly misleading name which goes and moves your files around. Practically the same operation is done with Path.rename, which is less surprising since it matches popular OS commands/UIs (ren, Rename). IMHO Path.replace should not exist as is and a keyword modifier (silent?) for Path.rename toggles between the minor behavior differences of the two. Additionally: Both calls lack any kind of return, which leads me to expect after a rename/replace the Path instance would be changed to the new path. This is not the case, after the call the Path instance keeps "pointing" to the previous (and quite likely now useless) path. Returning the new path would be another reasonable option. In any case, I think the documentation should mention this behavior explicitly. And, while we are at it, having implemented the relatively dangerous replace/rename (along with convenience shorcuts for reading, writing, opening...), why was a Path.copy not included? ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 299976 nosy: Alberto Gomez-Casado, docs@python priority: normal severity: normal status: open title: Path.replace and Path.rename naming, behavior and documentation type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31154> _______________________________________

2 1

[issue31045] Add a language switch to the Python documentation
by Julien Palard 09 Aug '17

09 Aug '17

Changes by Julien Palard <julien+python(a)palard.fr>: ---------- stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31045> _______________________________________

1 0

[issue22635] subprocess.getstatusoutput changed behavior in 3.4 (maybe 3.3.4?)
by STINNER Victor 09 Aug '17

09 Aug '17

STINNER Victor added the comment: IMHO it's too late to change *again* subprocess.getstatusoutput() behaviour. Otherwise, it would mean that a complex test like "if not((3, 4) <= sys.version_info < (3, 7))" would be needed to workaround the bug... Whereas right now, basically we only have to check if we are running on Python 3 or not. (Python 3.0-3.3 is almost not used in the wild.) Instead we should just *document* the behaviour change using ".. versionchanged:: 3.4" in Doc/library/subprocess.rst. Any volunteer to do that? ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22635> _______________________________________

1 0