gpt4 book ai didi

python - 是否有使用 sphinx.ext.napoleon 在 Sphinx 中记录函数类型参数的标准格式?

转载 作者:行者123 更新时间:2023-12-04 09:20:52 25 4
gpt4 key购买 nike

我正在使用 Sphinx 来记录我的一个项目,其中一个类在其 __init__ 中接受一个函数作为参数。 .是否有标准方法来记录此函数类型参数?我也在用 sphinx.ext.napoleon 为我的文档字符串使用 Google 格式。
下面是一个例子:

class ExampleClass:
"""An example class to demonstrate my question

Args:
func (what goes here?): Description of the parameter
"""

def __init__(self, func):
self.func = func

def do_something(self, param):
"""An example method

Args:
param (str): Description of param

Returns:
bool: The return description
"""

return self.func(param)
在我的代码中,有问题的参数应该包含一个 str并返回 bool .使用 Sphinx 时是否有标准方法来记录这一点?

最佳答案

记录函数参数的最简单方法是使用 typing.Callable .通过这样做,静态类型检查器将验证传递函数的签名(参数和返回类型)是否与类型提示兼容。

from typing import Callable

class ExampleClassTwo:
"""An example class to demonstrate my question.

Args:
func (Callable[[str], bool]): Description of the parameter.
"""
def __init__(self, func: Callable[[str], bool]):

self.func = func
然而,这有一个潜在的问题。如果您查看 Python 数据模型,在 sub-section titled "Callable types" under 3.2 The standard type hierarchy 中.您会注意到有几种可能的可调用类型,任何具有指定签名的可调用对象都不会导致静态类型检查器发出警告。
例如,实现 __call__() 的类实例方法不会引起警告:
def str_function(param: str) -> bool:
pass

class OneInstance:

def __init__(self, param):
pass

def __call__(self, param: str) -> bool:
pass

one_instance = OneInstance("test instance")
# neither of the below raise a static type check warning
one = ExampleClassTwo(str_function)
two = ExampleClassTwo(one_instance)
您可以输入提示 param如上所示的签名以及验证 param类型为 FunctionType __init__就像您在运行时验证其他参数一样,并引发 TypeError如果参数不是函数,则异常。
from typing import Callable
from types import FunctionType

class ExampleClassTwo:
"""An example class to demonstrate my question

Args:
func (Callable[[str], bool]): Description of the parameter
Raises:
TypeError: Argument `param` is not of type ``FunctionType``.
"""

def __init__(self, func: Callable[[str], bool]):

if type(func) in (FunctionType,):
self.func = func
else:
raise TypeError("param must be initialized as being of ``FunctionType``.")
可以将这两个要求结合起来 Callable[[str], bool]FunctionTypean intersection using structural subtyping ,我还没有尝试过这种方法。
最后包含了一些会导致静态类型检查器发出警告的示例:
def int_function(param: int) -> bool:
pass


class ExampleClass:
"""An example class to demonstrate my question

Args:
func (FunctionType): Description of the parameter
"""

def __init__(self, func: FunctionType):
self.func = func

three = ExampleClass(str_function("test string")) # Expected type 'FunctionType', got 'bool' instead
four = ExampleClass(str_function) # Expected type 'FunctionType', got '(param: str) -> bool' instead
five = ExampleClass(type(str_function)) # No warning five.func is {type} <class 'function'>

six = ExampleClassTwo(int_function(2)) # Expected type '(str) -> bool', got 'bool' instead
seven = ExampleClassTwo(str_function("test string")) # Expected type '(str) -> bool', got 'bool' instead
eight = ExampleClassTwo(int_function) # Expected type '(str) -> bool', got '(param: int) -> bool' instead
nine = ExampleClassTwo(str_function) # No warning
enter image description here

关于python - 是否有使用 sphinx.ext.napoleon 在 Sphinx 中记录函数类型参数的标准格式?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/63103550/

25 4 0
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com