问题 Python C扩展：文档的方法签名？

我正在编写C扩展，我想使我的方法的签名可见为内省。

static PyObject* foo(PyObject *self, PyObject *args) {

    /* blabla [...] */

}

PyDoc_STRVAR(
    foo_doc,
    "Great example function\n"
    "Arguments: (timeout, flags=None)\n"
    "Doc blahblah doc doc doc.");

static PyMethodDef methods[] = {
    {"foo", foo, METH_VARARGS, foo_doc},
    {NULL},
};

PyMODINIT_FUNC init_myexample(void) {
    (void) Py_InitModule3("_myexample", methods, "a simple example module");
}

现在，如果（在构建它之后......）我加载模块并查看它的帮助：

>>> import _myexample
>>> help(_myexample)

我会得到：

Help on module _myexample:

NAME
    _myexample - a simple example module

FILE
    /path/to/module/_myexample.so

FUNCTIONS
    foo(...)
        Great example function
        Arguments: (timeout, flags=None)
        Doc blahblah doc doc doc.

我想更具体，能够取代 富（...） 通过 foo（超时，标志=无）

我可以这样做吗？怎么样？

3019

2017-07-09 15:54

起源

答案:

我通常的方法是找出这样的事情：“使用来源”。

基本上，我认为python的标准模块在可用时会使用这样的功能。看源头（比如这里）应该有所帮助，但实际上即使是标准模块也会在自动输出后添加原型。喜欢这个：

torsten @ pulsar：〜$ python2.6
>>>导入fcntl
>>>帮助（fcntl.flock）
群（...）
    羊群（fd，手术）

    对文件描述符fd执行锁定操作op。看到Unix [...]

因为上游没有使用这样的功能，我认为它不存在。 :-)

好的，我刚检查了当前的python3k源代码，情况仍然如此。该签名生成于 pydoc.py 在这里的python源代码中： pydoc.py。从第1260行开始的相关摘录：

        如果inspect.isfunction（object）：
            args，varargs，varkw，defaults = inspect.getargspec（object）
            ...
        其他：
            argspec ='（...）'

inspect.isfunction检查请求文档的对象是否为Python函数。但C实现的函数被认为是内置函数，因此您将始终获得 name(...) 作为输出。

2017-07-09 16:11

已经7年了 但您可以包含C扩展功能和类的签名。

Python本身使用争论诊所动态生成签名。然后一些机制创造了一个 __text_signature__ 这可以是内省的（例如 help）。 @MartijnPieters很好地解释了这个过程这个答案。

你实际上可以从python获得参数诊所并以动态方式进行，但我更喜欢手动方式：将签名添加到docstring：

在你的情况下：

PyDoc_STRVAR(
    foo_doc,
    "foo(timeout, flags=None, /)\n"
    "--\n"
    "\n"
    "Great example function\n"
    "Arguments: (timeout, flags=None)\n"
    "Doc blahblah doc doc doc.");

我在包装中大量使用了这个： iteration_utilities/src。因此，为了演示它的工作原理，我使用了这个包暴露的C-extension函数之一：

>>> from iteration_utilities import minmax
>>> help(minmax)
Help on built-in function minmax in module iteration_utilities._cfuncs:

minmax(iterable, /, key, default)
    Computes the minimum and maximum values in one-pass using only
    ``1.5*len(iterable)`` comparisons. Recipe based on the snippet
    of Raymond Hettinger ([0]_) but significantly modified.

    Parameters
    ----------
    iterable : iterable
        The `iterable` for which to calculate the minimum and maximum.
[...]

定义了此函数的docstring 这个文件。

重要的是要意识到这一点 python <3.4是不可能的 你需要遵循一些规则：

你需要包括 --\n\n 签名定义行之后。
签名必须位于docstring的第一行。
签名必须有效，即 foo(a, b=1, c) 失败，因为在默认参数之后无法定义位置参数。
您只能提供一个签名。因此，如果您使用以下内容，它将无效：
```
foo(a)
foo(x, a, b)
--

Narrative documentation
```

2017-12-20 15:09

这适用吗？ inspect.signature？ - Eric

@Eric是的，只要符合规则 __text_signature__ 我上面提到过。 - MSeifert

听起来像是一件事 numpy 需要补丁 - Eric

github.com/numpy/numpy/issues/8734 - Eric

答案: