Mailman 3 July 2018 - docs

[issue29127] Incorrect reference names in asyncio.subprocess documentation
by Eric Ahn Oct. 2, 2020

Oct. 2, 2020

New submission from Eric Ahn: On this page of the documentation https://docs.python.org/3/library/asyncio-subprocess.html it seems that some of the reference names are incorrect. Namely, asyncio.subprocess.PIPE is referred to as asyncio.asyncio.subprocess.PIPE (along with STDOUT and DEVNULL), plus asyncio.subprocess.Process is referred to as asyncio.asyncio.subprocess.Process. This is reflected in the permalinks as well as when one tries to reference these via intersphinx (which is how I discovered it; I was trying to link to this page and was failing). ---------- assignee: docs@python components: Documentation messages: 284418 nosy: Eric Ahn, docs@python priority: normal severity: normal status: open title: Incorrect reference names in asyncio.subprocess documentation versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29127> _______________________________________

3 2

[issue24757] Installing Py on Windows: Need to restart or logout for path to be added
by John Palermo Sept. 24, 2020

Sept. 24, 2020

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 Sept. 19, 2020

Sept. 19, 2020

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. Sept. 19, 2020

Sept. 19, 2020

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 Sept. 14, 2020

Sept. 14, 2020

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 Sept. 13, 2020

Sept. 13, 2020

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 Sept. 13, 2020

Sept. 13, 2020

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 Sept. 11, 2020

Sept. 11, 2020

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

[issue30826] More details in reference 'Looping through a list in Python and modifying it'
by Anmol Gupta Sept. 3, 2020

Sept. 3, 2020

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

[issue13828] Further improve casefold documentation
by Jim Jewett Aug. 24, 2020

Aug. 24, 2020

New submission from Jim Jewett <jimjjewett(a)gmail.com>: > http://hg.python.org/cpython/rev/0b5ce36a7a24 > changeset: 74515:0b5ce36a7a24 > + Casefolding is similar to lowercasing but more aggressive because it is > + intended to remove all case distinctions in a string. For example, the German > + lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already > + lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold` > + converts it to ``"ss"``. Perhaps add the recommendation to canonicalize as well. A complete, but possibly too long, try is below: Casefolding is similar to lowercasing but more aggressive because it is intended to remove all case distinctions in a string. For example, the German lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold` converts it to ``"ss"``. Note that most case-insensitive matches should also match compatibility equivalent characters. The casefolding algorithm is described in section 3.13 of the Unicode Standard. Per D146, a compatibility caseless match can be achieved by from unicodedata import normalize def caseless_compat(string): nfd_string = normalize("NFD", string) nfkd1_string = normalize("NFKD", nfd_string.casefold()) return normalize("NFKD", nfkd1_string.casefold()) ---------- assignee: docs@python components: Documentation messages: 151644 nosy: Jim.Jewett, benjamin.peterson, docs@python priority: normal severity: normal status: open title: Further improve casefold documentation versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13828> _______________________________________

7 10