Mailman 3 November 2015 - docs

[issue19489] move quick search box above TOC
by Georg Brandl 09 Sep '16

09 Sep '16

New submission from Georg Brandl: >From Mark Summerfield:, The Quick search box is really useful, but it is annoying that its position varies from page to page. On pages with long tables of contents it is often out of sight. Why not put it above the Table of Contents. That way it is always in the same place and easily accessible. ---------- assignee: docs@python components: Documentation messages: 202091 nosy: docs@python, georg.brandl priority: normal severity: normal status: open title: move quick search box above TOC _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19489> _______________________________________

9 24

[issue20683] [doc] Ease comprehension of section 9.2 of docs for Python 2 and 3 with example
by Karl Richter 08 Sep '16

08 Sep '16

New submission from Karl Richter: The explanation of namespaces in section 9.2 in documentation (http://docs.python.org/3/tutorial/classes.html#python-scopes-and-namespaces) is just so complicated without (at least one tiny) example. The example would ease the comprehension of the section by a high factor. ---------- assignee: docs@python components: Documentation messages: 211607 nosy: docs@python, krichter priority: normal severity: normal status: open title: [doc] Ease comprehension of section 9.2 of docs for Python 2 and 3 with example type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20683> _______________________________________

4 4

[issue24372] Documentation for ssl.wrap_socket's ssl_version parameter is odd
by Eric V. Smith 08 Sep '16

08 Sep '16

New submission from Eric V. Smith: The documentation for ssl.wrap_socket()'s ssl_version parameter says "ssl_version={see docs}". But as far as I can tell, there's no reason not to document it as PROTOCOL_SSLv23, since that's what it actually is in the code. My use case is that I'm producing a utility function for an RFC-5804 Manage Sieve client, which implements starttls(). I want to expose most of wrap_sockets()'s parameters, and pass them in to ssl.wrap_socket() itself. In order to do so, I need to specify the default values to match wrap_socket(). But ssl_version's default isn't documented. Is the reason to allow us to change the default in a bug fix release? If that's the case, I suggest creating a sentinel value, like ssl.DEFAULT_PROTOCOL, and have that be the documented default. Then I could declare my parameter as defaulting to ssl.DEFAULT_PROTOCOL, pass it in to ssl.wrap_socket(), and have it use the "current" default. If that's a desirable solution, I'll happily write a patch. If so, it would just apply to 3.6, but if we just want to document the actual value of ssl_version, then it would apply to the versions I've selected. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 244742 nosy: docs@python, eric.smith priority: low severity: normal status: open title: Documentation for ssl.wrap_socket's ssl_version parameter is odd type: enhancement versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24372> _______________________________________

2 6

[issue23843] ssl.wrap_socket doesn't handle virtual TLS hosts
by John Nagle 08 Sep '16

08 Sep '16

New submission from John Nagle: ssl.wrap_socket() always uses the SSL certificate associated with the raw IP address, rather than using the server_host feature of TLS. Even when wrap_socket is used before calling "connect(port, host)", the "host" parameter isn't used by TLS. To get proper TLS behavior (which only works in recent Python versions), it's necessary to create an SSLContext, then use context.wrap_socket(sock, server_hostname="example.com") This behavior is backwards-compatible (the SSL module didn't talk TLS until very recently) but confusing. The documentation does not reflect this difference. There's a lot of old code and online advice which suggests using ssl.wrap_socket(). It works until you hit a virtual host with TLS support. Then you get the wrong server cert and an unexpected "wrong host" SSL error. Possible fixes: 1. Deprecate ssl.wrap_socket(), and modify the documentation to tell users to always use context.wrap_socket(). 2. Add a "server_hostname" parameter to ssl.wrap_socket(). It doesn't accept that parameter; only context.wrap_socket() does. Modify documentation accordingly. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 239834 nosy: docs@python, nagle priority: normal severity: normal status: open title: ssl.wrap_socket doesn't handle virtual TLS hosts versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23843> _______________________________________

4 4

[issue22301] smtplib.SMTP.starttls' documentation is just confusing
by Michele Orrù 08 Sep '16

08 Sep '16

New submission from Michele Orrù: <maker> hello! In <https://docs.python.org/2/library/smtplib.html#smtplib.SMTP.starttls> I read:: <maker> "If keyfile and certfile are provided, these are passed to the socket module’s ssl() function." <maker> socket.ssl() exists, though it is not documented (not even in /dev/library/socket) <maker> and furthermore, the link on ssl() points to the ssl module, which is just confusing. <bitdancer> maker: open an issue. (I'm noising ap and chris because afaik they were working on the latest ssl security stuff) ---------- assignee: docs@python components: Documentation, Library (Lib), email messages: 226074 nosy: barry, christian.heimes, docs@python, maker, pitrou, r.david.murray priority: normal severity: normal status: open title: smtplib.SMTP.starttls' documentation is just confusing versions: 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/issue22301> _______________________________________

6 6

[issue20842] pkgutil docs should reference glossary terms not PEP 302
by Nick Coghlan 07 Sep '16

07 Sep '16

New submission from Nick Coghlan: The pkgutil docs still point at PEP 302 when mentioning loaders, importers, etc. They should reference the glossary terms (:term:`loader`, etc) instead. ---------- assignee: docs@python components: Documentation messages: 212630 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: pkgutil docs should reference glossary terms not PEP 302 type: enhancement versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20842> _______________________________________

9 16

[issue23226] Add float linspace recipe to docs
by Andrew Barnert 06 Sep '16

06 Sep '16

New submission from Andrew Barnert: In a recent thread on python-ideas (https://mail.python.org/pipermail/python-ideas/2015-January/030817.html), it was concluded that Python should not have a range-like type for floats in the stdlib, but there should be some simple discussion of the alternatives in the docs. The attached diff describes the issues, demonstrates the simplest reasonable algorithm, and links to a recipe on ActiveState (which builds the same algorithm into a lazy sequence, and links to other recipes with different alternatives). ---------- assignee: docs@python components: Documentation files: stdtypes.rst.diff keywords: patch messages: 233893 nosy: abarnert, docs@python priority: normal severity: normal status: open title: Add float linspace recipe to docs type: enhancement versions: Python 3.5 Added file: http://bugs.python.org/file37684/stdtypes.rst.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23226> _______________________________________

4 6

[issue19504] Change "customise" to "customize".
by Eric V. Smith 26 Aug '16

26 Aug '16

New submission from Eric V. Smith: The python source code usually uses "customiz*" (341 instances) over "customis*" (19 instance, 8 of which are in logging). I realize "foolish consistency", and all that, but I think the documentation should all use the same conventions. I'd be happy to change the documentation. Most of these changes are in documentation or docstrings, but some are in comments. Which is why I'm assigning to docs@. I didn't change 2.0.rst, because that seemed like a historical document. ---------- assignee: docs@python components: Documentation files: customise.diff keywords: easy, patch messages: 202210 nosy: docs@python, eric.smith priority: low severity: normal stage: patch review status: open title: Change "customise" to "customize". versions: Python 3.4 Added file: http://bugs.python.org/file32507/customise.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19504> _______________________________________

8 11

[issue20124] The documentation for the atTime parameter of TimedRotatimeFileHandler is confusing
by R. David Murray 24 Aug '16

24 Aug '16

New submission from R. David Murray: The docs say that you can specify 'atTime' with a 'when' of 'midnight', but that makes no sense on the face of it. atTime with a weekday specification makes sense, but it would also make sense to use atTime with a when of D (and an interval), which is not mentioned as a possibility. It could also make sense to use it with other intervals (in other words, use the atTime as the starting point for the rotation calculation, instead of the last mod time or 'now'). If that doesn't work it should be stated that atTime will be ignored in those cases. Probably all the time related entries should be rewritten with the existence of atTime in mind, in order to clarify all the possible (and not possible) interactions. ---------- assignee: docs@python components: Documentation messages: 207323 nosy: docs@python, r.david.murray, vinay.sajip priority: normal severity: normal stage: needs patch status: open title: The documentation for the atTime parameter of TimedRotatimeFileHandler is confusing versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20124> _______________________________________

2 1

[issue23183] timeit CLI best of 3: undocumented output format
by Chathuranga 24 Aug '16

24 Aug '16

New submission from Chathuranga: easy Following command is executed in terminal to use timeit module to measure time. python -m timeit -v -n 3 "time.sleep(1)" Output of the command: raw times: 3 3 3 3 loops, best of 3: 1 sec per loop The interpretation of this output is unclear, and no details available in the documentation. https://docs.python.org/2/library/timeit.html#command-line-interface ---------- assignee: docs@python components: Documentation messages: 233570 nosy: docs@python, hachat priority: normal severity: normal status: open title: timeit CLI best of 3: undocumented output format type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23183> _______________________________________

3 5