当前位置：首页 > news >正文

Python中docstring用法详解

news 2025/10/1 22:05:51

在Python中，docstring（文档字符串）是用来为模块、类、方法、函数等提供文档的一种方式。它是一个字符串字面量，出现在模块、类、函数或方法的定义的第一条语句。通过使用docstring，我们可以为代码添加描述性的文档，这些文档可以通过内置的help()函数或者各种文档生成工具（如Sphinx）来查看。

下面是一个简单的例子，展示如何在函数中使用docstring：

def add(a, b):"""计算两个数的和参数:a (int): 第一个加数b (int): 第二个加数返回:int: 两个加数的和"""return a + b

然后，我们可以通过以下方式查看这个函数的文档：

使用help()函数：在Python交互环境中，输入help(add)，就会显示这个函数的文档字符串。
使用__doc__属性：直接打印add.doc，也会输出同样的文档字符串。

例如：

print(help(add))
# 或者
print(add.__doc__)

docstring的格式可以有很多种，常见的包括纯文本、reStructuredText（reST）和Google风格等。上面例子中使用的是比较常见的格式，类似于Google风格。

使用docstring的好处是：

代码和文档在一起，容易维护。
可以通过工具自动生成文档。
方便其他开发者理解你的代码。

在编写大型项目时，良好的docstring是非常重要的。

在Python中，docstring（文档字符串）是一种特殊的字符串，用于为模块、函数、类和方法提供文档说明。它位于定义的第一行，用三个双引号 """ 或三个单引号 ''' 包裹。

基本用法

1. 函数文档字符串

def add(a, b):"""计算两个数的和参数:a (int): 第一个数字b (int): 第二个数字返回:int: 两个数字的和示例:>>> add(2, 3)5>>> add(-1, 1)0"""return a + b

2. 类文档字符串

class Calculator:"""一个简单的计算器类属性:brand (str): 计算器品牌方法:add: 加法运算subtract: 减法运算"""def __init__(self, brand):self.brand = branddef multiply(self, a, b):"""返回两个数的乘积"""return a * b

查看文档字符串

1. 使用 `help()` 函数

help(add)
# 或者
help(Calculator)

2. 使用 `doc` 属性

print(add.__doc__)
print(Calculator.__doc__)

3. 在交互式环境中

# 在IPython或Jupyter中
add?
# 或者
add??

常见的文档字符串格式

1. Google风格

def calculate_area(radius):"""计算圆的面积Args:radius (float): 圆的半径Returns:float: 圆的面积Raises:ValueError: 当半径为负数时Example:>>> calculate_area(5)78.53981633974483"""if radius < 0:raise ValueError("半径不能为负数")return 3.141592653589793 * radius ** 2

2. NumPy风格

def calculate_area(radius):"""计算圆的面积Parameters----------radius : float圆的半径Returns-------float圆的面积Examples-------->>> calculate_area(5)78.53981633974483"""return 3.141592653589793 * radius ** 2

模块级别的文档字符串

"""
math_utils.py这个模块提供了一些数学工具函数。包含的功能:
- 基本算术运算
- 几何计算
- 统计函数作者: Your Name
版本: 1.0
"""def average(numbers):"""计算数字列表的平均值"""return sum(numbers) / len(numbers)

实际示例

class BankAccount:"""银行账户类属性:account_holder (str): 账户持有人姓名balance (float): 账户余额account_number (str): 账户号码方法:deposit: 存款withdraw: 取款get_balance: 查询余额"""def __init__(self, account_holder, initial_balance=0):"""初始化银行账户Args:account_holder (str): 账户持有人姓名initial_balance (float, optional): 初始余额，默认为0"""self.account_holder = account_holderself.balance = initial_balanceself.account_number = self._generate_account_number()def deposit(self, amount):"""存款操作Args:amount (float): 存款金额Returns:float: 更新后的余额Raises:ValueError: 当存款金额为负数时"""if amount <= 0:raise ValueError("存款金额必须为正数")self.balance += amountreturn self.balancedef withdraw(self, amount):"""取款操作Args:amount (float): 取款金额Returns:float: 更新后的余额Raises:ValueError: 当取款金额为负数或超过余额时"""if amount <= 0:raise ValueError("取款金额必须为正数")if amount > self.balance:raise ValueError("余额不足")self.balance -= amountreturn self.balance# 使用帮助文档
help(BankAccount)
help(BankAccount.deposit)