三重单引号和三重双引号的文档字符串有什么区别？

Question

我只是想知道两种编写 Python Docstrings 的方式有什么区别（

__doc__

）：

1. 三个单引号：

   '''
   Comment goes here
   '''  
   

2. 三个双引号：

   """
   Comment goes here
   """
   

在稍后生成文档时，文档字符串的格式化方式是否有任何细微差别？

Answer 1

没有。他们是一样的。唯一的区别是第一个可以包含三个未转义双引号的序列，而第二个可以包含三个未转义单引号的序列。 （换句话说，因为分隔符不同，你可以在其中使用的字符略有不同。）

Docstrings 只是常规字符串，在 Python 中，不同的字符串定界符之间没有区别，当然，你不能在字符串内部使用字符串定界符。

Answer 2

参考文档PEP 257 -- Docstring Conventions建议使用

"""triple double-quotes"""

来保持一致性，并且它们的所有示例都显示相同：

为了保持一致性，始终使用

"""triple double quotes"""

文档字符串。如果您使用任何，请使用

r"""raw triple double quotes"""

文档字符串中的反斜杠。

使用单引号还是双引号只是实践中的文体问题。从这些字符串生成和发布文档时，格式没有区别。

Answer 3

选择你想要的任何风格。就我个人而言，我在 Python 中可以到处使用单引号。

文件声明：

"String literals can be enclosed in matching single quotes (') or double quotes (")."

您决定使用哪一个并不重要。重要的是你坚持你的决定。选择一种风格并坚持下去是一种很好的做法。

Answer 4

在 Python 中，单引号

' '

和双引号

" "

都可以用来将字符串中的字符括起来。

对于常规字符串默认情况下，单引号应该使用，使您的代码与Python文档更加一致。例如：

chr(97)

退货：

'a'

当字符串包含 string literal 时， double quotations 应该被使用。例如

"the str is 'hello'"

.

三重单引号用于多行注释：

text = '''Takes a singular word 
and returns its plural. 
'''

如果多行字符串包含string literal，需要使用三重双引号：

text = """Takes a singular word 
and returns its plural. 
e.g. 'apple' becomes 'apples'.
"""

话虽如此，PEP 257 建议始终使用 三重双引号

""" """

以确保文档字符串的一致性。它推荐使用 三重双引号 的原因，即使它是单行文档字符串，也是为了以后更容易将文档字符串扩展为多行。

同样，因为文档字符串本身更可能包含字符串文字，所以使用 三重双引号 也使得以后更容易扩展。下面的简单示例显示了一行文档字符串：

def plural(word, /):
    assert isinstance(word, str)
    """Takes a singular word and returns its plural."""
    return word + 's'

这可以稍后扩展：

def plural(word, /):
    assert isinstance(word, str)
    """Takes a singular word and returns its plural. 
    e.g. 'apple' becomes 'apples'.
    
    Parameters
    ----------
    word : str
        singular str.
    
    Returns
    -------
    str
        plural str.
    
    """
    return word + 's'

Python 核心开发人员 Raymond Hettinger 认为应该尽可能使用单引号，因为语言本身更喜欢使用单引号。然而，他注意到 Python 社区本身似乎更倾向于使用双引号。

他指出，这可能是由于程序员从 C++ 等语言迁移而来，这些语言对字符

'a'

使用单引号，对字符串

"apples"

使用双引号。我最初是为了数据科学而从 MATLAB 转到 Python，并且出于同样的原因最初也倾向于使用双引号。由于我遵循的大多数数据科学教程也支持双引号，因此这种习惯得到了加强。最好尽可能与 Python 语言本身保持一致，因此我现在遵循 Raymond Hettinger 的建议，对常规字符串使用单引号，对包含字符串文字的字符串使用双引号，对文档字符串使用三重双引号。