Question

我有一个通用格式的文档字符串，我在创建函数时尝试遵循。我总结了函数的功能，然后简要解释了输入所需的类以及它输出的类。

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

    cuberoot4u(float) -> float

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

所以在这种情况下，cuberoot4u为输入获取一个浮点数并返回一个浮点输出。

如果将.txt文件作为输入并以字符串形式输出内容，我怎样才能最好地向用户传达文档字符串函数所需的输入类别？

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 还是有一个特定的类名，就像字符串'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)

显然，仅当float为非负数时，返回类型为number，否则应为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以外还有什么？）

现在有了第三个功能，除了类型和合同外，还有副作用。这些应记录在功能的一般描述中（如果它们是运行此功能的要点），或者在注释/警告中（如果它们只是要记住的话）。例如（再次使用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，这意味着它对其参数执行一些纯操作（即，始终为同一输入返回相同的输出，并且没有副作用）。

为某些python函数传送docstrings

1 个答案: