Python 内置类属性 `__doc__` 属性的使用教程

---

概要

在 Python 中，有许多内置的类属性可以更好地理解和操作类。其中之一是 __doc__ 属性，它用于存储类的文档字符串（docstring）。文档字符串是一种用于描述类、函数、模块或方法的字符串，通常位于定义的顶部，并用于提供有关其功能和用法的信息。在本教程中，将详细介绍 __doc__ 属性的使用方法，并提供丰富的示例代码，帮助大家充分利用这一功能。

---

什么是文档字符串（docstring）？

文档字符串，通常称为 docstring，是一个字符串文字，用于描述函数、类、模块或方法的用途、参数、返回值和其他相关信息。Python 鼓励程序员编写清晰和详细的文档字符串，以便其他人能够理解和使用代码。

文档字符串通常被包含在三引号（''' 或 """）中，并位于定义的顶部，如下所示：

def add(a, b):
    """
    This function adds two numbers and returns the result.

    Parameters:
        a (int): The first number.
        b (int): The second number.

    Returns:
        int: The sum of the two numbers.
    """
    return a + b

文档字符串通常包括以下部分：

• 描述函数或类的目的和功能。

• 参数列表，包括参数的名称、类型和说明。

• 返回值说明，包括返回值的类型和含义。

• 可选的示例和用法说明。

文档字符串的主要目标是提供足够的信息，以便其他开发者能够理解代码的作用和使用方式。

__doc__ 属性的作用

Python 中的每个对象（包括模块、类、函数等）都有一个名为 __doc__ 的属性，该属性存储着对象的文档字符串。通过访问 __doc__ 属性，可以在运行时获取文档字符串，从而提供更多的上下文信息和帮助。

__doc__ 属性的主要作用包括：

• 提供有关对象的详细描述。

• 帮助其他开发者了解对象的用途和参数。

• 作为自动生成文档的一部分。

使用 __doc__ 属性访问文档字符串

要访问对象的文档字符串，只需使用对象的名称后跟 .__doc__ 即可。以下是几种常见的用法：

1. 访问函数的文档字符串

def add(a, b):
    """
    This function adds two numbers and returns the result.

    Parameters:
        a (int): The first number.
        b (int): The second number.

    Returns:
        int: The sum of the two numbers.
    """
    return a + b

# 访问函数的文档字符串
print(add.__doc__)

输出结果将是函数 add 的文档字符串：

This function adds two numbers and returns the result.

Parameters:
    a (int): The first number.
    b (int): The second number.

Returns:
    int: The sum of the two numbers.

2. 访问类的文档字符串

class Person:
    """
    This class represents a person with a name and age.
    """

    def __init__(self, name, age):
        self.name = name
        self.age = age

# 访问类的文档字符串
print(Person.__doc__)

输出结果将是类 Person 的文档字符串：

This class represents a person with a name and age.

3. 访问模块的文档字符串

# mymodule.py

"""
This is a sample module that demonstrates the use of __doc__.
"""

def my_function():
    """
    This function does something interesting.
    """
    pass

# 在另一个 Python 脚本中访问模块的文档字符串
import mymodule

print(mymodule.__doc__)

输出结果将是模块 mymodule 的文档字符串：

This is a sample module that demonstrates the use of __doc__.

编写规范的文档字符串

在编写文档字符串时，建议遵循以下几项规范：

1. 使用三引号：文档字符串应该包含在三引号中，以便跨多行。

2. 描述清晰：文档字符串应该清晰、简洁地描述对象的目的和功能。

3. 参数说明：如果对象接受参数，应该在文档字符串中提供参数的名称、类型和含义。

4. 返回值说明：如果对象返回值，应该在文档字符串中说明返回值的类型和含义。

5. 示例和用法：在文档字符串中提供示例和用法说明，帮助其他开发者理解如何使用对象。

使用 __doc__ 属性的案例

以下是一个示例，演示了如何编写规范的文档字符串，并使用 __doc__ 属性访问和显示文档字符串的内容。

class Calculator:
    """
    This class represents a simple calculator.

    It can perform basic arithmetic operations such as addition, subtraction,
    multiplication, and division.

    Attributes:
        name (str): The name of the calculator.
    """

    def __init__(self, name):
        """
        Initialize a new calculator with a given name.

        Args:
            name (str): The name to assign to the calculator.
        """
        self.name = name

    def add(self, a, b):
        """
        Add two numbers and return the result.

        Args:
            a (int or float): The first number.
            b (int or float): The second number.

        Returns:
            int or float: The sum of the two numbers.
        """
        return a + b

    def subtract(self, a, b):
        """
        Subtract the second number from the first and return the result.

        Args:
            a (int or float): The first number.
            b (int or float): The second number.

        Returns:
            int or float: The result of subtraction.
        """
        return a - b

# 创建一个 Calculator 实例
calc = Calculator("My Calculator")

# 访问类的文档字符串
print(calc.__doc__)

# 访问 add 方法的文档字符串
print(calc.add.__doc__)

# 访问 subtract 方法的文档字符串
print(calc.subtract.__doc__)

输出结果将包括类、方法和属性的文档字符串内容。

总结

__doc__ 属性是 Python 中的一个强大工具，可用于访问和显示对象的文档字符串。通过编写规范的文档字符串，可以提供有关代码的重要信息，并使其更易于理解和维护。请在编写 Python 代码时积极使用 __doc__ 属性，以便更好地协作和共享您的代码。希望本教程能帮助大家更好地理解并利用 __doc__ 属性的功能。

如果你觉得文章还不错，请大家 点赞、分享、留言 下，因为这将是我持续输出更多优质文章的最强动力！