为某些python函数传输docstring

Question

我有一个docstring的通用格式，当我创建函数时，我试图遵循这些格式。我对函数的作用做了一个总结，然后简要解释了它需要什么类作为输入，以及它输出什么类。在

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

    cuberoot4u(float) -> float

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

所以在本例中，cuberoot4u为输入获取一个浮点值，并为输出返回一个浮点值。在

如果函数以.txt文件作为输入，并以字符串形式输出内容，那么如何用docstrings向用户传达函数所需的输入类？在

^{pr2}$

最好是说getText(filename.txt) -> str 还是有一个特定的类名，就像string是'str'而整数是'int'？在

同样，对于输出未明确定义的函数，例如：

^{3}$

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

Answer 1

你在抽象中碰到了一个通常被称为的洞。在您的例子中，对于每个指定参数类型的函数来说，抽象就足够了。大多数语言（或者说，所有的语言），尤其是Python，没有一个足够强大的类型系统来实现它。在

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

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

    squareroot4u(float) -> float

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

显然，只有当number非负时，返回类型才是float，否则它应该是complex。Python（与某些面向科学的语言不同）没有单独的非负数类型，因此您必须另外指定一个contract来强制它：

^{pr2}$

我个人使用^{}来记录文档，其格式如下

^{3}$

对于您的第二个功能：

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 docstring中的类型通常在可以从上下文中推导出来时被省略（例如，除了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相反，这意味着它对其参数执行一些纯操作（即，对于相同的输入，总是返回相同的输出，并且没有副作用）。在