Mailman 3 October 2021 - Docs-bugs

[issue45647] "expression" is erroneous in the doc
by Arthur Milchior 03 Nov '21

03 Nov '21

New submission from Arthur Milchior <arthur(a)milchior.fr>: https://docs.python.org/3/reference/expressions.html#grammar-token-python-g… is wrong This line state: `expression ::= conditional_expression | lambda_expr` and it is a problem because, by the way sphinx understand reference, this mean that any people who use the token `expression` will be linked to this particular line. For example in https://docs.python.org/3/reference/expressions.html#grammar-token-python-g… `key_datum ::= expression ":" expression | "**" or_expr` while clearly a key_datum is not expecting only a conditional expression or a lambda expression. Admittedly, you can derive, from expression: * conditional_expression * or_test * and_test * not_test * comparison * or_expr * xor_expr * and_expr * shift_expr * a_expr * m_expr * u_expr * power * primary * atom in this order, so in practice you can probably derive most of the expressions. However, I doubt that this is what the documentation meant here, and clearly not practical. ---------- assignee: docs@python components: Documentation messages: 405189 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: "expression" is erroneous in the doc versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45647> _______________________________________

2 1

[issue45602] The grammar misses links that are present everywhere else
by Arthur Milchior 02 Nov '21

02 Nov '21

New submission from Arthur Milchior <arthur(a)milchior.fr>: The grammar, in https://docs.python.org/3/reference/grammar.html , lacks some utilities that the remaining of the documentation have. While it remains usable, it is hard to navigate. As an example https://www.python.org/dev/peps/pep-0634/ 's "star_named_exrpsession" and "block" links to the general grammar page, and indeed can't link to the specific rules as there are no anchor on them. This would also allow a related improvement: being able to click on a rule R in the right side of a declaration and go to the definition of R. Given the recursive nature of grammar, that would transform a sequence of search into a sequence of click (and even allow to use the browser's "back" to go back to the previous definition, or to open the new definition in a new tab) As far as I can tell, the first action would be to add a new kind of token on Doc/tools/extensions/peg_highlight.py , so that we distinguish the left and the right part of the rule. The left part (the name of the declared rule) would be easy to recognize as it always start on the beginning of the line and end with :. The second action would be that, for each declaration D, the html would contain an anchor "#D". And each time D would appear on the right hand side of a rule, it would be in a link to #D I suspect that adding those links and anchor could be done by overriding the default formatter or highlighter, but I don't understand pygment well enough to know what should be done here ---------- assignee: docs@python components: Documentation messages: 404946 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: The grammar misses links that are present everywhere else type: enhancement versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45602> _______________________________________

2 1

[issue45516] Add protocol description to the Traversable and TraversableResources documentation
by Jason R. Coombs 01 Nov '21

01 Nov '21

