Mailman 3 March 2019 - docs

[issue35765] Document references object x but doesn't show it in the example
by Patrick Rice 26 Sep '20

26 Sep '20

New submission from Patrick Rice <price(a)zoox.com>: https://docs.python.org/3.5/tutorial/inputoutput.html If you have an object x, you can view its JSON string representation with a simple line of code: >>> >>> import json >>> json.dumps([1, 'simple', 'list']) '[1, "simple", "list"]' ---------- assignee: docs@python components: Documentation messages: 333917 nosy: Patrick Rice, docs@python priority: normal severity: normal status: open title: Document references object x but doesn't show it in the example versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35765> _______________________________________

4 3

[issue24757] Installing Py on Windows: Need to restart or logout for path to be added
by John Palermo 24 Sep '20

24 Sep '20

New submission from John Palermo: Something I suppose many new users could stumble over: After installing Python and trying out "pip" or "python" on the command line nothing is found. You have to re-start Windows or re-log into your account. I suggest adding this information to the documentation here https://docs.python.org/2/using/windows.html#installing-python and also adding it to the Windows installer description for the "add Python to your path" option. ---------- assignee: docs@python components: Documentation messages: 247688 nosy: John Palermo, docs@python priority: normal severity: normal status: open title: Installing Py on Windows: Need to restart or logout for path to be added type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24757> _______________________________________

6 6

[issue18280] Documentation is too personalized
by Serhiy Storchaka 19 Sep '20

19 Sep '20

New submission from Serhiy Storchaka: Some documentation files contain a number of I/my/me. Looks like they grew from personal modules and personal articles. Perhaps the official documentation needs more depersonalized style. Here is full list of such files: Doc/c-api/exceptions.rst Doc/c-api/long.rst Doc/distutils/builtdist.rst Doc/extending/extending.rst Doc/extending/windows.rst Doc/howto/argparse.rst Doc/howto/curses.rst Doc/howto/functional.rst Doc/howto/regex.rst Doc/howto/sockets.rst Doc/howto/urllib2.rst Doc/install/index.rst Doc/library/audioop.rst Doc/library/ctypes.rst Doc/library/doctest.rst Doc/library/heapq.rst Doc/library/numbers.rst Doc/library/ossaudiodev.rst Doc/library/tk.rst Doc/library/unittest.mock-examples.rst Doc/library/unittest.mock.rst Doc/reference/introduction.rst Doc/tutorial/classes.rst The list doesn't include FAQs where it may be appropriate and whatsnew files. Andrew Kuchling recently has fixed Doc/howto/unicode.rst for this issue (as part of issue4153). ---------- assignee: docs@python components: Documentation messages: 191636 nosy: akuchling, docs@python, eric.araujo, ezio.melotti, georg.brandl, serhiy.storchaka priority: normal severity: normal status: open title: Documentation is too personalized versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18280> _______________________________________

11 17

[issue25467] Put “deprecated” warnings first
by Tony R. 19 Sep '20

19 Sep '20

New submission from Tony R.: Python has wonderful, detailed documentation. I love it! Unfortunately, I have often found myself reading the otherwise-excellent documentation on a class/function/whatever, only to find out at the END of my reading that it is deprecated. This is frustrating, and counter-intuitive. If something is deprecated, I want to know it before I read any further. I have attached a patch with the relevant changes. I hope it helps! ---------- assignee: docs@python components: Documentation files: 0001-Move-deprecated-blocks-to-the-beginning-of-their-doc.patch keywords: patch messages: 253391 nosy: Tony R., docs@python priority: normal severity: normal status: open title: Put “deprecated” warnings first type: enhancement Added file: http://bugs.python.org/file40851/0001-Move-deprecated-blocks-to-the-beginni… _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25467> _______________________________________

5 13

[issue33953] The DEFAULT_ENTROPY variable used to store the current default random bytes value should be documented for `secrets` module
by Serge Matveenko 14 Sep '20

14 Sep '20

New submission from Serge Matveenko <serge(a)matveenko.ru>: There is the corresponding section on the topic here https://github.com/python/cpython/blob/3.6/Doc/library/secrets.rst#how-many… The current value of 32 bytes is mentioned there correctly. Unfortunately, there is no way to know which constant in the `secrets` stores this value. It is easy to imagine a use case to use say `DEFAULT_ENTROPY * 4` in the code and stay updated with the default entropy being increased over time. Thus, it looks reasonable to document the `secrets.DEFAULT_ENTROPY` constant in the module docs. ---------- assignee: docs@python components: Documentation messages: 320402 nosy: docs@python, lig priority: normal severity: normal status: open title: The DEFAULT_ENTROPY variable used to store the current default random bytes value should be documented for `secrets` module type: enhancement versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33953> _______________________________________

3 5

[issue28499] Logging module documentation needs a rework.
by Pierre Bousquie 13 Sep '20

13 Sep '20

