numpy.lib.add_newdoc#

lib.add_newdoc(place, obj, doc, warn_on_python=True)[source]#

为已有对象添加文档，通常是用 C 定义的对象

其目的是在不需要重新编译的情况下更方便地编辑 docstring。此功能主要供 NumPy 内部使用。

参数:
placestr

要导入的模块的绝对名称

objstr | None

要添加文档的对象名称，通常是类或函数名称。

docstr | tuple[str, str] | list[tuple[str, str]]

如果是字符串，则为要应用于 obj 的文档。

如果是元组，则第一个元素被解释为 obj 的属性，第二个元素为要应用的 docstring —— (method, docstring)

如果是列表，则列表的每个元素应为长度为二的元组 —— [(method1, docstring1), (method2, docstring2), ...]

warn_on_pythonbool

如果为 True（默认），在对纯 Python 对象附加文档时会发出 UserWarning。

备注

如果无法写入 docstring，此例程永不会抛出错误，但如果被记录的对象不存在，则会抛出错误。

此例程无法修改只读的 docstring，例如新式类或内建函数中的 docstring。由于该例程永不抛出错误，调用者必须手动检查 docstring 是否已更改。

由于此函数从 C 级别的 str 对象获取 char * 并放入 obj 类型的 tp_doc 槽位，它违反了多项 C-API 最佳实践，具体表现为

  • 在调用 PyType_Ready 之后修改 PyTypeObject

  • 对 str 调用 Py_INCREF 并丢失引用，导致该 str 永不释放

如有可能，应避免这样做。

在此页面