向扩展方法添加带有注释的签名

当在我的应用程序中嵌入 Python 并编写扩展类型时，我可以添加signature通过使用正确制作的方法.tp_doc string.

static PyMethodDef Answer_methods[] = {
  { "ultimate", (PyCFunction)Answer_ultimate, METH_VARARGS, 
    "ultimate(self, question='Life, the universe, everything!')\n"
    "--\n"
    "\n"
    "Return the ultimate answer to the given question." },
  { NULL }
};

When help(Answer)执行后，返回以下内容（略）：

class Answer(builtins.object)
 |
 |  ultimate(self, question='Life, the universe, everything!')
 |      Return the ultimate answer to the given question.

这很好，但我使用的是Python3.6，它支持注释。我想将问题注释为字符串，并将函数注释为返回整数。我试过了：

static PyMethodDef Answer_methods[] = {
  { "ultimate", (PyCFunction)Answer_is_ultimate, METH_VARARGS, 
    "ultimate(self, question:str='Life, the universe, everything!') -> int\n"
    "--\n"
    "\n"
    "Return the ultimate answer to the given question." },
  { NULL }
};

但这又回到了(...)符号，文档变为：

 |  ultimate(...)
 |      ultimate(self, question:str='Life, the universe, everything!') -> int
 |      --
 |
 |      Return the ultimate answer to the given question.

并要求inspect.signature(Answer.ultimate)结果出现异常。

Traceback (most recent call last):
  File "<string>", line 11, in <module>
  File "inspect.py", line 3037, in signature
  File "inspect.py", line 2787, in from_callable
  File "inspect.py", line 2266, in _signature_from_callable
  File "inspect.py", line 2090, in _signature_from_builtin
ValueError: no signature found for builtin <built-in method ultimate of example.Answer object at 0x000002179F3A11B0>

我尝试使用 Python 代码在事后添加注释：

example.Answer.ultimate.__annotations__ = {'return': bool}

但是内置方法描述符不能以这种方式添加注释。

Traceback (most recent call last):
  File "<string>", line 2, in <module>
AttributeError: 'method_descriptor' object has no attribute '__annotations__'

有没有办法使用 C-API 向扩展方法添加注释？

Argument Clinic 看起来很有前途，可能仍然非常有用，但从 3.6.5 开始，它不支持注释 https://docs.python.org/3/howto/clinic.html#using-real-argument-clinic-converters-instead-of-legacy-converters.

annotation
该参数的注释值。目前不支持，因为 PEP 8 要求 Python 库不得使用注释。

TL;DR 有现在没有办法做到这一点。

签名和 C 扩展如何协同工作？

理论上它的工作原理如下（对于 Python C 扩展对象）：

• 如果 C 函数具有“正确的文档字符串”，则签名将存储在__text_signature__属性。
• 如果你打电话help or inspect.signature在这样的对象上，它解析__text_signature__并尝试从中构建一个签名。

如果您使用参数诊所，则不需要自己编写“正确的文档字符串”。签名行是根据代码中的注释生成的。然而前面提到的两个步骤仍然会发生。他们只是发生了到自动生成的签名行.

这就是为什么内置 Python 函数如sum have a __text-signature__s:

>>> sum.__text_signature__
'($module, iterable, start=0, /)'

本例中的签名是通过基于参数的 Clinic 生成的关于周围的评论sum执行 https://github.com/python/cpython/blob/v3.6.5/Python/bltinmodule.c#L2212-L2228.

注释有哪些问题？

注解存在几个问题：

• 返回注释打破了“正确文档字符串”的约定。所以__text_signature__添加返回注释时将为空。这是一个主要问题，因为解决方法必然涉及重写 CPython C 代码中负责文档字符串的部分 ->__text_signature__翻译！这不仅很复杂，而且您还必须提供更改后的 CPython 版本，以便它适用于使用您的函数的人。

  举个例子，如果你使用这个“签名”：

  ultimate(self, question:str='Life, the universe, everything!') -> int
  

  You get:

  >>> ultimate.__text_signature__ is None
  True
  

  但是如果删除返回注释：

  ultimate(self, question:str='Life, the universe, everything!')
  

  它给你一个__text_signature__:

  >>> ultimate.__text_signature__
  "(self, question:str='Life, the universe, everything!')"
  

• 如果您没有返回注释，它仍然无法工作，因为（当前）明确不支持注释。

  假设你有这个签名：

  ultimate(self, question:str='Life, the universe, everything!')
  

  它不适用于inspect.signature（异常消息实际上说明了一切）：

  >>> import inspect
  >>> inspect.signature(ultimate)
  Traceback (most recent call last):
  ...
      raise ValueError("Annotations are not currently supported")
  ValueError: Annotations are not currently supported
  

  负责解析的函数__text_signature__ is inspect._signature_fromstr https://github.com/python/cpython/blob/v3.6.5/Lib/inspect.py#L1938-L2076。从理论上讲，您有可能maybe可以通过猴子修补让它工作（返回注释仍然不起作用！）。但也许不是，有几个地方对__text_signature__这可能不适用于注释。

Would PyFunction_SetAnnotations https://docs.python.org/c-api/function.html#PyFunction_SetAnnotations work?

在评论中提到了这个 C API 函数。然而，这故意不适用于 C 扩展函数。如果你尝试在 C 扩展函数上调用它，它将引发SystemError: bad argument to internal function call。我用一个小的 Cython Jupyter“脚本”对此进行了测试：

%load_ext cython

%%cython

cdef extern from "Python.h":
    bint PyFunction_SetAnnotations(object func, dict annotations) except -1

cpdef call_PyFunction_SetAnnotations(object func, dict annotations):
    PyFunction_SetAnnotations(func, annotations)

>>> call_PyFunction_SetAnnotations(sum, {})

---------------------------------------------------------------------------
SystemError                               Traceback (most recent call last)
<ipython-input-4-120260516322> in <module>()
----> 1 call_PyFunction_SetAnnotations(sum, {})

SystemError: ..\Objects\funcobject.c:211: bad argument to internal function

所以这也不适用于 C 扩展函数。

Summary

因此，返回注释目前完全不可能（至少在不随程序分发您自己的 CPython 的情况下）。参数注释could如果你对私有函数进行猴子修补，则可以工作inspect模块。这是一个Python模块，所以它could是可行的，但我还没有进行概念验证，所以将其视为也许有可能，但可能非常复杂，而且几乎肯定不值得这么麻烦.

但是，您始终可以用 Python 函数包装 C 扩展函数（只是一个非常简单的包装器）。这个Python 包装器可以有函数注释。它需要更多的维护并且速度稍慢一些，但是可以为您省去签名和 C 扩展的所有麻烦。我不太确定，但如果您使用 Cython 来包装 C 或 C++ 代码，它甚至可能有一些自动化工具（自动编写 Python 包装器）。