Attribute Docstrings and Annotations
I'd like to propose annotations and docstrings on attributes for Python 3000 with the following Grammar and properties: expr_stmt: test (':' test ['=' (yield_expr|testlist)] | augassign (yield_expr|testlist) | [',' testlist] ('=' (yield_expr|testlist))* ) * annotations can appear for attributes that are not defined yet * code to generate and populate __annotations__ and __attrdoc__ would appear for all modules and class bodies, not for functions. * attribute annotations allow a name as target only * attribute annotations without assignment are illegal for functions * attribute annotations with assignment should probably be illegal for functions * docstring annotations only apply to the first target, and only if it is a name * docstring annotations do not apply to augmented assignments * docstring and annotations on functions do not get populated in __annotations__ * the class docstring is not reused as a function docstring The basic rationale for annotations on attributes is completeness with PEP3107. I'm proposing attribute docstrings as well because I think it's preferable to have a spot for documentation that isn't tied to annotations, like functions' __doc__. Also attribute docstrings as specified look similar to function docstrings; both have statements consisting of only a string that is taken as documentation. Here is an interactive session and the code that might be generated. What do you think? Thanks -Tony
2 0 LOAD_NAME 0 (__name__) 3 STORE_NAME 1 (__module__) 6 BUILD_MAP 0 9 STORE_NAME 2 (__annotations__) 12 BUILD_MAP 0 15 STORE_NAME 3 (__attrdoc__) 3 18 LOAD_CONST 0 ('class docstring') 21 STORE_NAME 4 (__doc__) 5 24 LOAD_CONST 1 ('attribute docstring') 27 LOAD_NAME 3 (__attrdoc__) 30 LOAD_CONST 2 ('attr') 33 STORE_SUBSCR 34 LOAD_NAME 5 (None) 37 STORE_NAME 6 (attr) 6 40 LOAD_CONST 3 (1) 48 STORE_NAME 7 (foo) 44 LOAD_CONST 3 (1) 51 LOAD_NAME 2 (__annotations__) 54 LOAD_CONST 4 ('foo') 57 STORE_SUBSCR 7 58 LOAD_CONST 5 (2) 61 LOAD_NAME 2 (__annotations__) 64 LOAD_CONST 6 ('bar') 67 STORE_SUBSCR 9 68 LOAD_CONST 7 ('another attribute docstring') 71 LOAD_NAME 3 (__attrdoc__) 74 LOAD_CONST 8 ('fields') 77 STORE_SUBSCR 78 LOAD_CONST 8 ('fields') 81 LOAD_CONST 2 ('attr') 84 BUILD_LIST 2 87 DUP_TOP 88 STORE_NAME 8 (fields) 91 STORE_NAME 9 (__slots__) 94 LOAD_LOCALS 95 RETURN_VALUE
Tony Lownds <tony@PageDNA.com> wrote:
[snip]
I have never needed attribute annotations, and I've never heard any core Python developer talk about it being useful to ahve them. -1 for the feature in any form. The syntax as described is ugly. -100 for the feature if it has the syntax provided. - Josiah
On Jan 1, 2007, at 10:21 PM, Josiah Carlson wrote:
It's the same syntax as function annotations... def f(name: annotation = value): ^^^^^^^^^^^^^^^^^^^^^^^^ class F: name: annotation = value ^^^^^^^^^^^^^^^^^^^^^^^^ The syntax was presented on Guido's blog, too. http://www.artima.com/weblogs/viewpost.jsp?thread=87182 -Tony
Tony Lownds <tony@pagedna.com> wrote:
I don't particularly like the look of function annotations either, but I don't have a better syntax (aside from swapping the annotation and value). In this case, I really don't like attribute annotations because it looks to me like a bunch of line noise without meaning, or some C-like conditional expression gone wrong.
I didn't like it when Guido posted it on his blog either. I would also point out that Guido lists attribute annotations as a "maybe". Perhaps he has become 100% on them, I don't know, but I'm still -1. In any case, you still haven't provided any use-cases, or an example where developers have been asking for the feature and could show that *not* having the feature was constraining them in some significant way. - Josiah
Yes, I blogged about it, but in the discussion that followed on python-3000 it became clear that the "typed attribute" notation is not a favorite of many folks, and I'm no longer in favor of it myself. The use cases are a lot weaker than for signature annotations. So let's drop it. On 1/2/07, Tony Lownds <tony@pagedna.com> wrote:
-- --Guido van Rossum (home page: http://www.python.org/~guido/)
On 1/2/07, Josiah Carlson <jcarlson@uci.edu> wrote:
I have never needed attribute annotations
For some classes, I document the intended use of certain attributes with a comment. Making this introspectable would be good. I've snipped the rest because I agree it wouldn't be worth the wordiness it would cause with any syntax I've seen so far. -jJ
Jim Jewett wrote:
I feel the correct way to do this is to just put the attribute comment in the doc string of the object that contains the attribute. Simple attributes are usually just that, simple values related to the object. Yes, it makes the doc string longer, but it also tends to makes for better documentation as well. Why make things more complex than they need to be? Ron
Tony Lownds <tony@PageDNA.com> wrote:
[snip]
I have never needed attribute annotations, and I've never heard any core Python developer talk about it being useful to ahve them. -1 for the feature in any form. The syntax as described is ugly. -100 for the feature if it has the syntax provided. - Josiah
On Jan 1, 2007, at 10:21 PM, Josiah Carlson wrote:
It's the same syntax as function annotations... def f(name: annotation = value): ^^^^^^^^^^^^^^^^^^^^^^^^ class F: name: annotation = value ^^^^^^^^^^^^^^^^^^^^^^^^ The syntax was presented on Guido's blog, too. http://www.artima.com/weblogs/viewpost.jsp?thread=87182 -Tony
Tony Lownds <tony@pagedna.com> wrote:
I don't particularly like the look of function annotations either, but I don't have a better syntax (aside from swapping the annotation and value). In this case, I really don't like attribute annotations because it looks to me like a bunch of line noise without meaning, or some C-like conditional expression gone wrong.
I didn't like it when Guido posted it on his blog either. I would also point out that Guido lists attribute annotations as a "maybe". Perhaps he has become 100% on them, I don't know, but I'm still -1. In any case, you still haven't provided any use-cases, or an example where developers have been asking for the feature and could show that *not* having the feature was constraining them in some significant way. - Josiah
Yes, I blogged about it, but in the discussion that followed on python-3000 it became clear that the "typed attribute" notation is not a favorite of many folks, and I'm no longer in favor of it myself. The use cases are a lot weaker than for signature annotations. So let's drop it. On 1/2/07, Tony Lownds <tony@pagedna.com> wrote:
-- --Guido van Rossum (home page: http://www.python.org/~guido/)
On 1/2/07, Josiah Carlson <jcarlson@uci.edu> wrote:
I have never needed attribute annotations
For some classes, I document the intended use of certain attributes with a comment. Making this introspectable would be good. I've snipped the rest because I agree it wouldn't be worth the wordiness it would cause with any syntax I've seen so far. -jJ
Jim Jewett wrote:
I feel the correct way to do this is to just put the attribute comment in the doc string of the object that contains the attribute. Simple attributes are usually just that, simple values related to the object. Yes, it makes the doc string longer, but it also tends to makes for better documentation as well. Why make things more complex than they need to be? Ron
participants (6)
-
Guido van Rossum -
Jim Jewett -
Josiah Carlson -
Ron Adam -
Tony Lownds -
Tony Lownds