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

Question

我有一个返回函数的包装函数.有没有办法以编程方式设置返回函数的docstring？如果我可以写信,__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

如果我创建这个类并尝试设置docstring 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

一个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文档:

用户定义的方法

用户定义的方法对象组合了类,类实例(或None)和任何可调用对象(通常是用户定义的函数).

特殊的只读属性:im_self是类实例对象,im_func是函数对象; im_class是绑定方法的im_self类或要求未绑定方法的方法的类; __doc__方法的文档(同 im_func.__doc__); __name__是方法名称(与im_func.__name__)相同; __module__是定义方法的模块的名称,如果不可用则是None.

版本2.2中更改:im_self用于引用定义方法的类.

在版本2.6中更改:对于3.0向前兼容性,im_func也可用 __func__,并且im_self为__self__.

Answer 2

我会将docstring传递给工厂函数并用于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 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__ 仅当您的对象属于“类型”类型时才可写。

在您的情况下，add_three是一个函数，您可以设置__doc__为任何字符串。