[issue39231] Mistaken notion in tutorial
New submission from Robert <freshbob1337@gmail.com>: https://docs.python.org/3/tutorial/controlflow.html 4.7.8. Function Annotations [...] "The following example has a positional argument, a keyword argument, and the return value annotated:" It is not a "positional argument" but an "optional argument". ---------- assignee: docs@python components: Documentation messages: 359443 nosy: docs@python, r0b priority: normal severity: normal status: open title: Mistaken notion in tutorial type: enhancement _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39231> _______________________________________
Mark Dickinson <dickinsm@gmail.com> added the comment: [Robert]
It is not a "positional argument" but an "optional argument".
I don't think I understand. Here the phrase "positional argument" in the docs is, I assume, referring to the parameter "ham: str" in the parameter list. So it's not optional; it's a required, positional-or-keyword parameter. I don't know whether the text of this section should be being tightened up with respect to the distinction between (formal) parameters and actual arguments, though. There's a tradeoff between readability and accessibility on the one hand, and technical accuracy on the other. ---------- nosy: +mark.dickinson _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39231> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: https://docs.python.org/3/tutorial/controlflow.html#function-annotations is the direct link. As Mark said, 'ham' is a required positional-or-keyword argument. 'eggs' is an optional 'positional-or-keyword. The sentence as is is wrong, even if Robert garbled the reason. With the signature as it, the sentence should be "The following example has a required argument, an optional argument, and the return value annotated." To make the existing sentence true, the signature could be changed to def f(ham: str, /, *, eggs: str) -> str: But I think this would be wrong. Annotation does not depend on how an argument is passed, but whether it has a default (making it optional). In particular, it shows that when optional, the annotation goes *before* '= default', not after. (It could have gone after: eggs = 'eggs': str.) ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39231> _______________________________________
Change by Irit Katriel <iritkatriel@yahoo.com>: ---------- keywords: +patch nosy: +iritkatriel nosy_count: 4.0 -> 5.0 pull_requests: +23778 stage: -> patch review pull_request: https://github.com/python/cpython/pull/25029 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39231> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: New changeset a53e9a7cf5912a44c5143e353912e44cfcfca7dc by Irit Katriel in branch 'master': bpo-39231: correct tutorial annotations section (GH-25029) https://github.com/python/cpython/commit/a53e9a7cf5912a44c5143e353912e44cfcf... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39231> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- nosy: +miss-islington nosy_count: 5.0 -> 6.0 pull_requests: +23790 pull_request: https://github.com/python/cpython/pull/25042 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39231> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +23791 pull_request: https://github.com/python/cpython/pull/25043 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39231> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: New changeset 6fcebbb5a8cea25717804f5be9b6878104748ea5 by Miss Islington (bot) in branch '3.8': bpo-39231: correct tutorial annotations section (GH-25029) https://github.com/python/cpython/commit/6fcebbb5a8cea25717804f5be9b68781047... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39231> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: New changeset 7990072999b7e9b4ef6b1f6bb376d441a5a41d74 by Miss Islington (bot) in branch '3.9': bpo-39231: correct tutorial annotations section (GH-25029) https://github.com/python/cpython/commit/7990072999b7e9b4ef6b1f6bb376d441a5a... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39231> _______________________________________
Change by Terry J. Reedy <tjreedy@udel.edu>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed type: enhancement -> behavior versions: +Python 3.10, Python 3.8, Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39231> _______________________________________
participants (5)
-
Irit Katriel -
Mark Dickinson
-
miss-islington
-
Robert
-
Terry J. Reedy