classification
Title: Tutorial: Add function annotation example to function tutorial
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: asvetlov, docs@python, eric.araujo, ezio.melotti, python-dev, rhettinger, zach.ware
Priority: normal Keywords: patch

Created on 2012-05-23 19:42 by zach.ware, last changed 2012-11-01 19:48 by zach.ware. This issue is now closed.

Files
File name Uploaded Description Edit
annotations_tutorial.patch zach.ware, 2012-05-23 19:42 Patch against trunk review
annotations_tutorial.v2.patch zach.ware, 2012-05-25 17:24 Take 2 review
Messages (8)
msg161451 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2012-05-23 19:42
A couple months ago, I had never before heard of function annotations and came across a function that had them (I don't remember where or what it was).  I spent a fair bit of time searching fruitlessly to figure out what the heck that "->" in the function definition meant.  Then finally, a week or two ago, I came across a mention of pep 3107 and function annotations, and figured out what it was that confused me so thoroughly.

In an effort to save others from the same confusion, I've put together a small subsection to add to the tutorial about function definition.  The text I'm proposing to add is as follows:

"""
: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
"""

I'd also like to see a link for "->" in the index, either to this note or to the relevant paragraph of compound_stmts.rst or both.  The attached patch attempts to add such a link to this section, but I'm not certain that it's done properly.

Thanks :)
msg161469 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-05-23 23:08
This looks like a reasonable addition to the tutorial :-)
msg161550 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-05-25 05:40
Thanks for the patch.  I made some comments on the code review tool, which should have sent you a mail.
msg161593 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2012-05-25 17:24
Thanks for the review :).  Replied and here's the updated patch.
msg163889 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-06-25 04:49
LGTM, will commit.
msg174448 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-11-01 19:28
New changeset 2bf99322218f by Andrew Svetlov in branch '3.2':
Issue #14893: Add function annotation example to function tutorial.
http://hg.python.org/cpython/rev/2bf99322218f

New changeset 45167091b5f9 by Andrew Svetlov in branch '3.3':
Merge issue #14893: Add function annotation example to function tutorial.
http://hg.python.org/cpython/rev/45167091b5f9

New changeset 63b495ff366b by Andrew Svetlov in branch 'default':
Merge issue #14893: Add function annotation example to function tutorial.
http://hg.python.org/cpython/rev/63b495ff366b
msg174449 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-11-01 19:29
Fixed. Thanks, Zachary.
msg174456 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2012-11-01 19:48
Thank you Éric for the approval, and Andrew for the commit!
History
Date User Action Args
2012-11-01 19:48:47zach.waresetmessages: + msg174456
2012-11-01 19:29:34asvetlovsetstatus: open -> closed

nosy: + asvetlov
messages: + msg174449

resolution: fixed
stage: patch review -> resolved
2012-11-01 19:28:51python-devsetnosy: + python-dev
messages: + msg174448
2012-11-01 19:18:54zach.waresetversions: + Python 3.4
2012-06-25 04:49:00eric.araujosetassignee: docs@python -> eric.araujo
messages: + msg163889
2012-05-25 17:24:55zach.waresetfiles: + annotations_tutorial.v2.patch

messages: + msg161593
2012-05-25 05:40:06eric.araujosetmessages: + msg161550
2012-05-23 23:13:43ezio.melottisetnosy: + ezio.melotti, eric.araujo

stage: patch review
2012-05-23 23:08:27rhettingersetnosy: + rhettinger
messages: + msg161469
2012-05-23 19:42:34zach.warecreate