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__?属性的功能。

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