Python怎么获取函数的文档字符串（docstring）_函数文档字符串的访问与使用

下次还敢

发布时间：2025-09-17 23:27:01

999人浏览过

来源于php中文网

原创

答案是访问函数的__doc__属性可获取其文档字符串。通过函数.__doc__能直接读取函数定义中的docstring内容，适用于函数、方法、类和模块；结合inspect.getdoc()还可智能处理缩进，提升可读性，是理解代码功能、参数与返回值最直接的方式。

python怎么获取函数的文档字符串（docstring）_函数文档字符串的访问与使用

在Python里，想知道一个函数是干嘛的，或者它需要什么参数、返回什么，最快最直接的办法就是去看看它的文档字符串（docstring）。而要拿到这个docstring，其实很简单，直接访问函数对象的

__doc__

属性就行了。这个属性会直接返回函数定义时，紧接着函数头部的那个字符串字面量。

解决方案

要获取Python函数的文档字符串，核心操作就是访问函数对象的

__doc__

属性。这个属性在函数被定义时就自动关联了其第一个字符串字面量，如果这个字面量是多行字符串，它也会完整地被捕获。

来看一个具体的例子，这样会更清楚：

def calculate_area(length, width):
    """
    计算矩形的面积。

    这个函数接受矩形的长和宽作为参数，并返回它们的乘积。
    这是一个多行文档字符串的示例，展示了详细的描述。

    参数:
        length (float): 矩形的长度，必须是正数。
        width (float): 矩形的宽度，必须是正数。

    返回:
        float: 矩形的面积。如果输入无效，可能返回None或引发错误（此处为简化，仅返回乘积）。

    示例:
        >>> calculate_area(5, 10)
        50.0
    """
    if not isinstance(length, (int, float)) or length <= 0:
        raise ValueError("长度必须是正数。")
    if not isinstance(width, (int, float)) or width <= 0:
        raise ValueError("宽度必须是正数。")
    return length * width

# 获取 calculate_area 函数的文档字符串
function_doc = calculate_area.__doc__
print("--- 函数文档字符串 ---")
print(function_doc)

# 即使是lambda函数，虽然不常见，但如果定义了，也能获取
# 不过通常不建议给lambda写docstring，因为它们通常很简单
# lambda_func = lambda x: x * 2
# print(lambda_func.__doc__) # 这会是None，因为没有显式定义docstring

运行这段代码，你会看到

calculate_area

函数的整个文档字符串被打印出来。这适用于任何函数、方法、类，甚至模块。它们都有一个

__doc__

属性。

立即学习“Python免费学习笔记（深入）”；

为什么我们需要函数文档字符串？提升代码可读性与团队协作效率

我常常觉得，代码注释和文档字符串，就像是给未来的自己或者团队成员写的情书。尤其是在Python这种强调可读性的语言里，一个写得好的docstring，简直能省下无数次沟通和调试的时间。它不仅仅是代码的“说明书”，更是代码意图的直接表达。

从个人开发角度看，当你几个月后回头看自己写的代码，如果没有docstring，你可能得重新“考古”一遍逻辑。而有了它，一眼就能明白函数是干嘛的，需要什么输入，返回什么输出，甚至有哪些潜在的副作用或注意事项。这大大加快了理解和修改的速度。

从团队协作角度讲，docstring更是不可或缺。新成员入职，面对一个庞大的代码库，如果每个关键函数都有清晰的docstring，他们就能更快地上手，理解各个模块的功能边界和使用方式。这比口头讲解或者翻阅外部文档要高效得多，因为文档就“长”在代码旁边，随手可得。此外，许多自动化文档生成工具（比如Sphinx）都是基于docstring来构建项目文档的，这进一步提升了团队的生产力，让文档与代码保持同步。对我而言，docstring就像是代码的“名片”，它向外界清晰地展示了函数的功能和契约，是专业代码不可或缺的一部分。

Docstring的编写规范有哪些？（PEP 257）遵循最佳实践

Python社区对docstring的编写其实有一些约定俗成的规范，最官方的当然是 PEP 257 -- Docstring Conventions。但说实话，实际项目中，团队内部往往会根据自己的偏好形成一套风格，比如Google风格、NumPy风格，或者是reStructuredText格式。不过，无论哪种风格，核心原则都是为了清晰、一致和易于解析。

PEP 257 的一些核心建议：

知鹿匠

知鹿匠教师AI工具，新课标教案_AI课件PPT_作业批改

下载

