Question

好吧，我喜欢Python，但主要发现两件令人讨厌的事情：声明下面的self和docstrings。

我想知道的是，在我的代码声明之前，我应该如何获得文档字符串？类似的东西：

"""Class docstring"""
class MyClass(object):
    "Method documentation"
    def my_method(self):
        pass

也许使用某种形式的装饰？

Answer 1

可以编写一个设置__doc__属性的装饰器：

def doc(docstr):
    def deco(f):
        f.__doc__ = docstr
        return f
    return deco

这适用于函数和旧式类，但不适用于新式类，因为新样式类的__doc__属性是只读的（除非使用元类，否则会增加更多复杂性）很少获得）。

无论如何，我建议不要使用这样的装饰器。坚持通常的惯例。这样，开发人员将立即了解文档字符串是什么，解析文档字符串源代码的工具将正常工作等。

编辑：为了涵盖新式课程，您可以使用此实现：

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

由于__doc__是只读的，我们需要使用所需的文档创建一个新的类型对象。为简单起见，我不考虑自定义元类（如果您愿意，请在上面的代码中用type替换f.__class__）。

同样，我不建议使用这个装饰器。

Answer 2

正如您在问题中的建议，您可以采取以下措施：

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

但是，我发现这并不比目前的语法更好。

Answer 3

那不行。根据定义，docstring是声明后面一行的字符串。

如果你真的想用装饰器做这件事，你可以创建一个装饰器来设置包装函数（或类）的__doc__属性。

Answer 4

如果你真的想，当然。

def doc(text):
  def w(f):
    f.__doc__ = text
    return f
  return w

在Python代码中更改doc字符串的位置

4 个答案: