如何使用Python的文档字符串记录带参数的方法？
编辑: PEP 257给出了这个例子:
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0: return complex_zero
...
这是大多数Python开发人员使用的约定吗？
Keyword arguments:
<parameter name> -- Definition (default value if any)
我期待一些更正式的东西,比如
def complex(real=0.0, imag=0.0):
"""Form a complex number.
@param: real The real part (default 0.0)
@param: imag The imaginary part (default 0.0)
"""
if imag == 0.0 and real …我知道PHP或Java的虚拟方法.
它们如何在Python中实现？
或者我要在抽象类中定义一个空方法并覆盖它？
我正在尝试清理我的python代码文档,并决定使用sphinx-doc,因为它看起来不错.我喜欢如何使用以下标签引用其他类和方法:
:class:`mymodule.MyClass` About my class.
:meth:`mymodule.MyClass.myfunction` And my cool function
我试图弄清楚如何在函数中记录参数名称,所以如果我有一个像这样的函数:
def do_this(parameter1, parameter2):
"""
I can describe do_this.
:something?:`parameter1` And then describe the parameter.
"""
这是最好的做法是什么？
更新:
正确的语法是:
def do_this(parameter1, parameter2):
"""
I can describe do_this.
:something parameter1: And then describe the variable
"""
我知道用于构建 Google 风格的文档字符串的语法，例如：
def function_with_types_in_docstring(param1, param2):
"""Example function with types documented in the docstring.
`PEP 484`_ type annotations are supported. If attribute, parameter, and
return types are annotated according to `PEP 484`_, they do not need to be
included in the docstring:
Args:
param1 (int): The first parameter.
param2 (str): The second parameter.
Returns:
bool: The return value. True for success, False otherwise.
"""
但是，如果我有一个函数可以根据执行的代码分支返回多种类型怎么办？记录这一点的正确方法是什么？
下面是一个例子。该部分应该放入什么Returns？
def foo(x, y):
"""Dummy function.
Args:
x (int): integer
y (int): integer …我正在使用Sphinx(make HTML)从其函数的reStructuredText文档字符串自动生成Python 3模块的HTML文档.到目前为止,生成的HTML文档看起来很好,但函数签名的参数类型(在源代码中作为PEP484类型提示给出)未正确显示.
例如,这是我的一个函数的Sphinx生成的HTML文档的一些示例输出:
static parse_from_file(filename: str) ? list
Parses stuff from a text file.
Parameters: filename – the filepath of a textfile to be parsed
Returns: list of parsed elements
这就是我期望的样子:
static parse_from_file(filename)
Parses stuff from a text file.
Parameters: filename (str) – the filepath of a textfile to be parsed
Returns: list of parsed elements
Return type: list
这就是Python代码的实际外观:
def parse_from_file(filename: str) -> list:
"""Parses stuff from a text file.
:param filename: the filepath of a …我目前正在使用Sphinx和autodoc插件为我的python包编写文档.对于函数返回值,我可以写例如:returns: int: count,告诉sphinx存在类型为int的返回值,命名为count.
我现在有一个函数,它让我的数据库中的项目的前辈:
def get_previous_release(release_id):
""" Holt Vorgängeritem eines Items mit der ID release_id
:param release_id: ID des items für das Release
:type release_id: int
"""
if not isinstance(release_id, int):
raise ValueError('get_previous_release expects an Integer value for the parameter release_id')
try:
release = my_queries.core.get_by_id(release_id)
except IndexError:
raise LookupError('The item with id {} could no be found'.format(release_id))
if 'Alpha-Release' in release.name:
release = AlphaRelease(release.key, release.name, release.state)
elif 'Beta-Release' in release.name:
release = BetaRelease(release.key, release.name, release.state)
elif '-Release' in …Sphinx是否有一个支持的标准来记录参数或返回值类型不是一个简单的单个对象？
例如,在下面,arg1是str,arg2是str的列表,arg3是str或int.如何在Sphinx中指定集合或复合类型？或者这没有共同的标准？
def function(arg1, arg2, arg3):
"""
:param arg1: Argument 1
:type arg1: str
:param arg2: Argument 2
:type arg2: list[str]
:param arg3: Argument 3
:type arg3: str or int
"""
pass