[issue14187] add "annotation" entry to Glossary
New submission from Chris Rebert <pybugs@rebertia.com>: The Glossary should include an entry for "annotation" and/or "function annotation" regarding the language feature introduced by PEP 3107. ---------- assignee: docs@python components: Documentation messages: 154852 nosy: cvrebert, docs@python priority: normal severity: normal status: open title: add "annotation" entry to Glossary versions: Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: I'm not sure this would be a worthwhile addition. This language feature is not widely referenced outside the docs for the feature itself. ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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? ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: Propose some brief text for an entry so we have something to evaluate for its utility. ---------- assignee: docs@python -> rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: 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-definition...]. Annotations may be accessed via the [__annotations__][http://docs.python.org/dev/reference/datamodel.html#the-standard-type-hierar... : 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: Any reactions to the strawman wording for the entry? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Looks good to me, with the proviso that it should be “function annotation”. ---------- versions: +Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: Here's an actual patch. ---------- keywords: +patch Added file: http://bugs.python.org/file25544/func_annotation.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Thanks, LGTM. ---------- title: add "annotation" entry to Glossary -> add "function annotation" entry to Glossary _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: The third paragraph should be dropped. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Sandro Tosi <sandro.tosi@gmail.com> added the comment: I agree with Raymond that last paragraph should be removed; +1 for the remaining part ---------- nosy: +sandro.tosi _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: 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. ? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Changes by Chris Rebert <pybugs@rebertia.com>: Added file: http://bugs.python.org/file25568/function_annotation_v2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: This looks fine. Éric, please apply the v2 patch when you get a chance. ---------- assignee: rhettinger -> eric.araujo priority: normal -> low _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Changes by Zachary Ware <zachary.ware@gmail.com>: ---------- nosy: +zach.ware _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Changes by Zachary Ware <zachary.ware@gmail.com>: ---------- versions: +Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Zachary Ware added the comment: 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. ---------- versions: -Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
R. David Murray added the comment: Done. Thanks for the ping. And thanks for the suggestion and patch, Chris. ---------- nosy: +r.david.murray resolution: -> fixed stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________
participants (8)
-
Chris Rebert -
Ezio Melotti
-
R. David Murray
-
Raymond Hettinger
-
Roundup Robot
-
Sandro Tosi
-
Zachary Ware
-
Éric Araujo