Python获取函数文档字符串技巧

欢迎各位小伙伴来到golang学习网，相聚于此都是缘哈哈哈！今天我给大家带来《Python获取函数文档字符串的方法》，这篇文章主要讲到等等知识，如果你对文章相关的知识非常感兴趣或者正在自学，都可以关注我，我会持续更新相关文章！当然，有什么建议也欢迎在评论留言提出！一起学习！

答案是访问函数的__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这种强调可读性的语言里，一个写得好的docstring，简直能省下无数次沟通和调试的时间。它不仅仅是代码的“说明书”，更是代码意图的直接表达。

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

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

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

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

PEP 257 的一些核心建议：

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

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

好了，本文到此结束，带大家了解了《Python获取函数文档字符串技巧》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！