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 _______________________________________