Python C扩展：文档的方法签名？ [英] Python C extension: method signatures for documentation?

问题描述

 静态的
我正在编写C扩展名，我想让我的方法的签名可以看得到。 PyObject * foo（PyObject * self，PyObject * args）{
 
 / * blabla [...] * / 
 
} 
 
 PyDoc_STRVAR 
 foo_doc，
很好的例子function\\\

参数：（timeout，flags = None）\\\

Doc blahblah doc doc doc 
 
 static PyMethodDef methods [] = {
 {foo，foo，METH_VARARGS，foo_doc}，
 {NULL}，
}; 
 
 PyMODINIT_FUNC init_myexample（void）{
（void）Py_InitModule3（_ myexample，方法，一个简单的示例模块）; 
} 
  

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

 >>> import _myexample 
>>>帮助（_myexample）
  

我会得到：

 帮助模块_myexample：
 
 NAME 
 _myexample  - 一个简单的示例模块
 
 FILE 
 / path /to/module/_myexample.so 
 
 FUNCTIONS 
 foo（...）
很好的例子函数
参数：（timeout，flags = None）
 Doc blahblah doc doc doc 
  

我想要更加具体，可以替换 foo（... ）由 foo（timeout，flags = None）

我可以这样做吗？如何？

解决方案

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

基本上，我假定python的标准模块可以使用这样的功能。查看来源（例如这里）应该有帮助，但实际上甚至标准模块在自动输出后添加原型。像这样：

 torsten @ pulsar：〜$ python2.6 
 >>> import fcntl 
 >>> help（fcntl。 flock）
 flock（...）
 flock（fd，operation）
 
对文件描述符fd执行锁操作op。看到Unix [...] 
 

所以上游没有使用这样的功能，我假设它不在那里。 ： - ）

好的，我刚刚检查了目前的python3k源码，但仍然如此。这个签名是在这里的python来源的 pydoc.py 中生成的： pydoc.py 。相关摘录从1260行开始：

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

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

I am writing C extensions, and I'd like to make the signature of my methods visible for introspection.

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");
}

Now if (after building it...) I load the module and look at its help:

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

I will get:

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.

I would like to be even more specific and be able to replace foo(...) by foo(timeout, flags=None)

Can I do this? How?

解决方案

My usual approach to finding out about things like this is: "use the source".

Basically, I would presume that the standard modules of python would use such a feature when available. Looking at the source (for example here) should help, but in fact even the standard modules add the prototype after the automatic output. Like this:

torsten@pulsar:~$ python2.6
>>> import fcntl
>>> help(fcntl.flock)
flock(...)
    flock(fd, operation)

    Perform the lock operation op on file descriptor fd.  See the Unix [...]

So as upstream is not using such a feature, I would assume it is not there. :-)

Okay, I just checked current python3k sources and this is still the case. That signature is generated in pydoc.py in the python sources here: pydoc.py. Relevant excerpt starting in line 1260:

        if inspect.isfunction(object):
            args, varargs, varkw, defaults = inspect.getargspec(object)
            ...
        else:
            argspec = '(...)'

inspect.isfunction checks if the object the documentation is requested for is a Python function. But C implemented functions are considered builtins, therefore you will always get name(...) as the output.

这篇关于Python C扩展：文档的方法签名？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！