Issue #23932: Update the tutorial section on function annotations.
Patch by Juti Noppornpitak.
diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
index ef50731..813c828 100644
--- a/Doc/tutorial/controlflow.rst
+++ b/Doc/tutorial/controlflow.rst
@@ -673,11 +673,9 @@
pair: function; annotations
single: -> (return annotation assignment)
-:ref:`Function annotations <function>` are completely optional,
-arbitrary metadata information about user-defined functions. Neither Python
-itself nor the standard library use function annotations in any way; this
-section just shows the syntax. Third-party projects are free to use function
-annotations for documentation, type checking, and other uses.
+:ref:`Function annotations <function>` are completely optional metadata
+information about the types used by user-defined functions (see :pep:`484`
+for more information).
Annotations are stored in the :attr:`__annotations__` attribute of the function
as a dictionary and have no effect on any other part of the function. Parameter
@@ -686,16 +684,17 @@
defined by a literal ``->``, followed by an expression, between the parameter
list and the colon denoting the end of the :keyword:`def` statement. The
following example has a positional argument, a keyword argument, and the return
-value annotated with nonsense::
+value annotated::
- >>> def f(ham: 42, eggs: int = 'spam') -> "Nothing to see here":
+ >>> def f(ham: str, eggs: str = 'eggs') -> str:
... print("Annotations:", f.__annotations__)
... print("Arguments:", ham, eggs)
+ ... return ham + ' and ' + eggs
...
- >>> f('wonderful')
- Annotations: {'eggs': <class 'int'>, 'return': 'Nothing to see here', 'ham': 42}
- Arguments: wonderful spam
-
+ >>> f('spam')
+ Annotations: {'ham': <class 'str'>, 'return': <class 'str'>, 'eggs': <class 'str'>}
+ Arguments: spam eggs
+ 'spam and eggs'
.. _tut-codingstyle: