Mailman 3 June 2019 - docs

[issue36960] Make datetime docs more user-friendly
by Brad Solomon 12 Sep '19

12 Sep '19

New submission from Brad Solomon <brad.solomon.1124(a)gmail.com>: The datetime docs are chalk full of detail. This is a positive aspect, and represents a huge amount of work by Tim Peters and A.M. Kuchling. However, it also may function as an obstacle for beginner readers and those simply seeking to answer a basic question or see a straightforward usage example. Rather than seeing an example-based explanation of a common use-case, they are bombarded with technical detail and edge cases. I propose some restructuring of the datetime docs with the goal of making them more reader-friendly. The goal is not to eliminate any of the detail, but to restructure things so as to bring the "everyday" parts into more prominent real estate. The changes here all make an effort to reflect what's espoused by "Documenting Python" at https://devguide.python.org/documenting/. I have some additional changes in mind but wanted to put this here now to gauge receptiveness to the existing changes. ---------- assignee: docs@python components: Documentation messages: 342813 nosy: bsolomon1124, docs@python priority: normal pull_requests: 13321 severity: normal status: open title: Make datetime docs more user-friendly type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36960> _______________________________________

4 6

[issue36373] asyncio.gather: no docs for deprecated loop parameter
by dtrauma 12 Sep '19

12 Sep '19

New submission from dtrauma <python-bugs(a)digital-trauma.de>: https://docs.python.org/3.7/library/asyncio-task.html#running-tasks-concurr… For asyncio.gather, the docs should probably say The loop argument is deprecated and scheduled for removal in Python 3.10. as they do for all the other loop arguments of other functions. ---------- assignee: docs@python components: Documentation messages: 338406 nosy: docs@python, dtrauma priority: normal severity: normal status: open title: asyncio.gather: no docs for deprecated loop parameter type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36373> _______________________________________

7 48

[issue33459] Fix "tuple display" mention in Expressions
by Andrés Delfino 12 Sep '19

12 Sep '19

New submission from Andrés Delfino <adelfino(a)gmail.com>: Expressions mentions "tuple displays" in 6.16 (Operator precedence). AFAIK, there ano "tuple displays". Expressions mentions list, dict, and set displays, and then talks about generator expressions. I guess "parenthesized expressions" should be the term that fits here? ---------- assignee: docs@python components: Documentation messages: 316380 nosy: adelfino, docs@python priority: normal severity: normal status: open title: Fix "tuple display" mention in Expressions type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33459> _______________________________________

6 15

documentation bug
by Hug Capella 12 Sep '19

12 Sep '19

at the page with URL: https://docs.python.org/3/library/stdtypes.html that text: Cast 1D/unsigned char to 2D/unsigned long: should be: Cast 1D/unsigned long to 2D/unsigned long:

2 4

[issue13474] Mention of "-m" Flag Missing From Doc on Execution Model
by Eric Snow 12 Sep '19

12 Sep '19

New submission from Eric Snow <ericsnowcurrently(a)gmail.com>: The doc on code execution[1] leaves out mention of the -m flag. Seems like it belongs there too. [1] Doc/reference/executionmodel.rst ---------- assignee: docs@python components: Documentation messages: 148288 nosy: docs@python, eric.snow priority: normal severity: normal status: open title: Mention of "-m" Flag Missing From Doc on Execution Model versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13474> _______________________________________

8 10

[issue35325] imp.find_module() return value documentation discrepancy
by Stefan Bauer (TraceTronic) 12 Sep '19

12 Sep '19

New submission from Stefan Bauer (TraceTronic) <stefan.bauer(a)tracetronic.de>: I’d like to report a discrepancy between the documentation and implementation of the method imp.find_module(). The documentation <https://docs.python.org/3.7/library/imp.html#imp.find_module> currently says “If the module does not live in a file, the returned file is None, pathname is the __empty_string__, […]” The implementation <https://github.com/python/cpython/blob/master/Lib/imp.py#L272>, on the other hand, returns __None__ for built-in and frozen modules. Yours, Stefan ---------- assignee: docs@python components: Documentation messages: 330495 nosy: StefanBauerTT, docs@python priority: normal severity: normal status: open title: imp.find_module() return value documentation discrepancy versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35325> _______________________________________

5 11

[issue35685] Add samples on patch.dict of the use of decorator and in class
by Emmanuel Arias 12 Sep '19

12 Sep '19

New submission from Emmanuel Arias <emmanuelarias30(a)gmail.com>: Hi! I create this PR to add a samples of the use of patch.dict with decorator on method and class. I think that is a good improve because the doc mentions the use of patch.dict with decorator on method and class but don't show any samples. Other, question, why on unittest.mock documentation is used `assert *something* == *something*` and it is not used the assertEquals (and others)? IMHO this would be better for unittest docs. Regards ---------- assignee: docs@python components: Documentation messages: 333226 nosy: docs@python, eamanu, michael.foord priority: normal severity: normal status: open title: Add samples on patch.dict of the use of decorator and in class type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35685> _______________________________________

3 8

[issue36191] pubkeys.txt contains bogus keys
by Thomas Jollans 12 Sep '19

12 Sep '19