单行Docstring： 如果docstring内容非常简洁，可以放在一行。开头和结尾的三引号应在同一行。
```
def greet(name):
    """返回一个问候语。"""
    return f"Hello, {name}!"
```

多行Docstring：

第一行是函数的简短摘要，以句号结尾，不重复函数名。
第二行留空，与摘要和后续描述分隔。
之后是更详细的描述，包括参数、返回值、可能引发的异常、使用示例等。
结尾的三引号应单独一行。

def complex_calculation(data, factor=1.0):
    """
    执行一个复杂的数学计算。

    这个函数会对输入数据进行一系列的变换和聚合操作，
    最终返回一个处理后的结果。它特别适用于需要对数据
    进行标准化或归一化的场景。

    参数:
        data (list of float): 待处理的数值列表。
        factor (float, optional): 调整计算结果的乘数。默认为 1.0。

    返回:
        float: 计算后的最终结果。

    Raises:
        ValueError: 如果 `data` 为空列表或包含非数值元素。

    示例:
        >>> complex_calculation([1, 2, 3], factor=2.0)
        12.0
    """
    # ... function logic ...
    pass

常见的Docstring风格：

reStructuredText (reST) 风格： 这是Sphinx等文档工具默认支持的格式，使用特定标记 (
```
:param:
```
,
```
:returns:
```
,
```
:raises:
```
) 来描述参数、返回值和异常。
Google 风格： 使用
```
Args:
```
,
```
Returns:
```
,
```
Raises:
```
等标题来组织内容，可读性强。
NumPy 风格： 类似于Google风格，但在参数、返回等部分使用了更结构化的表格形式，对科学计算库尤其友好。

选择哪种风格，通常取决于项目或团队的偏好。但关键在于保持一致性。一旦选定了一种风格，就应该在整个项目中严格遵守，这样才能最大化docstring的价值，让它们易于阅读、理解和自动化处理。

除了直接访问

__doc__

，还有其他获取和处理Docstring的方式吗？

inspect

模块的妙用

当然，直接用

__doc__

属性是最基础的。但有时候，我们可能需要更高级、更智能的方式来处理这些文档，比如自动去除缩进，或者处理继承关系中的docstring。这时候，Python标准库里的

inspect

模块就派上用场了，它提供了一系列有用的函数来检查活动对象（模块、类、函数、帧、回溯等）。

inspect.getdoc()

就是一个非常实用的函数，它能智能地获取对象的文档字符串，并且会自动处理一些常见的格式问题，比如去除多余的缩进，这对于从源代码中提取的docstring特别有用。

import inspect

def another_function(arg1, arg2):
    """
    这是另一个函数，它的docstring故意有一些不规则的缩进。
        第二行缩进了。
        第三行也缩进了，但可能比第二行少。

    参数:
        arg1 (str): 第一个参数。
        arg2 (int): 第二个参数。
    """
    return f"{arg1} - {arg2}"

class MyClass:
    """
    一个示例类。
    """
    def my_method(self):
        """
        类中的一个方法。
        """
        pass

# 使用 __doc__ 直接获取
raw_doc = another_function.__doc__
print("--- 原始 __doc__ ---")
print(raw_doc)

# 使用 inspect.getdoc() 获取
cleaned_doc = inspect.getdoc(another_function)
print("\n--- inspect.getdoc() 处理后的文档 ---")
print(cleaned_doc)

# 获取类和方法的文档
print("\n--- 类的文档 ---")
print(inspect.getdoc(MyClass))
print("\n--- 方法的文档 ---")
print(inspect.getdoc(MyClass.my_method))

你会发现，

inspect.getdoc()

会把

another_function

文档字符串中不必要的开头缩进给清理掉，让内容看起来更整洁。这对于那些从源文件读取docstring并希望美观展示的工具来说，简直是福音。

除了

inspect

模块，还有一些更宏观的工具和库在处理docstring：

Sphinx： 这是Python项目最常用的文档生成器。它能够解析reStructuredText格式的docstring，并结合其他源文件（如Markdown），生成漂亮的HTML、PDF等格式的文档。它甚至可以通过扩展支持Google或NumPy风格的docstring。
Pydoc： Python自带的模块，可以从模块、类、函数中提取docstring，并在命令行或Web浏览器中显示文档。虽然不如Sphinx功能强大，但对于快速查看文档非常方便。
IDE/编辑器： 很多现代IDE（如PyCharm, VS Code）都会解析docstring，并在你调用函数时提供参数提示和文档预览，这极大地提升了开发效率。

所以，获取docstring不仅仅是