在Sphinx文档中保留包装/装饰Python函数的默认参数 [英] Preserve default arguments of wrapped/decorated Python function in Sphinx documentation

问题描述

如何在装饰功能的文档中用真实签名替换 * args 和 ** kwargs 假设我有以下装饰和装饰功能：

How can I replace *args and **kwargs with the real signature in the documentation of decorated functions?

Let's say I have the following decorator and decorated function:

import functools

def mywrapper(func):
    @functools.wraps(func)
    def new_func(*args, **kwargs):
        print('Wrapping Ho!')
        return func(*args, **kwargs)
    return new_func

@mywrapper
def myfunc(foo=42, bar=43):
    """Obscure Addition

    :param foo: bar!
    :param bar: bla bla
    :return: foo + bar

    """
    return foo + bar

因此，调用 print（myfunc（3，4））给我们：

Wrapping Ho!
7

到目前为止这么好。我也希望我的库包含 myfunc 正确记录与Sphinx。
但是，如果我通过以下方式将我的功能包含在我的sphinx html页面中：

So far so good. I also want my library containing myfunc properly documented with Sphinx. However, if I include my function in my sphinx html page via:

.. automodule:: mymodule
    :members: myfunc

它实际上会显示为：

隐藏加法

• 参数：
  
  
  
  • foo ：bar！
  
  < bar ：bla bla
  
  • Parameters:
    • foo: bar!
    • bar: bla bla

    我如何摆脱通用的 myfunc（* args，** kwargs）在标题中？这应该由 myfunc（foo = 42，bar = 43）替代。如何在文档中保留默认的关键字参数？

    How can I get rid of the generic myfunc(*args, **kwargs) in the title? This should be replaced by myfunc(foo=42, bar=43). How can I change sphinx or my decorator mywrapper such that the default keyword arguments are preserved in the documentation?

    strong>编辑：

    正如所指出的，此问题已经被问过，但答案并不那么有帮助。

    As pointed out this question has been asked before, but the answers are not so helpful.

    然而，我有一个想法，想知道这是否可能。 Sphinx设置了一些环境变量，告诉我的模块它实际上是由Sphinx导入的？如果是这样，我可以简单地猴子补丁我自己的包装纸。如果我的模块由Sphinx导入，我的包装器返回原来的功能而不是包装它们。因此，签名被保留。

    However, I had an idea and wonder if this is possible. Does Sphinx set some environment variable that tells my module that it is actually imported by Sphinx? If so, I could simply monkey-patch my own wrappers. If my module is imported by Sphinx my wrappers return the original functions instead of wrapping them. Thus, the signature is preserved.

    推荐答案

    我想出了一个猴子补丁为 functools.wraps 。
    因此，我简单地将其添加到项目文档的sphinx 源文件夹中的 conf.py 脚本中：

    I came up with a monkey-patch for functools.wraps. Accordingly, I simply added this to the conf.py script in my project documentation's sphinx source folder:

    # Monkey-patch functools.wraps
    import functools
    
    def no_op_wraps(func):
        """Replaces functools.wraps in order to undo wrapping.
    
        Can be used to preserve the decorated function's signature
        in the documentation generated by Sphinx.
    
        """
        def wrapper(decorator):
            return func
        return wrapper
    
    functools.wraps = no_op_wraps
    

    因此，当通过 make html 构建html页面时， functools.wraps 替换为这个装饰器 no_op_wraps ，绝对只是简单地返回原来的功能。

    Hence, when building the html page via make html, functools.wraps is replaced with this decorator no_op_wraps that does absolutely nothing but simply return the original function.

    这篇关于在Sphinx文档中保留包装/装饰Python函数的默认参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！