Mailman 3 February 2019 - docs

[issue13231] sys.settrace - document 'some other code blocks' for 'call' event type
by anatoly techtonik 16 Mar '19

16 Mar '19

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/sys.html#sys.settrace While writing settrace function you need to know what kind of data is expected and how to get more information about it. Current documentation for sys.settrace doesn't give too much answers. To improve that situation at least with 'call' event: 1. Link 'frame' to the middle of table on inspect module page [1] 2. List all possible 'code blocks' for 'call' event (I know there is module in addition to function) 3. Provide example how to extract popular data for corresponding 'code block' (name for functions, name for modules, name for classes/methods, relative file path, line no, how to detect labmbda function) in a safe manner (inspect page contains some FUD about memory usage) 1. http://docs.python.org/library/inspect#types-and-members ---------- assignee: docs@python components: Documentation messages: 146009 nosy: docs@python, techtonik priority: normal severity: normal status: open title: sys.settrace - document 'some other code blocks' for 'call' event type _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13231> _______________________________________

2 2

[issue13277] tzinfo subclasses information
by Senthil Kumaran 16 Mar '19

16 Mar '19

New submission from Senthil Kumaran <senthil(a)uthcode.com>: This was in the docs mailing list, not translated to bug report Paul Koning wrote: Section 8.1.6 of the library manual talks about utcoffset(dt)-dst(dt) as the "standard offset" and says that this should not depend on the date or +time but only on the location. This is not true as there cases were certain locations changed the time offsets as per their convenience. It is either a doc fix to remove that sentence if the datetime.astimezone does not depend upon utcoffset(dt)-dst(dt), or if it does, then it is a code fix. ---------- assignee: docs@python messages: 146501 nosy: docs@python, orsenthil priority: normal severity: normal stage: needs patch status: open title: tzinfo subclasses information type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13277> _______________________________________

5 5

[issue13074] Improve documentation of locale encoding functions
by Geoffrey Bache 16 Mar '19

16 Mar '19

New submission from Geoffrey Bache <gjb1002(a)users.sourceforge.net>: The locale module provides locale.getdefaultlocale and locale.getpreferredencoding. The encodings returned by each are generally subtly different ('ISO8859-1' vs 'ISO-8859-1'), but the difference between these methods is not explained. A comment by Martin von Löwis from 2003 in http://bugs.python.org/issue813449 indicates that "getdefaultlocale should not be used in new code", if this is really the case then this should be in the docs. Anyone reading the docs from the top will currently encounter getdefaultlocale first and believe that this is the way to get the encoding. ---------- assignee: docs@python components: Documentation messages: 144677 nosy: docs@python, gjb1002 priority: normal severity: normal status: open title: Improve documentation of locale encoding functions versions: Python 2.6, 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/issue13074> _______________________________________

5 5

[issue23311] Update PC/example_nt and extending/windows.rst
by Steve Dower 16 Mar '19

16 Mar '19

