[Python-checkins] cpython (3.2): Issue #14893: Add function annotation example to function tutorial.

Thu Nov 1 20:28:51 CET 2012

http://hg.python.org/cpython/rev/2bf99322218f
changeset: 80165:2bf99322218f
branch: 3.2
parent: 80161:87ccf2635ad7
user: Andrew Svetlov <andrew.svetlov at gmail.com>
date: Thu Nov 01 21:26:55 2012 +0200
summary:
 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
