Docstring不匹配使用NumPy的矢量化

时间:2015-04-11 12:25:12

标签: python numpy python-sphinx

我有一个函数,需要使用NumPy的vectorize工厂进行矢量化。如文档中所述,docstring被复制,但似乎help和Sphinx没有使用实际对象的__doc__属性。很可能它与vectorize返回的对象类型有关,numpy.lib.function_base.vectorize而不是function

这是一个最小的例子:

import numpy as np

def _f(x):
    """Function to be vectorized"""
    return x**2

f = np.vectorize(_f)  # Will be exported from the module as public API
print f.__doc__       # Prints _f.__doc__
print help(f)         # Prints np.vectorize.__doc__

虽然__doc__提供了函数_f中定义的文档字符串,但help(f)显示了vectorize函数的完整文档。因此,导出的函数对象f及其文档不会被Sphinx的autodoc扩展文件选中。

我想到的一个快速解决方案是将矢量化包装在另一个函数中并在此处定义文档字符串。但这对我来说似乎有点尴尬:

def wrapper(x):
    """Function to be vectorized"""
    tmp = np.vectorize(_f)
    return tmp(x)

是否有人遇到同样的问题并且知道更好的解决方案让autodoc与vectorize仿函数一起使用?

1 个答案:

答案 0 :(得分:3)

np.vectorize实际上是一个类,因此f = np.vectorize(_f)是对其__init__的调用,并返回该类的实例。当您使用f(abc)时,实际上是在调用其__call__方法。

f.__doc__是在创建过程中根据您提供的参数或_f.__doc__分配给该实例的属性。

看起来help(f)(和autodoc?)显示的是类.__doc__,而不是实例自己的__doc__type(f).__doc__

这不是一个解决方案,但它可能有助于指出正确的方向。

如果我np.vectorize.__doc__=f.__doc__help(f)现在显示:

Help on vectorize in module numpy.lib.function_base object:

f = class vectorize(builtins.object)
 |  Function to be vectorized
 |  
 |  Methods defined here:
 |  
 |  __call__(self, *args, **kwargs)
 |      Return arrays with the results of `pyfunc` broadcast (vectorized) over
 |      `args` and `kwargs` not in `excluded`.
 ...

这会显示已分配的__doc__,但也会显示类方法。

np.ufunc个对象显示出类似的行为。将help(np.add)np.add.__doc__进行比较。一个显示所有ufunc的背景信息,另一个显示该对象的具体信息。

事实上,对于help的任何类对象,__call__都会给出类__doc__。我想知道是否有一种方法可以调整pydoc.help,以便在使用类__doc__之前检查实例是否为__doc__