python - 使用 NumPy 的向量化的文档字符串不匹配

Question

我有一个函数，需要使用 NumPy 的 vectorize 进行矢量化工厂。正如文档中所述，文档字符串被复制，但 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 仿函数吗？

Answer 1

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__ .