函数定义中带有三引号的字符串文字

Question

我正在关注 Python 教程，有时他们会讨论函数的第一条语句如何成为字符串文字。就示例而言，这个字符串文字似乎是用三个"s 完成的，给出了example

"""Print a Fibonacci series up to n."""

根据本文档，这将主要用于创建某种自动生成的文档。

所以我想知道这里是否有人可以向我解释这些字符串文字到底是什么？

Answer 1

您所说的（我认为）称为docstrings（感谢Boud 提供链接）。

def foo():
    """This function does absolutely nothing"""

现在，如果您从解释器中输入help(foo)，您将看到我在函数中输入的字符串。您也可以通过foo.__doc__访问该字符串

当然，字符串文字就是这样——文字字符串。

a = "This is a string literal"  #the string on the right side is a string literal, "a" is a string variable.

或

foo("I'm passing this string literal to a function")

可以通过多种方式定义它们：

'single quotes'
"double quotes"
""" triple-double quotes """  #This can contain line breaks!

甚至

#This can contain line breaks too!  See?
''' triple-single 
    quotes '''

Answer 2

好吧，看看表达式、文字和字符串的概念会很有帮助。

字符串、表达式和文字

在程序中，我们必须表示各种类型的数据。一种类型数据是整数；另一种类型是浮点数。

可以通过各种方式产生某种类型的值，即通过各种表达式。 表达式 是“创建”一个值的程序的任何 sn-p。例如，在下面的 Python 表达式中，表达式 2+2 产生值 4。赋值运算符 = 将产生的值 4 放入名为 i 的变量中：

i = 2+2

鉴于上面的语句，下面的表达式产生相同的值4，但现在这个表达式只包含一个变量：

i

下面，我们通过一个算术表达式产生一个值，然后通过一个变量（也是一个表达式）产生它。

但是，语言应该提供一种语法来直接产生基本值。例如，上面表达式中的2 检索值2。直接产生基本值的表达式称为literals。两个表达式 2+2 和 4 产生相同的值 4，但第二个表达式是表示操作的非常基本的方式，由语言提供，不需要执行显式操作，所以它是一个字面量。

字符串文字和多行字符串

一种非常重要的数据类型是文本、一系列字母、数字和其他字符。这种类型通常称为string。

字符串文字，以这种方式，是产生字符串的文字。在 Python 中，这些文字通过多种方式标记（即，字符串文字有多种语法）。例如，您可以在文字的开头或结尾放置单引号或双引号：

"A string literal"

'Another string literal'

其他方法是将三个单引号或双引号放在相同的位置。在这种情况下，文字可以跨越多行：

"""A single line string literal"""

"""A multiline
string literal"""

'''Another multiline
string literal'''

请注意，无论您为字符串文字选择何种语法，它都不会改变其值。单引号字符串等于双引号字符串字符相同，三引号字符串等于单引号字符串内容相同：

>>> "A single line string literal" == 'A single-line string literal'
True

>>> """A single line string literal""" == "A single line string literal"
True

>>> # \n is the character that represents a new line
>>> "A multiline\nstring literal" == """A multiline
string literal""" 
True

文档字符串以及为什么它们应该是字符串文字

文档的意思是你可以在方法声明之后放置一个字符串字面量，这个字面量将被用作文档——我们用它来调用 docstring。使用单引号或双引号字符串，或者单引号或三引号字符串都没有关系：它只需要是 literal。

考虑以下函数：

def f1(value):
    "Doc for f1"
    return value + 1

def f2(value):
    """Doc for f2"""
    return value + 2

现在，在 Python 控制台中声明它们并调用 help(f1) 和 help(f2)。请注意，字符串文字的语法无关紧要。

OTOH，您不能使用其他表达式（例如变量或字符串操作）来生成文档。所以下面函数第一行的字符串没有文档字符串：

mydoc = "This is doc"
def f3(value):
     mydoc
     return value+3

 def f4(value):
     "This is no documentation " + "because it is concatenated"
     return value+4

它应该是一个文字，因为编译器是明确编写的来将它作为文档进行管理。但是，编译器不准备将变量、复杂表达式等作为文档进行管理，因此它会忽略它们。换句话说，这是设计使然。

为什么使用三引号字符串作为文档字符串？

尽管文档字符串中可以使用任何形式的字符串文字，但您可能会认为文档通常包含很长的文本，包含多行和多段。好吧，既然它包含很多行，最好使用接受多行的文字形式，对吗？这就是为什么三引号字符串是编写文档字符串的首选（但不是强制性）方式的原因。

旁注

其实你可以在 Python 函数的任何地方放一个字符串字面量：

 def flying_literals(param):
    "Oh, see, a string literal!"
    param += 2
    "Oh, see, ANOTHER string literal!"
    return param
    "the above literal is irrelevant, but this one can be still MORE IRRELEVANT"

但是，只有第一行中的文字会有所不同（作为文档）。其他的是no-ops。

Answer 3

字符串文字只是在源代码中按字面意思给出的字符串。它是文档字符串还是其他字符串都没有关系。有关所有详细信息，请参阅Python language documentation section on string literals，但您现在可能不需要这些详细信息。

几个例子：

"abc"
'Guido'
r"""Norwegian Blue"""

Answer 4

字符串文字是许多引用选项之一中的字符串，它没有分配给变量。

所以，

"String" # string literal
'string' # string literal
"""
  Multiline
  String
  Literal
"""
foo = "string variable"

当您在 def 块之后立即有一个字符串文字时，它成为该方法的文档的一部分，称为 docstring

def foo(hello):
    """This is part of the documentation for foo"""

这是你将如何使用它：

>>> def foo(hello):
...     """This is the docstring"""
...     pass
... 
>>> foo.__doc__
'This is the docstring'

Answer 5

在 Python 中，有几种方法可以将字符串分成多行。字符串字面量就是其中之一，例如：

s = """Hello,
    world"""
print(s)
>>> Hello,
>>>     world #Notice, that spaces used in the literal are kept.

但正如您正确注意到的那样，字符串文字通常用于内联文档

class MyClass(object):
    """This is my class it does this and that.

       It has some cool features and I may tell you about them below.
    """

    def my_method(self):
        """This is a brief description of my method."""

    def important_method(self):
        """Because this method is important, I'm going to tell you
           a lot about it. For example...
        """

在你问之前，一个在多行上分割字符串的好方法是神圣的 Python 括号：

s = ('This is a very very long string. '
     'I have to split it to multiple lines. '
     'Whoa! It works!')
print(s)
>>> This is a very very long string. I have to split it to multiple lines. Whoa! It works!

您可能需要它来遵循 PEP-8，其中规定“每行不得超过 80 个字符”。

祝 Python 破解愉快！

Answer 6

它们是与任何其他字符串一样的字符串，周围有一对'、"、''' 或"""。
推荐的形式是三重双引号：

def some_function(s):
    """this is documentation for some_function"""
    print(s)