[Python-Dev] method decorators (PEP 318)

[Brad Clements]

On 26 Mar 2004 at 7:10, Guido van Rossum wrote:

> (2) Invent some other notation for setting function attributes as part
>     of the function *body*, before the doc string even.
> 
> For (2) I am thinking aloud here:
> 
>    def foobar(self, arg):
>        @author: "Guido van Rossum"
>        @deprecated
>        pass
> 


I met with Terry Way and some other folks last night to talk about PEP 316. I've also 
been speaking with David Goodger about developing a "recommended standard" for 
incorporating structured meta data in Python code.

DBC (Pep 316) is one use case,  method and function argument and return 
descriptors and type data is another use case, there's also Grouch for describing 
attribute types and class relationships. And DocTest could be consired to be 
"structured meta data"

Last night, Kevin Yacobson (??) said that he would prefer not to see "more docs 
stuffed in docstrings", but rather "in code", perhaps as class or method attributes as 
you describe above.

Personally, I'm not too concerned if meta data goes in docstrings, "free-floating" triple 
quoted strings scattered in code, or actual attributes of methods and functions. The 
thoughts I have about this are:

1. The meta data shouldn't be far away from the code it describes

2. .pyc files shouldn't be forced to contain this "extra" meta data either on disk or on 
subsequent use.

3. I think its desirable to be able to extract meta data from modules without importing 
them.

4. Structured meta data could be used to:

a. generate tests, either through explicit declaration (i.e. doctest) or implicitely (design 
by contract invariants and assertions combined with argument type knowledge)

b. describe method and function arguments and return values with both type and 
semantic information

c. describe attribute types and semantics

d. other meta data not yet considered.


5. IDE's could use meta data for code completion, hints and structure browsing

6. Other code analysis tools become possible, or existing ones could gain additional 
functionality

7. Meta data is not just for generating documentation

-

At PyCon I'm trying to collect use cases for "meta data in code". I haven't thought 
about how this meta data would be expressed in python code. Ideally, there would be 
a recommended "standard" for how meta data is expressed, and then a recommended 
standard for each meta data type. 


For example, it would be nice to not have to go through the hoops that Epydoc does in 
supporting 4 different documentation "standards".

Is PEP 318 going to specify how to handle arbitrary meta data, or should another PEP 
be proposed?


Am I the only one interested in this?

-- 
Brad Clements,                bkc at murkworks.com   (315)268-1000
http://www.murkworks.com                          (315)268-9812 Fax
http://www.wecanstopspam.org/                   AOL-IM: BKClements