Mailman 3 March 2014 - docs

[issue20787] typo in asyncio docs for subprocess_exec()
by akira March 13, 2014

March 13, 2014

New submission from akira: subprocess' stdout pipe is open for *reading* but its value is documented as an argument for `BaseEventLoop.connect_write_pipe`. It should be `BaseEventLoop.connect_read_pipe` instead. As it currently is for subprocess' stderr. The patch is attached. ---------- assignee: docs@python components: Documentation files: typo-subprocess_exec-docs.patch keywords: patch messages: 212316 nosy: akira, docs@python priority: normal severity: normal status: open title: typo in asyncio docs for subprocess_exec() versions: Python 3.4 Added file: http://bugs.python.org/file34235/typo-subprocess_exec-docs.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20787> _______________________________________

3 2

[issue20266] Bring Doc/faq/windows up to date
by Zachary Ware March 13, 2014

March 13, 2014

New submission from Zachary Ware: The Python on Windows faq could use some TLC. For instance, cx_Freeze should be mentioned in the faq about creating an executable (and py2exe should either mention that it doesn't quite support 3.x yet, or just be removed until it does), and the embedding faq should be cleaned up with proper voice and formatting (and the "undocumented facts" should be documented). ---------- assignee: docs@python components: Documentation, Windows keywords: easy messages: 208138 nosy: docs@python, zach.ware priority: normal severity: normal stage: needs patch status: open title: Bring Doc/faq/windows up to date type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20266> _______________________________________

6 6

[issue12354] packaging.pypi.simple docs use both client and crawler variable, which might be confusing
by Filip Gruszczyński March 13, 2014

March 13, 2014

New submission from Filip Gruszczyński <gruszczy(a)gmail.com>: In documentation for packaging.pypi.simple in first code snippet crawler variable is created on which further operations will be performed. However in all next snippets there is client variable, which is a little confusing on first sight. This could be consistent throughout the whole page. ---------- assignee: docs@python components: Distutils2, Documentation messages: 138538 nosy: alexis, docs@python, eric.araujo, gruszczy priority: normal severity: normal status: open title: packaging.pypi.simple docs use both client and crawler variable, which might be confusing versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12354> _______________________________________

4 9

[issue8255] Packaging step-by-step tutorial
by Éric Araujo March 13, 2014

March 13, 2014

Changes by Éric Araujo <merwok(a)netwok.org>: ---------- resolution: -> out of date stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8255> _______________________________________

1 0

[issue20903] smtplib.SMTP raises socket.timeout
by Chris Clark March 12, 2014

March 12, 2014

Chris Clark added the comment: I am concerned about the policy of not documenting all exceptions that are raised. It sounds like there is no straightforward way to write a comprehensive except statement without using a bare except or catching some base exception. I consider it dangerous to catch broad exception classes because it can hide some nasty bugs. And while I may be able to use OSError here, how can I be sure that you aren't forgetting about some other unexpected exception? Furthermore, I don't want to catch all OSErrors, only those relating to the SMTP server connection failing. I definitely agree that it is preferable to be able to differentiate different types of exceptions. It seems to me that the best solution would be to make subclasses of SMTPConnectError so that I can catch SMTPConnectError if I don't care about the type or SMTPConnectTimeoutError if I do care about the type. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20903> _______________________________________

1 0

[issue20903] smtplib.SMTP raises socket.timeout
by R. David Murray March 12, 2014

March 12, 2014

R. David Murray added the comment: In general we don't document what gets raised unless it is unique to a module or has non-obvious implications. In this case, getting socket exceptions out of a network library should be "obvious" in some sense :). In particular, both SMTPConnectError and socket.error are subclasses of OSError, so if you want to catch them all, catch OSError. Now, that said, I have some sympathy to the idea that something triggered by a parameter to the call should perhaps result in an SMTPConnectError. However, the argument *against* it is that it makes it difficult to differentiate the timeout error from other connection errors, which one might well want to do. We've moved toward making it easier to tell classes of errors apart (see PEP 3151), so this would be a regression in that approach. Given that the timeout is part of the signature, I think it does make sense to mention that the timeout will raise a socket.timeout error. ---------- assignee: -> docs@python components: +Documentation -Library (Lib) keywords: +easy nosy: +docs@python, r.david.murray stage: -> needs patch versions: +Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20903> _______________________________________

1 0

[issue4744] asynchat documentation needs to be more precise
by Éric Araujo March 12, 2014

March 12, 2014

Changes by Éric Araujo <merwok(a)netwok.org>: ---------- versions: +Python 3.3, Python 3.4 -Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue4744> _______________________________________

1 0

[issue20135] FAQ need list mutation answers
by R. David Murray March 12, 2014

March 12, 2014

R. David Murray added the comment: M. Votz: I like your entry, but I think it should be titled "Why did changing list 'a' also change list 'b'?" That's the form I've always encountered this question in. Then the answer can start of with "It didn't, 'a' and 'b' are the same list." and then go on with your text. Since Éric concurs, lets go ahead and move that other answer. Probably to right before "How can I pass optional or keywords parameters from one function to another?" ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20135> _______________________________________

1 0

[issue15231] update PyPI upload doc to say --no-raw passed to rst2html.py
by Chris Jerdonek March 12, 2014

March 12, 2014

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: I had an issue whereby my reST long_description wasn't getting rendered as HTML when uploaded to PyPI. Following the instructions here did not work as-is: http://docs.python.org/dev/distutils/uploading.html#pypi-package-display It seems that PyPI passes --no-raw (no HTML allowed) to rst2html.py, in which case the guidance would be better updated to read-- $ python setup.py --long-description | rst2html.py --no-raw > output.html ---------- assignee: docs@python components: Documentation keywords: easy messages: 164445 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: update PyPI upload doc to say --no-raw passed to rst2html.py versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15231> _______________________________________

5 39

[issue19627] python open built-in function - "updating" is not defined
by Bulwersator March 12, 2014

March 12, 2014

New submission from Bulwersator: see http://stackoverflow.com/questions/1466000/python-open-built-in-function-di… - "The Python docs conveniently leave out the crucial explanation that "open the file for updating" means "opens the file for both reading and writing", which answers my question." ---------- assignee: docs@python components: Documentation messages: 203075 nosy: Bulwersator, docs@python priority: normal severity: normal status: open title: python open built-in function - "updating" is not defined _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19627> _______________________________________

7 10