New submission from Steve Dower: The installer for 3.5 will include an option to install debug binaries alongside the release ones, so we should update extending/windows.rst to explain that and generally describe how to build an extension. It should also refer to python3.dll at least once... The example project in PC/example_nt is fairly outdated. It could be updated to automatically find a 3.5 install and use the debug or release binaries/libraries from there. We could also include a 'test' project for PTVS (http://pytools.codeplex.com/) that helps write Python code for testing the extension and also has mixed-mode debugging enabled so people can step between the Python and the C code. (In fact, the PTVS team wants to do a sample project like this anyway, so maybe we can remove PC/example_nt and point to theirs...) ---------- assignee: docs@python components: Documentation, Windows messages: 234624 nosy: docs@python, steve.dower, tim.golden, zach.ware priority: normal severity: normal status: open title: Update PC/example_nt and extending/windows.rst versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23311> _______________________________________

2 3

[issue20749] shutil.unpack_archive(): security concerns not documented
by Jakub Wilk 16 Mar '19

16 Mar '19

New submission from Jakub Wilk: shutil.unpack_archive() uses tarfile.extractall() under the hood, so it's not suitable for unpacking untrusted archives. But this fact is not documented. Please add a security warning to shutil.unpack_archive() documentation. ---------- assignee: docs@python components: Documentation messages: 212029 nosy: docs@python, jwilk priority: normal severity: normal status: open title: shutil.unpack_archive(): security concerns not documented _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20749> _______________________________________

3 3

[issue34464] docs: keywords are special - eg constants.html
by Jonathan Fine 16 Mar '19

16 Mar '19

New submission from Jonathan Fine <jfine2358(a)gmail.com>: The identifiers True, False, None and __debug__ are keywords in the language. For example >>> __debug__ = __debug__ SyntaxError: assignment to keyword 1. The page constants.html incorrectly says then are in the built-in namespace. Some of them were, once. 2. The list keyword.kwlist does not contain __debug__. (Problem in Lib/keyword.py.) 3. https://docs.python.org/3/reference/datamodel.html for None, NotImplemented, etc. 4. There may be other places that need looking at. See also: https://github.com/jfine2358/py-jfine2358/blob/master/docs/none-is-special.… Credit: The __debug__ problem arises from Steve D'Aprano's message https://mail.python.org/pipermail/python-ideas/2018-August/052917.html The std lib contains a test that this correctly raises SyntaxError: def f(*, x=lambda __debug__:0): pass ---------- assignee: docs@python components: Documentation messages: 323904 nosy: docs@python, jfine2358 priority: normal severity: normal status: open title: docs: keywords are special - eg constants.html type: enhancement versions: Python 2.7, 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/issue34464> _______________________________________

4 6

[issue34713] csvwriter.writerow()'s return type is undocumented
by Nicholas Chammas 13 Mar '19

13 Mar '19

New submission from Nicholas Chammas <nicholas.chammas(a)gmail.com>: It _looks_ like csvwriter.writerow() returns the number of bytes (or is it characters?) written. However, there is no documentation of this: https://docs.python.org/3.7/library/csv.html#csv.csvwriter.writerow Is this behavior part of the method's "contract"? And if so, shouldn't we document it? The same goes for csvwriter.writerows(). ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 325557 nosy: docs@python, nchammas priority: normal severity: normal status: open title: csvwriter.writerow()'s return type is undocumented type: enhancement versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34713> _______________________________________

3 5

Possible Documentation bug: Chapter 8. Errors and Exceptions
by Rahul Babtiwale 12 Mar '19

12 Mar '19

Hello, I was going through the chapter as per the below link : https://docs.python.org/3/tutorial/errors.html#handling-exceptions The code shown is as below: class B(Exception): pass class C(B): pass class D(C): pass for cls in [B, C, D]: try: raise cls() except D: print("D") except C: print("C") except B: print("B") - Now as per the above code the statement written below confused me a little: *"A class in an except <https://docs.python.org/3/reference/compound_stmts.html#except> clause is compatible with an exception if it is the same class or a base class thereof (but not the other way around — an except clause listing a derived class is not compatible with a base class)."* - A class in the except clause is compatible with an exception if it is the same class: I agree to this. - However, the next part "or a base class thereof" confused me. Does this mean that if it is a base class (i.e a class which inherits from the exception class and is the base class of all the other classes C & D) only then will it be compatible? - Because if i reverse the order of the except clauses, the only prints would be 'B','B' and 'B'. I think this elaboration needs to be done. I would request you to provide your insights on this. Thanks and Regards, Rahul

2 2

[issue28124] Rework SSL module documentation
by Christian Heimes 12 Mar '19

12 Mar '19

New submission from Christian Heimes: The documentation of the SSL module needs a rework. It's confusing and hard to understand even for experienced developers. The documentation should start with basic use cases and easy-to-reuse best practices. * The module starts with move ssl.wrap_socket() but it's no longer best practice. The section should be moved down and favor of a quick introduction of SSLContext. * ssl.create_default_context() is the best way to create a SSLContext. Mention that purpose flags and that Purpose.SERVER_AUTH is the correct setting on the client side. It means: "Create a context to authenticate the certs of a TLS server." (correct also for ftp, imap, ldap, smtp and so on). * The protocol table is confusing and does not mention the meaning of PROTOCOL_SSLv23 (aka PROTOCOL_TLS). It's auto-negotiation of the highest TLS protocol version and takes OP_NO_* SSLContext.options into account. PROTOCOL_TLS_CLIENT and PROTOCOL_TLS_SERVER are the recommended options nowadays. * Don't confront users with CERT_OPTIONAL in the first section. It's a super special mode for client cert authentication on the server side. On the client side, CERT_REQUIRED is the right mode with CERT_NONE as workaround. On the server side CERT_NONE (default) is usually the right setting. * check_hostname is a client-side option that should be enabled all the time. * Explain that users can load the public key of a self-signed certificate like a CA cert to have cert validation even for self-signed certs. ---------- assignee: docs@python components: Documentation messages: 276238 nosy: christian.heimes, docs@python priority: high severity: normal stage: needs patch status: open title: Rework SSL module documentation type: enhancement versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28124> _______________________________________

4 8

[issue26018] documentation of ZipFile file name encoding
by Martin von Gagern 10 Mar '19

10 Mar '19

New submission from Martin von Gagern: https://docs.python.org/3/library/zipfile.html#zipfile.ZipFile.write writes: “Note: There is no official file name encoding for ZIP files. If you have unicode file names, you must convert them to byte strings in your desired encoding before passing them to write(). WinZip interprets all file names as encoded in CP437, also known as DOS Latin.” I think this is wrong in many ways. Firstly, APPNOTE.TXT used to explicitely define CP437 as the standard, and it's still the standard in the absence of general purpose bit 11 and a more specific description using the 0x0008 Extra Field. On the other hand, we do have that general purpose bit these days, so there are now not just one but two well-defined file name encodings. And thirdly, encoding the string to bytes as suggested will in fact lead to a run time error, since ZipInfo expects to do this conversion itself. See work towards issue1734346, starting at commit 8e33f316ce14, for details on when this was addressed in the source code. ---------- assignee: docs@python components: Documentation messages: 257567 nosy: docs@python, gagern priority: normal severity: normal status: open title: documentation of ZipFile file name encoding type: behavior versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26018> _______________________________________

4 5