Well, I love Python, but find mainly two things annoying: self and docstrings below declarations.
What I would like to know is, how should I be able to have my docstrings before the declarations in my code? Something like:
"""Class docstring"""
class MyClass(object):
"Method documentation"
def my_method(self):
pass
Perhaps using some form of decorator?
It is possible to write a decorator that sets the __doc__ property:
def doc(docstr):
def deco(f):
f.__doc__ = docstr
return f
return deco
This will work for functions and old-style classes, but not for new-style classes, since the __doc__ attribute of new-style classes is read-only (unless you use metaclasses, adding even more complexity for very little gain).
I'd recommend against using such a decorator anyway. Just stick to the usual conventions. That way, fellow developers will immediately understand what's a docstring, tools parsing the source code for docstrings will work correctly etc.
Edit: To also cover new-style classes, you could use this implementation:
def doc(docstr):
def deco(f):
if isinstance(f, type):
d = vars(f).copy()
d["__doc__"] = docstr
return type(f.__name__, f.__bases__, d)
f.__doc__ = docstr
return f
return deco
Since __doc__ is read-only, we need to create a new type object with the desired documentation. For simplicity, I don't consider custom metaclasses (if you want to, replace type by f.__class__ in the above code).
Again, I don't recommend using this decorator.
__doc__ in python 2.7.2 for me.__doc__. I didn't realise this was the exception to the rule.
__doc__ writable, even if it's simply class Meta(type): pass. So in the end it wasn't the full truth when I stated that the decorator does not work for new-style classes.
__doc__ is writable again.As you already suggest in your question, you could do something as follows:
from functools import wraps
def docstring(docstr):
def decorator(cls):
@wraps(cls)
def wrapper(*args, **kwargs):
return cls(*args, **kwargs)
wrapper.__doc__ = docstr
return wrapper
return decorator
@docstring("""Class docstring""")
class MyClass(object):
def my_method(self):
pass
print MyClass.__doc__ # Class docstring
However, I don't find this particularly better than the current syntax.
MyClass into a function. The representation will be something like <function __main__.MyClass>, and you lose access to special attributes like __base__ etc.isinstance()? This won't work any more, neither will it be possible at all to derive from a class with such a decorator. In the end, this decorator might be completely unusable.That will not work. A docstring, is by definition, a string on the line following the declaration.
If you really want to do this with a decorator, you can create a decorator that sets the __doc__ property of the wrapped function (or class).
If you really want to, sure.
def doc(text):
def w(f):
f.__doc__ = text
return f
return w
__doc__ of new-style classes