使用哨兵对象记录Sphinx中的带默认参数的Python方法？

Question

如果你想让别人可以用 None 来调用某些方法，你需要在定义方法的时候使用一个叫做 哨兵对象。

 _sentinel = object()
 def foo(param1=_sentinel):
     ...

这样你就可以像这样调用 foo(param1=None)，并且能够区分出像 foo() 这样的调用。

问题是，当 Sphinx 生成文档时，它会写出类似这样的内容：

mymodule.foo(param1=<object object at 0x108c1a520>)

我该如何让 Sphinx 为这些函数生成更友好的输出呢？

想象一下，如果你有 3-4 个参数使用哨兵方法，文档会是什么样子。

Answer 1

生成的方法签名中的 <object object at 0x108c1a520> 这一部分，可以通过重写哨兵对象的 __repr__ 方法来改变。

_sentinel = type('_sentinel', (object,),
                 {'__repr__': lambda self: '_sentinel'})()

这部分内容会被 Sphinx 渲染成类似这样的样子：

mymodule.foo(param1=_sentinel)

Answer 2

这可以通过在自动文档指令中手动指定函数的签名来解决，比如：

.. automodule:: pymorphy.contrib.tokenizers

    .. autofunction:: extract_tokens(foo, bar)

    .. autofunction:: extract_words

Answer 3

我觉得如果你有一个哨兵（sentinel）在函数外创建对象的话，想让Sphinx变得更“友好”是不太可能的。Sphinx的自动文档扩展会导入模块，这就意味着模块里的代码会被执行。

你确定不能用类似这样的东西吗？

def foo(param1=None):
    if param1 == None:
        param1 = whatever you want...
    else:
         ...