草庐IT

Python C 扩展 : method signatures for documentation?

coder 2023-08-15 原文

我正在编写 C 扩展，并且我想让我的方法的签名可见以便自省(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");
}

现在如果(在构建它之后......)我加载模块并查看它的帮助:

>>> 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(timeout, flags=None) 替换 foo(...)

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

最佳答案

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

Python 本身使用 Argument Clinic动态生成签名。然后一些机制创建了一个 __text_signature__ 并且可以对其进行自省(introspection)(例如使用 help)。 @MartijnPieters 在 this answer 中很好地解释了这个过程.

您实际上可以从 python 获取参数 clinic 并以动态方式进行，但我更喜欢手动方式:将签名添加到文档字符串:

在你的情况下:

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 扩展函数之一:

>>> 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.
[...]

此函数的文档字符串已定义 this file .

重要的是要意识到这对于 python <> 是不可能的，您需要遵循一些规则:

  • 您需要在签名定义行之后包含--\n\n。

  • 签名必须在文档字符串的第一行。

  • 签名必须有效，即 foo(a, b=1, c) 失败，因为无法在默认参数之后定义位置参数。

  • 您只能提供一个签名。因此，如果您使用类似的东西，它就不起作用:

    foo(a)
foo(x, a, b)
--

Narrative documentation

关于Python C 扩展 : method signatures for documentation?，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/1104823/

documentationsignaturescodeiteration_utilitiesiterationpythonpython-c-api

