Title: add "function annotation" entry to Glossary
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: cvrebert, docs@python, eric.araujo, ezio.melotti, python-dev, r.david.murray, rhettinger, sandro.tosi, zach.ware
Priority: low Keywords: patch

Created on 2012-03-03 20:19 by cvrebert, last changed 2013-05-06 17:00 by r.david.murray. This issue is now closed.

File name Uploaded Description Edit
func_annotation.patch cvrebert, 2012-05-11 21:50 docs patch review
function_annotation_v2.patch cvrebert, 2012-05-13 23:45 axed 3rd paragraph review
Messages (20)
msg154852 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-03-03 20:19
The Glossary should include an entry for "annotation" and/or "function annotation" regarding the language feature introduced by PEP 3107.
msg155101 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-03-07 17:40
I'm not sure this would be a worthwhile addition.  This language feature is not widely referenced outside the docs for the feature itself.
msg155280 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-03-10 02:20
I think too that function annotations don’t need to be in the glossary; documenting them in the language reference section that talks about defining functions should be enough.  What do you think, Chris?
msg155413 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-03-11 21:58
Well, I thought the Glossary was a somewhat useful document in and of itself ("What's conceptual term 'X' mean? Hmm... I'll check the Glossary!") and so should include all terms which aren't module-specific.

But I won't push hard if no one else sees value in adding this entry.
msg155415 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-03-11 22:16
FWIW searching for "annotations" in the Sphinx quick search doesn't yield anything interesting, and the first result that actually contains a paragraph about annotations is the 11th (compound statements).
msg155416 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-03-11 22:30
Also, it would be a nice place to point out for those coming from Java or similar that the Java-esque concept of annotations has little to do with Python's function annotations, and that in Python their uses are typically served using decorators instead.
msg155417 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-03-11 23:13
Propose some brief text for an entry so we have something to evaluate for its utility.
msg155423 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-03-12 00:14
Strawman entry wording:

An annotation is an arbitrary metadata value associated with a function parameter or return value. The syntax for function annotations is explained in [Function definitions][]. Annotations may be accessed via the [__annotations__][ : Callable types -> User-defined functions -> Special attributes] special attribute of a function object.

Python itself does not assign any particular meaning to function annotations; they are intended to be interpreted by third-party libraries or tools. Annotations were added to Python by [PEP 3107 "Function Annotations"][], which describes some of their possible uses.

Some other languages (e.g. Java, C#) also have a concept of "annotations", but it is distinct from the Python concept; the purpose of these "annotations" is served in Python using [decorators]["decorator" entry in Glossary] instead.
msg160327 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-05-10 07:07
Any reactions to the strawman wording for the entry?
msg160352 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-05-10 15:37
Looks good to me, with the proviso that it should be “function annotation”.
msg160454 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-05-11 21:50
Here's an actual patch.
msg160458 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-05-11 22:33
Thanks, LGTM.
msg160460 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-05-11 22:47
The third paragraph should be dropped.
msg160471 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-05-12 15:04
I agree with Raymond that last paragraph should be removed; +1 for the remaining part
msg160582 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-05-13 23:42
Right, I can see how the 3rd paragraph has become tangential given the refined scope of the entry.

What do people think about a separate entry:

        Can refer to either a `function annotation` or some uses of `decorator`s.

msg160589 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-05-14 00:59
This looks fine.  Éric, please apply the v2 patch when you get a chance.
msg160625 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-05-14 13:47
Will do.  Chris, I don’t think another entry for “annotation” is needed, given Raymond’s previous rejection of the paragraph talking about other languages.
msg188563 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-05-06 16:48
Would anyone mind committing this?  It was approved by Raymond almost a year ago now, and is still accurate.

The patch still applies cleanly to 3.3 and default, though with some fuzz.
msg188564 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-05-06 16:59
New changeset e2a805281d26 by R David Murray in branch '3.3':
#14187: Add glossary entry for 'function annotations'.

New changeset 3e1c45f5c585 by R David Murray in branch 'default':
Merge #14187: Add glossary entry for 'function annotations'.
msg188565 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-05-06 17:00
Done.  Thanks for the ping.  And thanks for the suggestion and patch, Chris.
Date User Action Args
2013-05-06 17:00:11r.david.murraysetstatus: open -> closed

nosy: + r.david.murray
messages: + msg188565

resolution: fixed
stage: resolved
2013-05-06 16:59:26python-devsetnosy: + python-dev
messages: + msg188564
2013-05-06 16:48:53zach.waresetmessages: + msg188563
versions: - Python 3.2
2013-01-04 21:33:24zach.waresetversions: + Python 3.4
2012-06-19 16:38:16zach.waresetnosy: + zach.ware
2012-05-14 13:47:20eric.araujosetmessages: + msg160625
2012-05-14 00:59:08rhettingersetpriority: normal -> low
assignee: rhettinger -> eric.araujo
messages: + msg160589
2012-05-13 23:45:42cvrebertsetfiles: + function_annotation_v2.patch
2012-05-13 23:42:04cvrebertsetmessages: + msg160582
2012-05-12 15:04:04sandro.tosisetnosy: + sandro.tosi
messages: + msg160471
2012-05-11 22:47:24rhettingersetmessages: + msg160460
2012-05-11 22:33:07eric.araujosetmessages: + msg160458
title: add "annotation" entry to Glossary -> add "function annotation" entry to Glossary
2012-05-11 21:50:45cvrebertsetfiles: + func_annotation.patch
keywords: + patch
messages: + msg160454
2012-05-10 15:37:19eric.araujosetmessages: + msg160352
versions: + Python 3.2
2012-05-10 07:07:57cvrebertsetmessages: + msg160327
2012-03-12 00:14:31cvrebertsetmessages: + msg155423
2012-03-11 23:13:18rhettingersetassignee: docs@python -> rhettinger
messages: + msg155417
2012-03-11 22:30:40cvrebertsetmessages: + msg155416
2012-03-11 22:16:20ezio.melottisetmessages: + msg155415
2012-03-11 21:58:50cvrebertsetmessages: + msg155413
2012-03-10 02:20:17eric.araujosetnosy: + eric.araujo
messages: + msg155280
2012-03-07 17:41:32ezio.melottisetnosy: + ezio.melotti
type: enhancement
2012-03-07 17:40:31rhettingersetnosy: + rhettinger
messages: + msg155101
2012-03-03 20:19:16cvrebertcreate