[Python-checkins] cpython (3.4): Issue #23932: Update the tutorial section on function annotations.

[zach.ware]

https://hg.python.org/cpython/rev/0acb8dcb8e0c
changeset:   95576:0acb8dcb8e0c
branch:      3.4
parent:      95574:19f6f339af7e
user:        Zachary Ware <zachary.ware at gmail.com>
date:        Mon Apr 13 11:30:47 2015 -0500
summary:
  Issue #23932: Update the tutorial section on function annotations.

Patch by Juti Noppornpitak.

files:
  Doc/tutorial/controlflow.rst |  21 ++++++++++-----------
  1 files changed, 10 insertions(+), 11 deletions(-)


diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
--- 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:
 

-- 
Repository URL: https://hg.python.org/cpython