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

news2024/9/20 6:32:36

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)