Mailman 3 April 2021 - docs

[issue41411] Improve and consolidate f-strings docs
by Ezio Melotti May 2, 2021

May 2, 2021

New submission from Ezio Melotti <ezio.melotti(a)gmail.com>: [Creating a new issue from #41045] I was just just trying to link to someone the documentation for f-strings, but: 1) Searching "fstring" only returns two results about xdrlib[0]; 2) Searching "f-string" returns many unrelated results[1]; 3) The first (and closer) result (string -- Common string operations[2]) yields nothing while using ctrl+f with fstring, f-string, f', f"; 4) at the top of that page there are two links in a "see also": * Text Sequence Type — str[3]: it mentions raw strings at the beginning, but also yields no results for fstring, f-string, f', f"; * String Methods[4]: that is another section of the previous page (so ctrl+f doesn't find anything), but has a link to "Format String Syntax"[5]; 5) The "Format String Syntax" page[5] has another link in the middle of a paragraph that points to "formatted string literals", that eventually brings us to the right page[6]; 6) the "right page"[6] has a wall of text with a block of code containing the grammar, luckily followed by a few examples. I think we should: 1) add index entries for "f-string" and "fstring" in the relevant sections of the docs, so that they appear in the search result; 2) in the Text Sequence Type — str[3] section, have a bullet list for f-strings, raw-strings, and possibly u-strings; 3) possibly use the term "f-string" in addition (or instead) of "formatted string literal", to make the pages more ctrl+f-friendly throughout the docs; 4) possibly have another more newbie-friendly section on f-string (compared to the lexical analysis page) in the tutorial, in the stdtypes page[7] (e.g. before the printf-style String Formatting" section[8]), or in the string page[2] (e.g. after the "Format String Syntax" section[10]); 5) possibly reorganize and consolidate the different sections about strings, string methods, str.format(), the format mini-language, f-strings, raw/unicode-strings, %-style formatting in a single page or two (a page for the docs and one for the grammar), since it seems to me that over the years these sections got a bit scattered around as they were being added. [0]: https://docs.python.org/3/search.html?q=fstring [1]: https://docs.python.org/3/search.html?q=f-string [2]: https://docs.python.org/3/library/string.html [3]: https://docs.python.org/3/library/stdtypes.html#textseq [4]: https://docs.python.org/3/library/stdtypes.html#string-methods [5]: https://docs.python.org/3/library/string.html#formatstrings [6]: https://docs.python.org/3/reference/lexical_analysis.html#f-strings [7]: https://docs.python.org/3/library/stdtypes.html [8]: https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatt… ---------- assignee: docs@python components: Documentation messages: 374398 nosy: docs@python, eric.smith, ezio.melotti priority: normal severity: normal stage: needs patch status: open title: Improve and consolidate f-strings docs type: enhancement versions: Python 3.10, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41411> _______________________________________

6 13

[issue43815] documentation for types.new_class() mention misleading default for exec_body
by Eric V. Smith May 1, 2021

May 1, 2021

New submission from Eric V. Smith <eric(a)trueblade.com>: https://github.com/python/cpython/blob/3.8/Lib/types.py The documentation says "If no callback is provided, it has the same effect as passing in lambda ns: ns." I read this as saying that the callback should return the namespace, but in reality the return value is ignored. I think the lambda should be "lambda ns: None". ---------- assignee: docs@python components: Documentation keywords: easy, newcomer friendly messages: 390854 nosy: docs@python, eric.smith priority: normal severity: normal status: open title: documentation for types.new_class() mention misleading default for exec_body versions: Python 3.10, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43815> _______________________________________

3 4

Example of uniform on random page appears to have the wrong comment
by Theodore Greene May 1, 2021

May 1, 2021

Hi! I'm a little confused. In the examples section of the docs for the random module it shows uniform(2.5, 10.0) # Random float: 2.5 <= x < 10.0 But the docs say random.uniform(a, b) Return a random floating point number N such that a <= N <= b for a <= b and b <= N <= a for b < a. So, shouldn't the example really say # Random float: 2.5 <= x <= 10.0 or am I not understanding random.uniform? Best wishes, Ted

2 1

[issue43971] documentation: no spacing around default args in annotated function
by Mohamed Moselhy May 1, 2021

May 1, 2021

New submission from Mohamed Moselhy <look4d(a)gmail.com>: See https://www.python.org/dev/peps/pep-0008/#function-annotations The first section of https://docs.python.org/3/library/dataclasses.html shows quantity_on_hand: int=0, when there should be spacing around the '=' according to PEP 8 (see link above). ---------- assignee: docs@python components: Documentation files: screen.png messages: 392271 nosy: docs@python, eric.araujo, ezio.melotti, mdk, moselhy, willingc priority: normal severity: normal status: open title: documentation: no spacing around default args in annotated function versions: Python 3.10, Python 3.11, Python 3.7, Python 3.8, Python 3.9 Added file: https://bugs.python.org/file49998/screen.png _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43971> _______________________________________

4 8

[issue43869] Fix documentation of epoch/time.time
by Ofek Lev May 1, 2021

May 1, 2021

New submission from Ofek Lev <ofekmeister(a)gmail.com>: The descriptions for the following: - https://docs.python.org/3/library/time.html#epoch - https://docs.python.org/3/library/time.html#time.time indicate that it is platform dependent. However, that is likely untrue. See the brief discussion here: https://github.com/DataDog/integrations-core/pull/6692#discussion_r427469097 ---------- assignee: docs@python components: Documentation messages: 391214 nosy: Ofekmeister, docs@python, p-ganssle priority: normal severity: normal status: open title: Fix documentation of epoch/time.time type: enhancement versions: Python 3.10, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43869> _______________________________________

3 5

[issue22167] iglob() has misleading documentation (does indeed store names internally)
by Roy Smith May 1, 2021

May 1, 2021

New submission from Roy Smith: For background, see: https://mail.python.org/pipermail/python-list/2014-August/676291.html In a nutshell, the iglob() docs say, "Return an iterator which yields the same values as glob() without actually storing them all simultaneously." The problem is, internally, it calls os.listdir(), which apparently *does* store the entire list internally, defeating the whole purpose of iglob() I recognize that iglob() is not going to get fixed in 2.7, but at least the documentation should be updated to point out that it doesn't really do what it says it does. Or rather, it doesn't really not do what it says it doesn't :-) ---------- assignee: docs@python components: Documentation messages: 225048 nosy: docs@python, roysmith priority: normal severity: normal status: open title: iglob() has misleading documentation (does indeed store names internally) type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22167> _______________________________________

8 19

[issue43928] Fix the typo in documentation
by Terry J. Reedy April 30, 2021

April 30, 2021

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: New changeset e08c67372d62236409da296353827985a3202e8a by JT in branch 'master': bpo-43928: Fix 'succesfully' typo in document (GH-25569) https://github.com/python/cpython/commit/e08c67372d62236409da296353827985a3… ---------- nosy: +terry.reedy _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43928> _______________________________________

1 1

[issue43935] Fix typo in Turtle.back docstring
by Stéphane Wirtel April 30, 2021

April 30, 2021

New submission from Stéphane Wirtel <stephane(a)wirtel.be>: Thank you for your contribution but as you know, you have to sign the CLA. https://github.com/python/cpython/pull/25581#issuecomment-826150064 ---------- nosy: +matrixise _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43935> _______________________________________

3 6

[issue42589] doc: Wrong "from" keyword link in Exceptions doc
by Irit Katriel April 30, 2021

April 30, 2021

New submission from Irit Katriel <iritkatriel(a)yahoo.com>: In the Exceptions doc: https://docs.python.org/3/library/exceptions.html#built-in-exceptions In the sentence "The expression following from must be an exception or None." "from" is a keyword which links to https://docs.python.org/3/reference/simple_stmts.html#from But that is related to the from in "from X import Y" rather than "raise X from Y". ---------- assignee: docs@python components: Documentation messages: 382649 nosy: docs@python, iritkatriel priority: normal severity: normal status: open title: doc: Wrong "from" keyword link in Exceptions doc type: behavior versions: Python 3.10, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42589> _______________________________________

4 8

[issue36384] [security] CVE-2021-29921: ipaddress Should not reject IPv4 addresses with leading zeroes as ambiguously octal
by STINNER Victor April 30, 2021

April 30, 2021

STINNER Victor <vstinner(a)python.org> added the comment: The CVE-2021-29921 was assigned to this vulnerability. ---------- title: ipaddress Should not reject IPv4 addresses with leading zeroes as ambiguously octal -> [security] CVE-2021-29921: ipaddress Should not reject IPv4 addresses with leading zeroes as ambiguously octal _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36384> _______________________________________

1 0