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。
文档字符串的最后一行。"""
pass
print(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 = length
self.width = width
def area(self):
"""计算并返回矩形的面积。
返回:
float: 矩形的面积
"""
return self.length * self.width
def 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 math
PI = math.pi
def circle_area(radius):
"""计算圆的面积。
参数:
radius (float): 圆的半径
返回:
float: 圆的面积
"""
return PI * radius ** 2
def 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