New submission from Pierre Bousquie: At pyconf-fr 2016 Florian Strzelecki (@Exirel) made a great talk on how to make good documentation. At one time he asked "python logging doc?, did you realy found it clear and helpfull?" clear answer from the crowd: not at all. Stephane Wirtel ask us (the unhappy folks) : Hey send a bug request, then the pull request and... i'll be there to help :). So i'm here for first step: fill the bug issue. I'm willing to fix this doc! ---------- assignee: docs@python components: Documentation messages: 279141 nosy: Pierre Bousquie, docs@python priority: normal severity: normal status: open title: Logging module documentation needs a rework. type: enhancement versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28499> _______________________________________

5 10

[issue33239] tempfile module: functions with the 'buffering' option are incorrectly documented
by Martin Falatic 13 Sep '20

13 Sep '20

New submission from Martin Falatic <martin(a)falatic.com>: The documentation for the tempfile module in Python 3.x for the `buffering` option is incorrect: https://docs.python.org/3/library/tempfile.html TemporaryFile, NamedTemporaryFile, and SpooledTemporaryFile all take the `buffering` option, which in turn appears to correlate to the Python 2.7 option `bufsize`, which was and continues to be an integer (per the source). In the 3.x documentation the default signature for TemporaryFile, NamedTemporaryFile, and SpooledTemporaryFile includes `buffering=None`. Actually specifying None as a default for this will cause an exception (`TypeError: an integer is required (got type NoneType)`). There is a cross-reference in the 3.x tempfile docs to `open` (https://docs.python.org/3/library/functions.html#open) which in turn shows the correct signature to use for `buffering`. Additionally, the source code is clearly documented (https://github.com/python/cpython/blob/master/Lib/tempfile.py) A good correction would be to ensure `buffering=-1` is documented as the default for the three functions in tempfile, with an additional note explicitly stating that -1 == no buffering, and the existing `open` cross-reference retained. ---------- assignee: docs@python components: Documentation messages: 315072 nosy: MartyMacGyver, docs@python priority: normal severity: normal status: open title: tempfile module: functions with the 'buffering' option are incorrectly documented versions: 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/issue33239> _______________________________________

6 13

[issue25912] Use __spec__.__name__ instead of __name__ in the docs where appropriate
by Antony Lee 11 Sep '20

11 Sep '20

New submission from Antony Lee: There are a couple of places in the docs where it would be appropriate to replace __name__ by __spec__.__name__ in order to support the case where the module is executed as the __main__ module: - logging.getLogger should certainly use __spec__.__name__ so that the logger hierarchy be respected (otherwise, when running "python -mpkg.subpkg", the logger of pkg.subpkg is named "__main__" and thus not a child of the "pkg" logger). - examples for argparse.ArgumentParser (e.g. in the docs for venv) should use __spec__.__name__ instead of __name__ for the "prog=" argument. (not guaranteed to be exhaustive) ---------- assignee: docs@python components: Documentation messages: 256743 nosy: Antony.Lee, docs@python priority: normal severity: normal status: open title: Use __spec__.__name__ instead of __name__ in the docs where appropriate versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25912> _______________________________________

2 3

[issue35228] Index search in CHM help crashes viewer
by Christian Ullrich 04 Sep '20

04 Sep '20

New submission from Christian Ullrich <chris(a)chrullrich.net>: Typing into the index keyword field frequently crashes the CHM viewer with the first or second character. The Python CHMs are the only ones that I see this crash with; it started around 3.6 or so. >From event log: Faulting application name: hh.exe, version: 10.0.17134.1, time stamp: 0xa0eff942 Faulting module name: hhctrl.ocx, version: 10.0.17134.48, time stamp: 0x412ce02a Exception code: 0xc0000005 Fault offset: 0x00000000000387b2 Faulting process ID: 0x3558 Faulting application start time: 0x01d47b3f8db53eef Faulting application path: C:\Windows\hh.exe Faulting module path: C:\Windows\System32\hhctrl.ocx Report ID: 53f84d38-adb4-4c0b-bd45-9bce02406e6f Faulting package full name: Faulting package-relative application ID: This particular crash involved the file from 3.7.1: sha1(doc\python371.chm) = 1c0e2d861cadc759436bfac0a767c5bb633423f9 ---------- assignee: docs@python components: Documentation, Windows messages: 329824 nosy: chrullrich, docs@python, paul.moore, steve.dower, tim.golden, zach.ware priority: normal severity: normal status: open title: Index search in CHM help crashes viewer type: behavior versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35228> _______________________________________

7 14

[issue30826] More details in reference 'Looping through a list in Python and modifying it'
by Anmol Gupta 03 Sep '20

03 Sep '20

New submission from Anmol Gupta: Documentation section: https://docs.python.org/3/reference/compound_stmts.html#for The documentation does not explain at all why is there an infinite loop when not using a copy of the list. It leaves the reader in a confused state. Even there are questions concerning the same on stackoverlflow: https://stackoverflow.com/questions/44633798/loop-through-a-list-in-python-… ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30826> _______________________________________

6 13