[Python-Dev] Similarity of docstrings and decorators (original) (raw)

Andrew Durdin adurdin at gmail.com
Thu Aug 12 08:01:10 CEST 2004

It recently struck me that both decorators and docstrings are syntactic sugar for code that would otherwise follow the function definition, vide:

@staticmethod def foo(): """Frobs the baz""" pass

versus

def foo(): pass foo.doc = """Frobs the baz""" foo = staticmethod(foo)

This suggests two things to me: firstly, that the proposed decorator syntaxes which place the decorators after the def, beside the docstring, are the most consistent with existing syntax (that for docstrings); and secondly, that this suggests that it might be better to have an explicit function "header" section where both decorators and docstrings will reside. For a conceptual example (not a syntax proposal):

def foo(): header: staticmethod """Frobs the baz"""

pass

I realise there would be some issues with this--backward compatibility with existing docstrings (which could probably be resolved by a gradual deprecation), and Guido's concern about having to "peek inside the block"--but I thought it worth mentioning this generalised conception of both features, that highlights their similarity.

(As for peeking inside the function, if a separate header area existed for the "important external properties", then it, together with the signature (which is arguably the most important part of a function definition) would comprise all that you would need to know externally.)

More information about the Python-Dev mailing list