Mailman 3 September 2018 - docs

[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

[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

[issue13828] Further improve casefold documentation
by Jim Jewett 24 Aug '20

24 Aug '20

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

[issue23802] patch: __deepcopy__ memo dict argument usage
by Daniel Shahaf 18 Aug '20

18 Aug '20

New submission from Daniel Shahaf: In the 'copy' module documentation, it wasn't fully clear to me how __deepcopy__ implementations should treat the memo dict argument. The attached patch clarifies that __deepcopy__ implementations should treat the memo dict argument as an opaque type. ---------- assignee: docs@python components: Documentation files: opaque.diff keywords: patch messages: 239473 nosy: danielsh, docs@python priority: normal severity: normal status: open title: patch: __deepcopy__ memo dict argument usage type: enhancement Added file: http://bugs.python.org/file38723/opaque.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23802> _______________________________________

4 6

[issue30757] pyinstaller can be added to docs, py2exe ref can be updated
by Denis Akhiyarov 17 Aug '20

17 Aug '20

New submission from Denis Akhiyarov: https://github.com/python/cpython/pull/1158 It is not clear why this FAQ item is written in addition to this document: https://github.com/python/cpython/blob/master/Doc/faq/windows.rst#how-do-i-… https://github.com/python/cpython/blob/master/Doc/faq/programming.rst#how-c… ---------- assignee: docs@python components: Documentation messages: 296844 nosy: denfromufa, docs@python priority: normal severity: normal status: open title: pyinstaller can be added to docs, py2exe ref can be updated 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/issue30757> _______________________________________

4 4

[issue28681] About function renaming in the tutorial
by Xue Fuqiao 06 Jul '20

06 Jul '20

New submission from Xue Fuqiao: In https://hg.python.org/cpython/file/6fbb7c9d77c6/Doc/tutorial/controlflow.rs… : A function definition introduces the function name in the current symbol table. The value of the function name has a type that is recognized by the interpreter as a user-defined function. This value can be assigned to another name which can then also be used as a function. This serves as a general renaming mechanism Maybe "aliasing" is a better term than "renaming" here, since the original function name can still be used after the "renaming". ---------- assignee: docs@python components: Documentation files: renaming.patch keywords: patch messages: 280683 nosy: docs@python, xfq priority: normal severity: normal status: open title: About function renaming in the tutorial type: enhancement versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file45468/renaming.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28681> _______________________________________

9 16