如何记录Python函数的参数类型？

Question

我知道参数可以是任何对象，但在文档中指定您期望的内容非常重要。

首先，如何指定以下类型的参数？

• str（或使用String或string？）
• int
• list
• dict
• function()
• tuple
• MyClass类的对象实例

其次，如何指定可以是多种类型的参数，例如可以处理单个参数的函数，该参数可以是int或str？

请使用下面的示例演示所需的语法及您提出的解决方案。请注意，希望能够从文档内部超链接到“Image”类的引用。

def myMethod(self, name, image):
    """
    Does something ...

    name String: name of the image
    image Image: instance of Image Class or a string indicating the filename.

    Return True if operation succeeded or False.
    """
    return True

请注意，欢迎建议使用任何文档工具（如Sphinx，Oxygen等），只要它能够满足要求。

更新：

似乎doxygen中有一些支持记录参数类型的功能。下面的代码可以工作，但会在参数名称前加上一个烦人的$符号（因为它最初是为PHP设计的）。

    @param str $arg description
    @param str|int $arg description

- sorin

---

您可以提供的最佳输入输出文档是一组通过单元测试，使用unittest框架。 - johnsyweb

@Johnsyweb，你的链接很遗憾地已经失效了。https://docs.python.org/2/library/unittest.html - Kev1n91

7年后，https://docs.python.org/2/library/unittest.html 或 https://docs.python.org/3/library/unittest.html 应该仍然可用。 - johnsyweb

Answer 1

有更好的方法。我们使用

def my_method(x, y):
    """
    my_method description

    @type x: int
    @param x: An integer

    @type y: int|string
    @param y: An integer or string

    @rtype: string
    @return: Returns a sentence with your variables in it
    """

    return "Hello World! %s, %s" % (x,y)

就是这样了。在PyCharm集成开发环境中，这对我帮助很大。它非常好用；-）

- Tony Melony

---

这似乎不起作用。当我在开头引号后添加了一个'!'时，它就起作用了。 - SW_user2953243

1. 要创建函数文档，请在函数头中按alt+Enter并选择“插入文档字符串存根”https://www.jetbrains.com/pycharm/webhelp/creating-documentation-comments.html
2. 在PyCharm中，docstring的默认格式是“重构文本”。您可以在“文件”->“设置”->“Python集成工具”->“Dostring格式”中将其更改为Epytext（如上所述的Tony Melony清单）。请参阅epydoc参考http://epydoc.sourceforge.net/epytext.html

- d9k

Eclipse 中的 PyDev 也喜欢这样。 - shrewmouse

Answer 2

为了使Doxygen正确解析Python文档字符串，您需要在开头加上感叹号。

def myMethod(self, name, image):
    """!
    Does something ...

    @param name String: name of the image
    @param image Image: instance of Image Class or a string indicating the filename.

    @return Return True if operation succeeded or False.
    """
    return True

- docu

Answer 3

如果使用Python 3，您可以使用PEP 3107中描述的函数注释。

def compile(
   source: "something compilable",
   filename: "where the compilable thing comes from",
   mode: "is this a single statement or a suite?"):

参见函数定义。

- robert

---

但是，还没有支持这一点的文档处理器，是吗？似乎sphinx不支持，我也找不到关于doxygen支持的任何信息。 - naught101

三年前，我认为到现在应该已经完成了。 - robert

Answer 4

我想在这里发布这个小贴士，因为IDEA向我展示了这一点，而我从未被告知或读过这个。

>>> def test( arg: bool = False ) -> None: print( arg )

>>> test(10)
10

当你输入test(时，IDLE的文档提示会出现(arg: bool=False) -> None，这是我认为只有Visual Studio才能做到的事情。

虽然这不是doxygen材料，但对于使用你的代码的人来说，它很好地记录了参数类型。

- Tcll

Answer 5

没错，@docu是对的 - 这是将两种文档方案相对无缝地结合起来的（我认为最好的）方法。另一方面，如果您还想在doxygen生成的索引页面上放置文本之类的内容，您可以添加

##
# @mainpage (Sub)Heading for the doxygen-generated index page
# Text that goes right onto the doxygen-generated index page

在你的Python代码的开头某个地方。

换句话说，在doxygen不期望Python注释的地方，使用##来提醒它有标签需要处理。在它期望Python注释的地方（例如在函数或类的开头），使用"""!。

- user147058

Answer 6

Doxygen 很适合 C++，但如果你主要使用 Python 代码的话，你应该尝试一下 sphinx。如果你选择了 sphinx，那么你只需要遵循 pep8 就可以了。

- Tom

---

主要原因是因为该项目已经使用了doxygen，其次，sphinx无法记录参数类型。 - sorin

而且Sphinx不会自动记录代码。它默认情况下无法识别新的函数等内容。您必须显式地添加它们。所有考虑到这一点的Sphinx插件都不能正常工作。 - buhtz