为某些 python 函数传送文档字符串

Question

我有一个通用的文档字符串格式，我在创建函数时会尝试遵循该格式。我总结了该函数的作用，然后简要解释了输入的内容 class 以及输出的内容 class。

def cuberoot4u(number):
    """Returns the cube root of number.

    cuberoot4u(float) -> float

    """
    return pow(number, 1/3)

所以在这种情况下，cuberoot4u 接受一个浮点数作为输入，returns一个浮点数作为输出。

如果函数将 .txt 文件作为输入并以字符串形式输出内容，我如何才能最好地向用户传达 class 函数需要什么输入？

def getText(filename):
    """Reads the file filename and returns the content.

    getText(?????) -> str
    """
    fd = open(filename)
    text = fd.read()
    fd.close()
    return text

最好是说 getText(filename.txt) -> str 还是有一个特定的 class 名称，就像字符串是 'str' 而整数是 'int'？

此外，对于输出没有像这个例子那样明确定义的函数呢：

def commandmenu():
    """Begin some random menu which does stuff.

    commandmenu() -> ??????
    """


    while 1:
        someuserinput = input("Enter a command: ")
        if someuserinput == 'this':
            pass
        elif someuserinput == 'that':
            pass
        else:
            print('u suck')
    return None

所以在这种情况下，进入该函数没有初始输出，因为它会导致用户在执行某些操作之前进行输入。什么最适合？？？？？如果这样的功能变得越来越细致，可能会根据对用户的提示等导致多种不同的输出？

Answer 1

您遇到了通常所说的抽象中的漏洞。在您的情况下，抽象是每个指定参数类型的函数都足以记录它。大多数语言（或者，也许是所有语言），尤其是 Python 没有足够强大的类型系统来实现它。

考虑一个类似于您的第一个函数，但计算平方根的函数：

def squareroot4u(number):
    """Returns the cube root of number.

    squareroot4u(float) -> float

    """
    return pow(number, 1/2)

显然，return类型只有在number为非负的情况下才是float，否则应该是complex。 Python（与一些面向科学的语言不同）没有非负数的单独类型，因此您必须另外指定一个强制执行它的 contract：

def squareroot4u(number):
    """Returns the cube root of number.

    squareroot4u(number: float) -> float

    precondition: number >= 0
    raises ValueError otherwise
    """
    return pow(number, 1/2)

我个人使用 Sphinx 来记录，其格式看起来像

def squareroot4u(number):
    """Returns the cube root of number.

    :param number: a non-negative number, raises ``ValueError`` otherwise
    :type number: ``float``
    :return: square root of the input
    :rtype: ``float``
    """
    return pow(number, 1/2)

你的第二个函数：

def getText(filename):
    """Reads the file filename and returns the content.

    :param filename: a path to a text file 
                     (raises ``WhateverError``/blows ups the monitor otherwise)
    :type filename: ``str``
    :returns: file contents
    :rtype: ``str``
    """

请注意，Python 文档字符串中的类型在可以从上下文中推断出来时通常会被省略（例如，除了 str 之外，filename 还能是什么？）

现在有了第三个功能，除了类型和契约之外，您还有 副作用。这些应该记录在函数的一般描述中（如果它们是运行这个函数的要点），或者在 note/warning 中（如果它们只是要记住的东西） .例如（再次使用 Sphinx 语法）：

def commandmenu():
    """Begin some random menu which does stuff.
    Shows an input prompt and awaits user input.

    .. warning::

        May or may not randomly format your hard drive during full moon.
    """

在其他语言中（例如，Haskell），一些副作用可以表示为类型（monad）并进行静态检查。例如，标准库中有一个与您的 getText 类似的函数，其类型为

readFile :: FilePath -> IO String

而不是仅 String，这意味着它对其参数执行一些纯操作（即，始终 return 对相同的输入具有相同的输出并且没有边影响）。

为某些 python 函数传送文档字符串

Conveying docstrings for certain python functions

python

docstring