homepage

The Glossary should include an entry for "annotation" and/or "function annotation" regarding the language feature introduced by PEP 3107.

I'm not sure this would be a worthwhile addition. This language feature is not widely referenced outside the docs for the feature itself.

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?

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.

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).

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.

Propose some brief text for an entry so we have something to evaluate for its utility.

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][http://docs.python.org/dev/reference/compound_stmts.html#function-definitions]. Annotations may be accessed via the [__annotations__][http://docs.python.org/dev/reference/datamodel.html#the-standard-type-hierarchy : 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"][http://www.python.org/dev/peps/pep-3107/], 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.

Any reactions to the strawman wording for the entry?

Looks good to me, with the proviso that it should be "function annotation".

Here's an actual patch.

Thanks, LGTM.

The third paragraph should be dropped.

I agree with Raymond that last paragraph should be removed; +1 for the remaining part

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:
 "annotation"
 Can refer to either a `function annotation` or some uses of `decorator`s.
?

This looks fine. Éric, please apply the v2 patch when you get a chance.

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.

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.

New changeset e2a805281d26 by R David Murray in branch '3.3':
#14187: Add glossary entry for 'function annotations'.
http://hg.python.org/cpython/rev/e2a805281d26
New changeset 3e1c45f5c585 by R David Murray in branch 'default':
Merge #14187: Add glossary entry for 'function annotations'.
http://hg.python.org/cpython/rev/3e1c45f5c585 

Done. Thanks for the ping. And thanks for the suggestion and patch, Chris.