New submission from Thomas Jollans <tjol(a)tjol.eu>: The file https://www.python.org/static/files/pubkeys.txt contains some bogus GPG keys with 32-bit key IDs identical to actual release manager key IDs. (see below) I imagine these slipped in by accident and may have been created by someone trying to make a point. (see also: https://evil32.com/) This is obviously not a serious security concern, but it would be a better look if the file contained only the real keys, and if https://www.python.org/downloads/ listed fingerprints. Pointed out by Peter Otten on python-list. https://mail.python.org/pipermail/python-list/2019-March/739788.html These are the obvious fake keys included: pub:-:1024:1:2056FF2E487034E5:1137310238:::-: fpr:::::::::BA749AC731BE5A28A65446C02056FF2E487034E5: uid:::::::::Totally Legit Signing Key <mallory(a)example.org>: pub:-:1024:1:C2E8D739F73C700D:1245930666:::-: fpr:::::::::7F54F95AC61EE1465CFE7A1FC2E8D739F73C700D: uid:::::::::Totally Legit Signing Key <mallory(a)example.org>: pub:-:1024:1:FABF4E7B6F5E1540:1512586955:::-: fpr:::::::::FD01BA54AE5D9B9C468E65E3FABF4E7B6F5E1540: uid:::::::::Totally Legit Signing Key <mallory(a)example.org>: pub:-:1024:1:0E93AA73AA65421D:1202230939:::-: fpr:::::::::41A239476ABD6CBA8FC8FCA90E93AA73AA65421D: uid:::::::::Totally Legit Signing Key <mallory(a)example.org>: pub:-:1024:1:79B457E4E6DF025C:1357547701:::-: fpr:::::::::9EB49DC166F6400EF5DA53F579B457E4E6DF025C: uid:::::::::Totally Legit Signing Key <mallory(a)example.org>: pub:-:1024:1:FEA3DC6DEA5BBD71:1432286066:::-: fpr:::::::::801BD5AE93D392E22DDC6C7AFEA3DC6DEA5BBD71: uid:::::::::Totally Legit Signing Key <mallory(a)example.org>: pub:-:1024:1:236A434AA74B06BF:1366844479:::-: fpr:::::::::B43A1F9EDE867FE48AD1D718236A434AA74B06BF: uid:::::::::Totally Legit Signing Key <mallory(a)example.org>: pub:-:1024:1:F5F4351EA4135B38:1250910569:::-: fpr:::::::::4F3B83264BC0C99EDADBF91FF5F4351EA4135B38: uid:::::::::Totally Legit Signing Key <mallory(a)example.org>: pub:-:1024:1:D84E17F918ADD4FF:1484232656:::-: fpr:::::::::3A3E83C9DB23EF8B5E5DADBED84E17F918ADD4FF: uid:::::::::Totally Legit Signing Key <mallory(a)example.org>: pub:-:1024:1:876CCCE17D9DC8D2:1164804081:::-: fpr:::::::::C1FCAEABC21C54C03120EF6A876CCCE17D9DC8D2: uid:::::::::Totally Legit Signing Key <mallory(a)example.org>: pub:-:1024:1:0F7232D036580288:1140898452:::-: fpr:::::::::12FF24C7BCEE1AE82EC38B3A0F7232D036580288: uid:::::::::Totally Legit Signing Key <mallory(a)example.org>: pub:-:1024:1:27801D7E6A45C816:1287310846:::-: fpr:::::::::8CA98EEE6FE14D11DF37694927801D7E6A45C816: uid:::::::::Totally Legit Signing Key <mallory(a)example.org>: ---------- assignee: docs@python components: Documentation messages: 337156 nosy: docs@python, tjollans priority: normal severity: normal status: open title: pubkeys.txt contains bogus keys type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36191> _______________________________________

5 5

[issue32008] Example suggest to use a TLSv1 socket
by Kurt Roeckx 12 Sep '19

12 Sep '19

New submission from Kurt Roeckx <kurt(a)roeckx.be>: Here: https://docs.python.org/3/library/ssl.html#ssl.SSLContext.check_hostname And here: https://docs.python.org/2/library/ssl.html#ssl.SSLContext.check_hostname It uses ssl.PROTOCOL_TLSv1, which is a bad example. Please change it to PROTOCOL_SSLv23 or PROTOCOL_TLS. (Those were the first 2 examples I could find via google on how to create an ssl connection using python.) ---------- assignee: docs@python components: Documentation messages: 306093 nosy: docs@python, kroeckx priority: normal severity: normal status: open title: Example suggest to use a TLSv1 socket type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32008> _______________________________________

6 19

[issue9938] Documentation for argparse interactive use
by Jay T 12 Sep '19

12 Sep '19

New submission from Jay T <jaytula(a)gmail.com>: I want to create a custom interactive shell where I continually do parse_args. Like the following: parser = argparse.ArgumentParser() command = raw_input() while(True): args = parser.parse_args(shlex.split(command)) # Do some magic stuff command = raw_input() The problem is that if I give it invalid input, it errors and exits with a help message. I learned from argparse-users group that you can override the exit method like the following: class MyParser(ArgumentParser): def exit(self, status=0, message=None): # do whatever you want here I would be nice to have this usage documented perhaps along with best practices for doing help messages in this scenario. ---------- assignee: docs@python components: Documentation messages: 117287 nosy: docs@python, jayt priority: normal severity: normal status: open title: Documentation for argparse interactive use type: feature request versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9938> _______________________________________

16 28