[Python-ideas] Attribute Docstrings and Annotations

[Tony Lownds]

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

 >>> class X:
...     "class docstring"
...     foo: 1 = 1
...     bar: 2
...     "attribute docstring"
...     attr = None
...     "another attribute docstring"
...     fields = __slots__ = ['fields', 'attr']
...     "docstring ignored"
...     x, y = 1, 2
...
 >>> X.__attrdoc__
{'fields': 'another attribute docstring', 'attr': 'attribute docstring'}
 >>> X.__annotations__
{'foo': 1, 'bar': 2}
 >>> X.foo
1
 >>> X.bar
Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
AttributeError: type object 'X' has no attribute 'bar'
 >>> def f():
...     x: 1
...
   File "<stdin>", line 2
SyntaxError: annotation without assignment not allowed in function



   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