classification
Title: Mistaken notion in tutorial
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, iritkatriel, mark.dickinson, miss-islington, r0b, terry.reedy
Priority: normal Keywords: patch

Created on 2020-01-06 18:11 by r0b, last changed 2021-03-27 17:48 by terry.reedy. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 25029 merged iritkatriel, 2021-03-26 19:14
PR 25042 merged miss-islington, 2021-03-27 17:21
PR 25043 merged miss-islington, 2021-03-27 17:21
Messages (6)
msg359443 - (view) Author: Robert (r0b) Date: 2020-01-06 18:11
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".
msg359590 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2020-01-08 12:58
[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.
msg359772 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-01-11 00:52
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.)
msg389612 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-03-27 17:21
New changeset a53e9a7cf5912a44c5143e353912e44cfcfca7dc by Irit Katriel in branch 'master':
bpo-39231: correct tutorial annotations section (GH-25029)
https://github.com/python/cpython/commit/a53e9a7cf5912a44c5143e353912e44cfcfca7dc
msg389613 - (view) Author: miss-islington (miss-islington) Date: 2021-03-27 17:31
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/6fcebbb5a8cea25717804f5be9b6878104748ea5
msg389614 - (view) Author: miss-islington (miss-islington) Date: 2021-03-27 17:43
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/7990072999b7e9b4ef6b1f6bb376d441a5a41d74
History
Date User Action Args
2021-09-02 10:27:59iritkatriellinkissue32766 superseder
2021-03-27 17:48:56terry.reedysetstatus: open -> closed
type: enhancement -> behavior
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.8, Python 3.9, Python 3.10
2021-03-27 17:43:14miss-islingtonsetmessages: + msg389614
2021-03-27 17:31:03miss-islingtonsetmessages: + msg389613
2021-03-27 17:21:25miss-islingtonsetpull_requests: + pull_request23791
2021-03-27 17:21:14miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request23790
2021-03-27 17:21:12terry.reedysetmessages: + msg389612
2021-03-26 19:14:56iritkatrielsetkeywords: + patch
nosy: + iritkatriel

pull_requests: + pull_request23778
stage: patch review
2020-01-11 00:52:47terry.reedysetnosy: + terry.reedy
messages: + msg359772
2020-01-08 12:58:32mark.dickinsonsetnosy: + mark.dickinson
messages: + msg359590
2020-01-06 18:11:51r0bcreate