New submission from Jason R. Coombs <jaraco(a)jaraco.com>: New changeset 4d03de3329ed8daa9c1107b1aedbb0fa280bddb6 by Filipe Laíns in branch 'main': bpo-45516: add protocol description to the Traversable documentation (#29039) https://github.com/python/cpython/commit/4d03de3329ed8daa9c1107b1aedbb0fa28… ---------- nosy: +jaraco _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45516> _______________________________________

3 13

[issue44365] Bad dataclass post-init example
by Micael Jarniac 01 Nov '21

01 Nov '21

New submission from Micael Jarniac <micael(a)jarniac.com>: https://docs.python.org/3/library/dataclasses.html#post-init-processing https://github.com/python/cpython/blob/3.9/Doc/library/dataclasses.rst#post… In the example, a base class "Rectangle" is defined, and then a "Square" class inherits from it. On reading the example, it seems like the Square class is meant to be used like: >>> square = Square(5) Since the Square class seems to be supposed to be a "shortcut" to creating a Rectangle with equal sides. However, the Rectangle class has two required init arguments, and when Square inherits from it, those arguments are still required, so using Square like in the above example, with a single argument, results in an error: >>> square = Square(5) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: __init__() missing 2 required positional arguments: 'width' and 'side' To "properly" use the Square class, it'd need to be instantiated like so: >>> square = Square(0, 0, 5) >>> square Square(height=5, width=5, side=5) Which, in my opinion, is completely counter-intuitive, and basically invalidates this example. ---------- assignee: docs@python components: Documentation messages: 395427 nosy: MicaelJarniac, docs@python priority: normal severity: normal status: open title: Bad dataclass post-init example type: behavior versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44365> _______________________________________

5 12

[issue45600] First sentence in docs for os.environ
by Andrei Kulakov 30 Oct '21

30 Oct '21

New submission from Andrei Kulakov <andrei.avk(a)gmail.com>: In os.eviron docs: https://docs.python.org/3.11/library/os.html#os.environ A mapping object representing the string environment. Should that be "... the process environment." ? ---------- assignee: docs@python components: Documentation messages: 404934 nosy: andrei.avk, docs@python priority: low severity: normal status: open title: First sentence in docs for os.environ type: enhancement versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45600> _______________________________________

4 10

[issue45655] List of PEPs at top of typing docs is too long to be readable
by Alex Waygood 29 Oct '21

29 Oct '21

New submission from Alex Waygood <Alex.Waygood(a)Gmail.com>: The list of relevant PEPs at the top of the typing docs has become too long to be readable or helpful. It would be good if this information could be presented in a more structured way. ---------- assignee: docs@python components: Documentation messages: 405215 nosy: AlexWaygood, docs@python, gvanrossum, kj priority: normal severity: normal status: open title: List of PEPs at top of typing docs is too long to be readable type: enhancement versions: Python 3.10, Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45655> _______________________________________

4 15

[issue42280] The list of standard generic collections is incomplete
by Alex Waygood 29 Oct '21

29 Oct '21

Change by Alex Waygood <Alex.Waygood(a)Gmail.com>: ---------- nosy: +AlexWaygood nosy_count: 5.0 -> 6.0 pull_requests: +27583 pull_request: https://github.com/python/cpython/pull/29308 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42280> _______________________________________

1 0

[issue45604] multiprocessing.log_to_stderr missing documentation for parameter
by Alex Wells 29 Oct '21

29 Oct '21

New submission from Alex Wells <alex.wells(a)diamond.ac.uk>: The documentation for multiprocessing.log_to_stderr() specifies that the method takes no parameters. However, intellisense in VSCode and debugging the method both show that there is a single parameter, "level", whose default value is None. Documentation here: https://docs.python.org/3.7/library/multiprocessing.html#multiprocessing.lo… The parameter appears to be a shorthand to allow you to both get the logger and specify the required log level in one step, rather than two. The code that handles the "level" parameter appears to do what I'd expect it to do. I think the documentation simply needs a few words written about the parameter. Thanks. ---------- assignee: docs@python components: Documentation messages: 404965 nosy: AlexWells, docs@python priority: normal severity: normal status: open title: multiprocessing.log_to_stderr missing documentation for parameter type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45604> _______________________________________

4 9

[issue45612] [doc] add sqlite3 module docstring
by Erlend E. Aasland 29 Oct '21

29 Oct '21

New submission from Erlend E. Aasland <erlend.aasland(a)innova.no>: Currently, the sqlite3 module docstring is the old pysqlite copyright comment in the start of Lib/sqlite3/__init__.py. This is not very helpful to the general user. Suggesting to add a more helpful docstring, a la the 're' or 'array' modules (those two were randomly picked among stdlib modules with helpful docstrings). ---------- assignee: docs@python components: Documentation messages: 405030 nosy: docs@python, erlendaasland priority: normal severity: normal status: open title: [doc] add sqlite3 module docstring versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45612> _______________________________________

3 7

[issue45583] Documentation of int() in datamodel.rst is out of date
by Arthur Milchior 29 Oct '21

29 Oct '21

New submission from Arthur Milchior <arthur(a)milchior.fr>: In 3.8, int() default implementation changed, using __index__() if it is available instead of __trunc__(). The file function.rst was updated accordingly, but the redundant information in datamodel.rst contained out of date information I offer a correction in https://github.com/python/cpython/pull/29182 (but ideally it should be added back to 3.8 python documentation) ---------- assignee: docs@python components: Documentation messages: 404848 nosy: ArthurMilchior, docs@python priority: normal severity: normal status: open title: Documentation of int() in datamodel.rst is out of date versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45583> _______________________________________

4 9