[issue39231] Mistaken notion in tutorial

[Terry J. Reedy]

Change by Terry J. Reedy :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed
type: enhancement -> behavior
versions: +Python 3.10, Python 3.8, Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue39231] Mistaken notion in tutorial

[miss-islington]

miss-islington  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/7990072999b7e9b4ef6b1f6bb376d441a5a41d74


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue39231] Mistaken notion in tutorial

[miss-islington]

miss-islington  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/6fcebbb5a8cea25717804f5be9b6878104748ea5


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue39231] Mistaken notion in tutorial

[miss-islington]

Change by miss-islington :


--
pull_requests: +23791
pull_request: https://github.com/python/cpython/pull/25043

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue39231] Mistaken notion in tutorial

[Terry J. Reedy]

Terry J. Reedy  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/a53e9a7cf5912a44c5143e353912e44cfcfca7dc


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue39231] Mistaken notion in tutorial

[miss-islington]

Change by miss-islington :


--
nosy: +miss-islington
nosy_count: 5.0 -> 6.0
pull_requests: +23790
pull_request: https://github.com/python/cpython/pull/25042

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue39231] Mistaken notion in tutorial

[Irit Katriel]

Change by Irit Katriel :


--
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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue39231] Mistaken notion in tutorial

[Terry J. Reedy]

Terry J. Reedy  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue39231] Mistaken notion in tutorial

[Mark Dickinson]

Mark Dickinson  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue39231] Mistaken notion in tutorial

[Robert]

New submission from Robert :

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com