Python中的多行字符串和文档字符串

Python中的多行字符串和文档字符串

Python中，多行字符串和文档字符串都使用三引号（""" 或 '''）来定义。都可以跨越多行而不需要使用行连接符（\）。

多行字符串和文档字符串都可以利用转义符来调整格式——可以包含制表符（\t）等特殊字符。

文档字符串是多行字符串的一种特殊用法。

多行字符串（Multi-line String）

多行字符串（Multi-line String）官方称为三引号字符串（Triple-quoted string）。多行字符串是指在代码中创建的跨越多行（spanning multiple lines）的字符串。Python 中，多行字符串通常使用三引号（""" 或 '''）来包围。这样，你可以在字符串内部自由地使用换行符和其他字符，而不需要在每一行的末尾添加特殊字符（例如 \）。

示例：

multi_line_str = """这是一个多行字符串。

它可以跨越多行，

而且每一行都可以自动换行。"""

在上面的示例中，multi_line_str 是一个多行字符串，包含了多行文本。

文档字符串（Docstring）

文档字符串（Docstring）是 Python 中用于编写模块、类、方法或函数说明的一种特殊的多行字符串。文档字符串紧跟在模块、类、方法或函数的定义之后，用来描述其用途、参数、返回值等信息。文档字符串通常使用三引号（"""）表示，并且能够被 Python 内置的帮助系统（如 help() 函数）读取。

示例：

def add(a, b):"""这是一个加法函数。参数:a -- 第一个数b -- 第二个数返回:两个数的和"""return a + b

在这个例子中，add 函数的文档字符串描述了函数的用途、参数和返回值。你可以通过 add.__doc__ 或 help(add) 来查看这个文档字符串的内容。

不同点：

a.用途：

多行字符串：主要用于表示普通的多行文本数据，可以赋值给变量。

文档字符串：专门用于为模块、函数、类或方法提供文档。

b.位置：

多行字符串：可以在代码中的任何地方使用。

文档字符串：通常位于模块、函数、类或方法定义的开始处（约定开始处）。

c.解释器处理：

多行字符串：被视为普通字符串。

文档字符串：被Python解释器特殊处理，存储在对象的__doc__属性中。

d.访问方式：

多行字符串：像普通变量一样访问。

文档字符串：可以通过__doc__属性或help()函数访问（如果文档字符串为空，则 __doc__ 属性返回 None）。且许多文档生成工具（如pdoc）会自动提取这些文档字符串来生成文档。

文档字符串中的转义符（例如\t等）与在字符串中的处理方式相同。

\t：制表符，插入一个水平制表符。

\u263A：Unicode字符☺。

多行字符串示例

multi_line_str = """这是第一行。
这是第二行，这里有一个\t制表符和\u263A。
这是第三行。"""
print(multi_line_str)

输出显示：

这是第一行。
这是第二行，这里有一个    制表符和☺。
这是第三行。

参见图示：

文档字符串示例

def example_function():"""这是一个文档字符串示例。
在这行文本中，这里有一个\t制表符\u263A。
文档字符串的最后一行。"""passprint(example_function.__doc__)

输出显示：

这是一个文档字符串示例。
在这行文本中，这里有一个    制表符和☺。
文档字符串的最后一行。

 

参见图示：

附、Python中的文档字符串(Docstrings)详解

 在Python中，文档字符串（Docstrings）是用三引号（""" 或 '''）定义的特殊字符串，用于为模块、类、方法或函数提供说明性文本。

定义：

文档字符串是出现在模块、函数、类或方法定义开头的字符串。它们用三重引号("""或''')包围。

注意，在开头，这是一个约定。Python解释器期望在这个位置找到文档字符串。

用途：

提供代码的说明和使用方法

可以通过内置的help()函数或对象的__doc__属性访问

用于自动生成文档

函数文档字符串例子：

def calculate_area(length, width):"""计算矩形面积。参数:length (float): 矩形的长度width (float): 矩形的宽度返回:float: 矩形的面积"""
return length * width

访问文档字符串:

print(calculate_area.__doc__)

help(calculate_area)

类中的文档字符串例子：

class Rectangle:"""表示矩形的类。这个类用于创建和操作矩形对象。它提供了计算面积和周长的方法，以及修改矩形尺寸的能力。属性:length (float): 矩形的长度width (float): 矩形的宽度方法:area(): 计算矩形的面积perimeter(): 计算矩形的周长"""def __init__(self, length, width):"""初始化矩形实例。参数:length (float): 矩形的长度width (float): 矩形的宽度"""self.length = lengthself.width = widthdef area(self):"""计算并返回矩形的面积。返回:float: 矩形的面积"""return self.length * self.widthdef perimeter(self):"""计算并返回矩形的周长。返回:float: 矩形的周长"""return 2 * (self.length + self.width)

访问词例子的文档字符串

1.使用 __doc__ 属性:

# 查看类的文档字符串

print(Rectangle.__doc__)

# 查看方法的文档字符串

print(Rectangle.area.__doc__)

print(Rectangle.perimeter.__doc__)

2.使用 help() 函数:

# 查看整个类的帮助信息，包括所有方法的文档字符串

help(Rectangle)

# 查看特定方法的帮助信息

help(Rectangle.area)

help(Rectangle.perimeter)

3. 创建实例并查看:

rect = Rectangle(5, 3)

print(rect.__doc__)  # 这会显示类的文档字符串

print(rect.area.__doc__)  # 这会显示area方法的文档字符串

另外，许多现代IDE（如PyCharm、VS Code）允许你将鼠标悬停在类或方法名上，就能看到其文档字符串。

模块的文档字符串例子：

一个名为 geometry.py 的简单模块，其中包含一些基本的几何计算函数。文件内容如：

"""几何计算模块这个模块提供了一些基本的几何计算函数，包括圆和矩形的面积计算。函数:circle_area(radius): 计算圆的面积rectangle_area(length, width): 计算矩形的面积常量:PI: 圆周率的近似值示例:>>> import geometry>>> geometry.circle_area(5)78.53981633974483>>> geometry.rectangle_area(4, 5)20
"""import mathPI = math.pidef circle_area(radius):"""计算圆的面积。参数:radius (float): 圆的半径返回:float: 圆的面积"""return PI * radius ** 2def rectangle_area(length, width):"""计算矩形的面积。参数:length (float): 矩形的长度width (float): 矩形的宽度返回:float: 矩形的面积"""return length * width

访问这个模块的文档字符串：

1.使用 __doc__ 属性:

import geometry

# 打印模块的文档字符串

print(geometry.__doc__)

# 打印特定函数的文档字符串

print(geometry.circle_area.__doc__)

print(geometry.rectangle_area.__doc__)

2.使用 help() 函数:

import geometry

# 显示整个模块的帮助信息

help(geometry)

# 显示特定函数的帮助信息

help(geometry.circle_area)

help(geometry.rectangle_area)

3.在交互式环境中:

如果你在 Python 的交互式环境中（如 IDLE 的shell中），你可以直接输入：

import geometry

geometry

这会显示模块的文档字符串。

官方有关资料

https://docs.python.org/zh-cn/3/tutorial/introduction.html#text

https://docs.python.org/zh-cn/3/library/stdtypes.html#textseq

https://docs.python.org/zh-cn/3/tutorial/controlflow.html#documentation-strings

https://peps.python.org/pep-0257/