[Python-checkins] cpython (merge 3.2 -> 3.3): Merge issue #14893: Add function annotation example to function tutorial.

[andrew.svetlov]

http://hg.python.org/cpython/rev/45167091b5f9
changeset:   80166:45167091b5f9
branch:      3.3
parent:      80162:717660ec8f67
parent:      80165:2bf99322218f
user:        Andrew Svetlov <andrew.svetlov at gmail.com>
date:        Thu Nov 01 21:27:23 2012 +0200
summary:
  Merge issue #14893: Add function annotation example to function tutorial.

Patch by Zachary Ware.

files:
  Doc/tutorial/controlflow.rst |  34 ++++++++++++++++++++++++
  1 files changed, 34 insertions(+), 0 deletions(-)


diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
--- a/Doc/tutorial/controlflow.rst
+++ b/Doc/tutorial/controlflow.rst
@@ -656,6 +656,40 @@
        No, really, it doesn't do anything.
 
 
+.. _tut-annotations:
+
+Function Annotations
+--------------------
+
+.. sectionauthor:: Zachary Ware <zachary.ware at gmail.com>
+.. index::
+   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.
+
+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
+annotations are defined by a colon after the parameter name, followed by an
+expression evaluating to the value of the annotation.  Return annotations are
+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::
+
+   >>> def f(ham: 42, eggs: int = 'spam') -> "Nothing to see here":
+   ...     print("Annotations:", f.__annotations__)
+   ...     print("Arguments:", ham, eggs)
+   ...
+   >>> f('wonderful')
+   Annotations: {'eggs': <class 'int'>, 'return': 'Nothing to see here', 'ham': 42}
+   Arguments: wonderful spam
+
+
 .. _tut-codingstyle:
 
 Intermezzo: Coding Style

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