使狮身人面像识别正确的签名 [英] getting sphinx to recognise correct signature

问题描述

我一直在努力获取文档，以便进行我正在从事的开源项目，该项目涉及镜像的客户端和服务器API。为此，我创建了一个装饰器，该装饰器在大多数情况下可用于记录仅对输入进行验证的方法。您可以在的简短评论，请点击此处是我使用 functools 包的原始代码：

  
导入functools 
 
 def trace（f）：
跟踪装饰器。 
 logger = ...＃一些代码确定正确的logger 
 where = ...＃一些代码创建一个字符串来描述我们的位置
 
 @ functools.wraps（f）
 def _trace（* args，** kwargs）：
 logger.debug（输入％s，其中）
结果= f（* args，** kwargs）
 logger.debug（ Leave％s，where）
返回结果
 
 return _trace 
  

，这里使用 decorator 包的代码：

  
导入修饰符
 
 def trace（f）：
跟踪修饰符。  
 logger = ...＃一些代码来确定正确的logger 
 where = ...＃一些代码来创建一个字符串，描述我们的位置
 
 def _trace（ f，* args，** kwargs）：
 logger.debug（ Entering％s，其中）
结果= f（* args，** kwargs）
 logger.debug（离开％s，其中）
返回结果
 
返回decorator.decorate（f，_trace）
  

出于性能原因，我们想移动代码以确定正确的记录器以及实际函数包装中的where字符串。因此，在两个版本中都使用嵌套包装函数。

两个版本的代码都可以在Python 2和Python 3上运行，但是第二个版本为以下版本创建了正确的原型使用Sphinx&时的装饰功能autodoc（如此答案中所建议，无需在autodoc语句中重复原型）。

这与cPython一起使用，我没有尝试Jython等。

I've been trying to get my documentation in order for an open source project I'm working on, which involves a mirrored client and server API. To this end I have created a decorator that can most of the time be used to document a method that simply performs validation on its input. You can find a class full of these methods here and the decorator's implementation here.

The decorator, as you can see uses functools.wraps to preserve the docstring, and I thought also the signature, however the source code vs the generated documentation looks like this:

Source:

vs

Docs:

Does anyone know any way to have setH's generated documentation show the correct call signature? (without having a new decorator for each signature - there are hudreds of methods I need to mirror)

I've found a workaround which involved having the decorator not changing the unbound method, but having the class mutate the method at binding time (object instantiation) - this seems like a hack though, so any comments on this, or alternative ways of doing this, would be appreciated.

解决方案

To expand my short comment on Ethan's answer, here is my original code using the functools package:

import functools

def trace(f):
    """The trace decorator."""
    logger = ... # some code to determine the right logger
    where = ... # some code to create a string describing where we are

    @functools.wraps(f)
    def _trace(*args, **kwargs):
        logger.debug("Entering %s", where)
        result = f(*args, **kwargs)
        logger.debug("Leaving %s", where)
        return result

    return _trace

and here the code using the decorator package:

import decorator

def trace(f):
    """The trace decorator."""
    logger = ... # some code to determine the right logger
    where = ... # some code to create a string describing where we are

    def _trace(f, *args, **kwargs):
        logger.debug("Entering %s", where)
        result = f(*args, **kwargs)
        logger.debug("Leaving %s", where)
        return result

    return decorator.decorate(f, _trace)

We wanted to move the code to determine the right logger and where-string out of the actual function wrapper, for performance reasons. Hence the approach with the nested wrapper function, in both versions.

Both versions of the code work on Python 2 and Python 3, but the second version creates the correct prototypes for the decorated functions when using Sphinx & autodoc (without having to repeat the prototype in the autodoc statements, as suggested in this answer).

This is with cPython, I did not try Jython etc.

这篇关于使狮身人面像识别正确的签名的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！