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.
|
|
Date |
User |
Action |
Args |
2022-04-11 14:57:27 | admin | set | github: 58395 |
2013-05-06 17:00:11 | r.david.murray | set | status: open -> closed
nosy:
+ r.david.murray messages:
+ msg188565
resolution: fixed stage: resolved |
2013-05-06 16:59:26 | python-dev | set | nosy:
+ python-dev messages:
+ msg188564
|
2013-05-06 16:48:53 | zach.ware | set | messages:
+ msg188563 versions:
- Python 3.2 |
2013-01-04 21:33:24 | zach.ware | set | versions:
+ Python 3.4 |
2012-06-19 16:38:16 | zach.ware | set | nosy:
+ zach.ware
|
2012-05-14 13:47:20 | eric.araujo | set | messages:
+ msg160625 |
2012-05-14 00:59:08 | rhettinger | set | priority: normal -> low assignee: rhettinger -> eric.araujo messages:
+ msg160589
|
2012-05-13 23:45:42 | cvrebert | set | files:
+ function_annotation_v2.patch |
2012-05-13 23:42:04 | cvrebert | set | messages:
+ msg160582 |
2012-05-12 15:04:04 | sandro.tosi | set | nosy:
+ sandro.tosi messages:
+ msg160471
|
2012-05-11 22:47:24 | rhettinger | set | messages:
+ msg160460 |
2012-05-11 22:33:07 | eric.araujo | set | messages:
+ msg160458 title: add "annotation" entry to Glossary -> add "function annotation" entry to Glossary |
2012-05-11 21:50:45 | cvrebert | set | files:
+ func_annotation.patch keywords:
+ patch messages:
+ msg160454
|
2012-05-10 15:37:19 | eric.araujo | set | messages:
+ msg160352 versions:
+ Python 3.2 |
2012-05-10 07:07:57 | cvrebert | set | messages:
+ msg160327 |
2012-03-12 00:14:31 | cvrebert | set | messages:
+ msg155423 |
2012-03-11 23:13:18 | rhettinger | set | assignee: docs@python -> rhettinger messages:
+ msg155417 |
2012-03-11 22:30:40 | cvrebert | set | messages:
+ msg155416 |
2012-03-11 22:16:20 | ezio.melotti | set | messages:
+ msg155415 |
2012-03-11 21:58:50 | cvrebert | set | messages:
+ msg155413 |
2012-03-10 02:20:17 | eric.araujo | set | nosy:
+ eric.araujo messages:
+ msg155280
|
2012-03-07 17:41:32 | ezio.melotti | set | nosy:
+ ezio.melotti type: enhancement
|
2012-03-07 17:40:31 | rhettinger | set | nosy:
+ rhettinger messages:
+ msg155101
|
2012-03-03 20:19:16 | cvrebert | create | |