[docs] Tutorial: Add function annotation example to function tutorial (issue 14893)

[zachary.ware at gmail.com]

Reviewers: eric.araujo,


http://bugs.python.org/review/14893/diff/4990/Doc/tutorial/controlflow.rst
File Doc/tutorial/controlflow.rst (right):

http://bugs.python.org/review/14893/diff/4990/Doc/tutorial/controlflow.rst#newcode649
Doc/tutorial/controlflow.rst:649: :ref:`Function annotations <function>`
are completely optional,
On 2012/05/25 07:39:39, eric.araujo wrote:
> The ref target looks wrong.  Maybe you want a link to the glossary
entry that
> will be added soon?  :term:`function annotations`

I had the same thought initially, but then I figured that this first
paragraph says roughly the same thing, and about all that the glossary
entry mentions that this doesn't is the PEP that spawned it.  The
glossary entry also links to :ref:`function`, so I figured I'd just cut
out the middle-man.  The relevant part really doesn't go into much more
detail, though, so maybe the grammar production list is the right thing
to point to anyway?  I'm happy to change it if we decide that way,
though.

As a side-note, should an example be added to the :ref:`function`
section?

http://bugs.python.org/review/14893/diff/4990/Doc/tutorial/controlflow.rst#newcode652
Doc/tutorial/controlflow.rst:652: familiarity with the syntax.
On 2012/05/25 07:39:39, eric.araujo wrote:
> Wording improvement suggestion: “Python itself or the standard library
don't use
> function annotations in any way; this section just shows the syntax. 
> Third-party projects are free to leverage function annotations for
> documentation, type checking and other uses.”

Done, though I moved the negative and added a comma.

http://bugs.python.org/review/14893/diff/4990/Doc/tutorial/controlflow.rst#newcode664
Doc/tutorial/controlflow.rst:664: ...     print("Annotations:",
f.__annotations__) # print the function's own annotations
On 2012/05/25 07:39:39, eric.araujo wrote:
> The comment seems to merely duplicate the code, which is clear enough
in my
> opinion.

Good point.  I think this was a holdover from a previous iteration of
the patch before I submitted it.  Removed.



Please review this at http://bugs.python.org/review/14893/

Affected files:
  Doc/tutorial/controlflow.rst


diff -r ab94ed2a8012 Doc/tutorial/controlflow.rst
--- a/Doc/tutorial/controlflow.rst	Wed May 23 11:22:44 2012 +0200
+++ b/Doc/tutorial/controlflow.rst	Wed May 23 14:09:51 2012 -0500
@@ -636,6 +636,39 @@
        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.  Python itself
+currently does not use annotations for anything, so this section is just for
+familiarity with the syntax.
+
+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 the function's own 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