我正在使用 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] 和 FunctionType
的要求组合为 an 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
关于python - Sphinx 中是否有使用 sphinx.ext.napoleon 记录函数类型参数的标准格式?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/63103550/