[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