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

在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 的一些核心建议：

1. 单行Docstring： 如果docstring内容非常简洁，可以放在一行。开头和结尾的三引号应在同一行。

   

   白瓜AI

   白瓜AI，一个免费图文AI创作工具，支持 AI 仿写，图文生成，敏感词检测，图片去水印等等。

   131

   查看详情

   def greet(name):     """返回一个问候语。"""     return f"Hello, {name}!"

2. 多行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不仅仅是

__doc__

那么简单，它背后是一个完整的生态系统，旨在让代码自文档化，让开发者和用户都能更容易地理解和使用代码。对我来说，掌握这些工具，是提高开发效率和代码质量的关键一步。