有关Python C 扩展 : method signatures for documentation?的更多相关文章

  1. ruby - 使用 C 扩展开发 ruby​​gem 时，如何使用 Rspec 在本地进行测试？ - 2

    我正在编写一个包含C扩展的gem。通常当我写一个gem时，我会遵循TDD的过程，我会写一个失败的规范，然后处理代码直到它通过，等等......在“ext/mygem/mygem.c”中我的C扩展和在gemspec的“扩展”中配置的有效extconf.rb，如何运行我的规范并仍然加载我的C扩展？当我更改C代码时，我需要采取哪些步骤来重新编译代码？这可能是个愚蠢的问题，但是从我的gem的开发源代码树中输入“bundleinstall”不会构建任何native扩展。当我手动运行rubyext/mygem/extconf.rb时，我确实得到了一个Makefile(在整个项目的根目录中)，然后当

  2. c - mkmf 在编译 C 扩展时忽略子文件夹中的文件 - 2

    我想这样组织C源代码:+/||___+ext||||___+native_extension||||___+lib||||||___(Sourcefilesarekeptinhere-maycontainsub-folders)||||___native_extension.c||___native_extension.h||___extconf.rb||___+lib||||___(Rubysourcecode)||___Rakefile我无法使此设置与mkmf一起正常工作。native_extension/lib中的文件(包含在native_extension.c中)将被完全忽略。

  3. ruby-on-rails - 向 Rails 3 添加 Ruby 扩展方法的最佳实践？ - 2

    我有一个要在我的Rails3项目中使用的数组扩展方法。它应该住在哪里？我有一个应用程序/类，我最初把它放在(array_extensions.rb)中，在我的config/application.rb中我加载路径:config.autoload_paths+=%W(#{Rails.root}/应用程序/类)。但是，当我转到railsconsole时，未加载扩展。是否有一个预定义的位置可以放置我的Rails3扩展方法？或者，一种预先定义的方式来添加它们？我知道Rails有自己的数组扩展方法。我应该将我的添加到active_support/core_ext/array/conversion

  4. ruby - 如何在 ruby​​ 中复制目录结构，不包括某些文件扩展名 - 2

    我想编写一个ruby​​脚本来递归复制目录结构，但排除某些文件类型。因此，给定以下目录结构:folder1folder2file1.txtfile2.txtfile3.csfile4.htmlfolder2folder3file4.dll我想复制这个结构，但不包含.txt和.cs文件。因此，生成的目录结构应如下所示:folder1folder2file4.htmlfolder2folder3file4.dll 最佳答案 您可以使用查找模块。这是一个代码片段:require"find"ignored_extensions=[".cs"

  5. ruby - 扩展类和实例 - 2

    这个问题有两个部分。在RubyProgrammingLanguage一书中，有一个使用模块扩展字符串对象和类的示例(第8.1.1节)。第一个问题。为什么如果您使用新方法扩展类，然后创建该类的对象/实例，则无法访问该方法？irb(main):001:0>moduleGreeter;defciao;"Ciao!";end;end=>nilirb(main):002:0>String.extend(Greeter)=>Stringirb(main):003:0>String.ciao=>"Ciao!"irb(main):004:0>x="foobar"=>"foobar"irb(main):

  6. ruby - 动态扩展现有方法或覆盖 ruby​​ 中的发送方法 - 2

    假设我们有A、B、C类。Adefself.inherited(sub)#metaprogramminggoeshere#takeclassthathasjustinheritedclassA#andforfooclassesinjectprepare_foo()as#firstlineofmethodthenrunrestofthecodeenddefprepare_foo#=>prepare_foo()neededhere#somecodeendendBprepare_foo()neededhere#somecodeendend如您所见，我正在尝试将foo_prepare()调用注入

  7. ruby-on-rails - 如何扩展 Ruby Test::Unit 断言以包含 assert_false？ - 2

    显然在Test::Unit中没有assert_false。您将如何通过扩展断言并添加文件config/initializers/assertions_helper.rb来添加它？这是最好的方法吗？我不想修改test/unit/assertions.rb。顺便说一句，我不认为这是多余的。我使用的是assert_equalfalse,something_to_evaluate。这种方法的问题是很容易意外使用assertfalse,something_to_evaluate。这将始终失败，不会引发错误或警告，并且会在测试中引入错误。 最佳答案

  8. ruby-on-rails - 无法构建 gem native 扩展 (mkmf (LoadError)) - Ubuntu 12.04 - 2

    这个问题在这里已经有了答案:Unabletoinstallgem-Failedtobuildgemnativeextension-cannotloadsuchfile--mkmf(LoadError)(17个答案)关闭9年前。嘿，我正在尝试在一台新的ubuntu机器上安装rails。我安装了ruby​​和rvm，但出现“无法构建gemnative扩展”错误。这是什么意思？$sudogeminstallrails-v3.2.9(没有sudo表示我没有权限)然后它会输出很多“获取”命令，最终会出现这个错误:Buildingnativeextensions.Thiscouldtakeawhi

  9. ruby-on-rails - 使用模块扩展带有 "has_many"的插件中的模型 - 2

    我在引擎样式插件中有一些代码，其中包含一些模型。在我的应用程序中，我想扩展其中一个模型。通过在初始值设定项中包含一个模块，我已经设法将实例和类方法添加到相关模型中。但是我似乎无法添加关联、回调等。我收到“找不到方法”错误。/libs/qwerty/core.rbmoduleQwertymoduleCoremoduleExtensionsmoduleUser#InstanceMethodsGoHere#ClassMethodsmoduleClassMethodshas_many:hits,:uniq=>true#nomethodfoundbefore_validation_on_crea

  10. ruby-on-rails - Ruby 1.9.3 -> 2.0 别名方法和扩展 - 2

    我正在尝试将Ruby1.9.3应用程序升级到2.0，除了一个小问题外，一切似乎都很顺利。我写了一个模块，我将其包含在我的模型中以覆盖activerecorddestroy。它将现有的destroy方法别名为destroy!，然后覆盖destroy以更改记录上的deleted_at时间戳。仅当我升级到ruby​​2.0时，destroy!不再破坏记录，但其行为就像我的新覆盖方法一样。知道为什么会这样吗？下面是更相关的代码部分。完整要点here.defself.included(base)base.class_evaldoalias_method:destroy!,:destroyalia

随机推荐