| 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) *  |
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) * |
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) * |
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) * |
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][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. |
|
|
| 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) * |
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) * |
Date: 2012-05-11 22:33 |
| Thanks, LGTM. |
|
|
| msg160460 - (view) |
Author: Raymond Hettinger (rhettinger) * |
Date: 2012-05-11 22:47 |
| The third paragraph should be dropped. |
|
|
| msg160471 - (view) |
Author: Sandro Tosi (sandro.tosi) * |
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: "annotation" Can refer to either a `function annotation` or some uses of `decorator`s. ? |
|
|
| msg160589 - (view) |
Author: Raymond Hettinger (rhettinger) * |
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) * |
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) * |
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)  |
Date: 2013-05-06 16:59 |
| 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 |
|
|
| msg188565 - (view) |
Author: R. David Murray (r.david.murray) * |
Date: 2013-05-06 17:00 |
| Done. Thanks for the ping. And thanks for the suggestion and patch, Chris. |
|
|