如何编程设置文档字符串？

Question

我有一个返回的功能的包装函数。有没有以编程方式设置返回函数的文档字符串的方法吗？如果我能写__doc__我会做到以下几点：

def wrapper(a):
    def add_something(b):
       return a + b
    add_something.__doc__ = 'Adds ' + str(a) + ' to `b`'
    return add_something

然后，我可以做

>>> add_three = wrapper(3)
>>> add_three.__doc__
'Adds 3 to `b`

然而，由于__doc__是只读的，我无法做到这一点。什么是正确的方法是什么？

---

编辑：好吧，我想保持这种简单的，但当然这不是我真正想要做的事。即使在一般__doc__是在我的情况下写的不是。

我想自动创建测试用例unittest。我有一个创建一个类对象是unittest.TestCase的子类中的包装函数：

import unittest
def makeTestCase(filename, my_func):
    class ATest(unittest.TestCase):
        def testSomething(self):
            # Running test in here with data in filename and function my_func
            data  = loadmat(filename)
            result = my_func(data)
            self.assertTrue(result > 0)

    return ATest

如果我创建这个类，并尝试设置testSomething的文档字符串我得到一个错误：

>>> def my_func(): pass
>>> MyTest = makeTestCase('some_filename', my_func)
>>> MyTest.testSomething.__doc__ = 'This should be my docstring'
AttributeError: attribute '__doc__' of 'instancemethod' objects is not writable

Answer 1

我将通过文档字符串进厂功能和使用type手动构造的类。

def make_testcase(filename, myfunc, docstring):
    def test_something(self):
        data = loadmat(filename)
        result = myfunc(data)
        self.assertTrue(result > 0)

    clsdict = {'test_something': test_something,
               '__doc__': docstring}
    return type('ATest', (unittest.TestCase,), clsdict)

MyTest = makeTestCase('some_filename', my_func, 'This is a docstring')

Answer 2

这是instancemethod从其__func__获取其文档字符串。更改__func__的文档字符串代替。 （的函数的__doc__属性是是可写的。）

>>> class Foo(object):
...     def bar(self):
...         pass
...
>>> Foo.bar.__func__.__doc__ = "A super docstring"
>>> help(Foo.bar)
Help on method bar in module __main__:

bar(self) unbound __main__.Foo method
    A super docstring

>>> foo = Foo()
>>> help(foo.bar)
Help on method bar in module __main__:

bar(self) method of __main__.Foo instance
    A super docstring

从 2.7文档：

  

用户定义的方法

     

一个用户定义的方法对象结合一个类，类的实例（或无）和任何可调用      对象（通常为用户定义的功能）。

     

特殊只读属性：im_self是类的实例对象，im_func是函数      宾语; im_class是绑定方法，或要求将类类本身      方法中未结合的方法;的 __doc__是该方法的文档（同      im_func.__doc__）; __name__是方法名（同im_func.__name__）;      __module__是在被限定的方法的模块的名称，或无如果不可用。

     

在2.2版本更改：im_self用来指的是所限定的方法的类

     

改变在版本2.6：对于3.0前向兼容性，的 im_func也可作为      __func__，并im_self作为__self__。

Answer 3

只需使用装饰器。这里是你的情况：

def add_doc(value):
    def _doc(func):
        func.__doc__ = value
        return func
    return _doc

import unittest
def makeTestCase(filename, my_func):
    class ATest(unittest.TestCase):
        @add_doc('This should be my docstring')
        def testSomething(self):
            # Running test in here with data in filename and function my_func
            data  = loadmat(filename)
            result = my_func(data)
            self.assertTrue(result > 0)

    return ATest

def my_func(): pass

MyTest = makeTestCase('some_filename', my_func)
print MyTest.testSomething.__doc__
> 'This should be my docstring'

这里的一个类似的用例： Python的动态帮助和自动填充代

Answer 4

这是一个除了事实的类型__doc__类的type属性不能改变。有趣的是，这是唯一真正的，只要类使用类型来创建。只要你用元类可以真正地改变__doc__。

该示例使用ABC（AbstractBaseClass）模块。它的工作原理使用一种特殊的ABCMeta元类

import abc

class MyNewClass(object):
    __metaclass__ = abc.ABCMeta

MyClass.__doc__ = "Changing the docstring works !"

help(MyNewClass)

将导致

"""
Help on class MyNewClass in module __main__:

class MyNewClass(__builtin__.object)
 |  Changing the docstring works !
"""

我想这应该是一个评论，但仍在收集我的第一个50分...

Answer 5

__doc__不可写只有当你的对象的类型的“type”的

在你的情况，add_three是一个功能，你可以设置__doc__为任何字符串。

Answer 6

在这里你想自动生成的子类unittest.TestCase生成的情况下，你可能有更多的里程重写他们的 SHORTDESCRIPTION 方法。

这是剥去方法底层文档字符串向下到第一行，如在正常单元测试输出看出;覆盖它足以让我们控制在什么样的报告TeamCity的，这是我们所需要的工具出现了。