Python文档字符串指南

___波子 Pro Max.2025-12-01 12:33

Python 文档字符串使用说明

文档字符串（Docstring）是Python中用于为模块、类、函数和方法提供文档的标准方式。它们被放在定义的首行，用三引号包围。

基本语法

python 复制代码 
def function_name(parameters):
    """这里是文档字符串"""
    # 函数体
    pass

文档字符串的几种风格

1. 单行文档字符串

python 复制代码 
def add(a, b):
    """返回两个数字的和。"""
    return a + b

def greet(name):
    """向指定的人打招呼。"""
    return f"Hello, {name}!"

2. 多行文档字符串

python 复制代码 
def calculate_area(radius):
    """
    计算圆的面积。
    
    参数:
        radius (float): 圆的半径
        
    返回:
        float: 圆的面积
    """
    return 3.14159 * radius ** 2

常用的文档字符串格式

1. Google 风格

python 复制代码 
def fibonacci(n):
    """
    计算斐波那契数列的第n项。
    
    Args:
        n (int): 要计算的斐波那契数列项数
        
    Returns:
        int: 斐波那契数列的第n项
        
    Raises:
        ValueError: 如果n小于0
        
    Examples:
        >>> fibonacci(5)
        5
        >>> fibonacci(10)
        55
    """
    if n < 0:
        raise ValueError("n必须是非负整数")
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

2. NumPy/SciPy 风格

python 复制代码 
def linear_regression(x, y):
    """
    执行简单线性回归。
    
    Parameters
    ----------
    x : array_like
        自变量数据
    y : array_like
        因变量数据
        
    Returns
    -------
    slope : float
        回归线斜率
    intercept : float
        回归线截距
    r_squared : float
        决定系数R²
        
    Notes
    -----
    使用最小二乘法计算线性回归参数。
    
    Examples
    --------
    >>> x = [1, 2, 3, 4, 5]
    >>> y = [2, 4, 5, 4, 5]
    >>> slope, intercept, r2 = linear_regression(x, y)
    """
    # 实现代码...
    pass

3. Sphinx 风格

python 复制代码 
def process_data(data, method='average'):
    """
    处理数据集的函数。
    
    :param data: 输入的数据列表
    :type data: list
    :param method: 处理方法，可选 'average', 'sum', 'max'
    :type method: str
    :return: 处理后的结果
    :rtype: float
    :raises ValueError: 当数据为空或方法不支持时
    """
    if not data:
        raise ValueError("数据不能为空")
    
    if method == 'average':
        return sum(data) / len(data)
    elif method == 'sum':
        return sum(data)
    elif method == 'max':
        return max(data)
    else:
        raise ValueError(f"不支持的方法: {method}")

类和模块的文档字符串

类的文档字符串

python 复制代码 
class BankAccount:
    """
    银行账户类，用于管理个人银行账户。
    
    Attributes:
        account_number (str): 账户号码
        balance (float): 账户余额
        owner (str): 账户持有人姓名
    """
    
    def __init__(self, account_number, owner, initial_balance=0):
        """
        初始化银行账户。
        
        Args:
            account_number (str): 账户号码
            owner (str): 账户持有人
            initial_balance (float): 初始余额，默认为0
        """
        self.account_number = account_number
        self.owner = owner
        self.balance = initial_balance
    
    def deposit(self, amount):
        """
        存款操作。
        
        Args:
            amount (float): 存款金额
            
        Returns:
            float: 更新后的余额
        """
        if amount <= 0:
            raise ValueError("存款金额必须大于0")
        self.balance += amount
        return self.balance

模块的文档字符串

python 复制代码 
"""
数学工具模块

这个模块提供各种数学计算工具函数，包括：
- 基本数学运算
- 统计分析
- 几何计算

作者: John Doe
版本: 1.0
日期: 2024-01-01
"""

import math

# 模块内容...

访问文档字符串

python 复制代码 
# 查看文档字符串
print(add.__doc__)
help(add)

# 在交互式环境中
# >>> help(calculate_area)
# >>> print(fibonacci.__doc__)

最佳实践

  1. 始终为公共模块、函数、类和方法编写文档字符串
  2. 保持文档字符串简洁但信息完整
  3. 使用一致的格式风格
  4. 包含示例代码
  5. 及时更新文档字符串

完整的示例

python 复制代码 
"""
数据分析工具包

提供数据清洗、转换和分析的基本功能。
"""

def normalize_data(data, method='minmax'):
    """
    数据归一化函数。
    
    将数据缩放到特定范围内，常用于机器学习预处理。
    
    Args:
        data (list or array): 输入数据
        method (str): 归一化方法，可选 'minmax' 或 'zscore'
        
    Returns:
        list: 归一化后的数据
        
    Raises:
        ValueError: 当数据为空或方法不支持时
        
    Examples:
        >>> data = [1, 2, 3, 4, 5]
        >>> normalize_data(data)
        [0.0, 0.25, 0.5, 0.75, 1.0]
        >>> normalize_data(data, 'zscore')
        [-1.26491106, -0.63245553, 0.0, 0.63245553, 1.26491106]
    """
    if not data:
        raise ValueError("数据不能为空")
    
    if method == 'minmax':
        min_val = min(data)
        max_val = max(data)
        return [(x - min_val) / (max_val - min_val) for x in data]
    elif method == 'zscore':
        mean_val = sum(data) / len(data)
        std_val = (sum((x - mean_val) ** 2 for x in data) / len(data)) ** 0.5
        return [(x - mean_val) / std_val for x in data]
    else:
        raise ValueError(f"不支持的归一化方法: {method}")

文档字符串是Python编程中非常重要的部分，它们不仅帮助他人理解你的代码，也帮助未来的你回忆代码的功能。

在终端中获取Python文档字符串的几种方法

有多种方式可以在终端中查看Python代码的文档字符串，下面介绍几种常用的方法：

1. 使用 help() 函数

在Python交互式环境中使用：

bash 复制代码 
python3
python 复制代码 
# 导入你的模块
import your_module

# 查看模块的文档字符串
help(your_module)

# 查看特定函数的文档字符串
help(your_module.your_function)

# 查看类的文档字符串
help(your_module.YourClass)

# 查看类方法的文档字符串
help(your_module.YourClass.method_name)

示例：

python 复制代码 
>>> import math
>>> help(math.sqrt)
Help on built-in function sqrt in module math:

sqrt(x, /)
    Return the square root of x.

2. 使用 .__doc__ 属性

bash 复制代码 
python3 -c "import your_module; print(your_module.your_function.__doc__)"

示例：

bash 复制代码 
# 查看math.sqrt的文档字符串
python3 -c "import math; print(math.sqrt.__doc__)"

# 查看整个模块的文档字符串
python3 -c "import math; print(math.__doc__)"

3. 使用 pydoc 命令

查看模块文档：

bash 复制代码 
# 查看已安装模块
pydoc math

# 查看当前目录下的模块
pydoc your_module

# 搜索模块
pydoc -k keyword

启动文档服务器：

bash 复制代码 
# 启动本地文档服务器
pydoc -p 8080
# 然后在浏览器访问 http://localhost:8080

生成HTML文档：

bash 复制代码 
# 为模块生成HTML文档
pydoc -w your_module

4. 使用 inspect 模块

bash 复制代码 
python3 -c "
import inspect
import your_module

# 获取函数的文档字符串
print(inspect.getdoc(your_module.your_function))

# 获取源码和文档
print(inspect.getsource(your_module.your_function))
"

5. 使用IPython（推荐）

如果你安装了IPython，它提供了更友好的文档查看方式：

bash 复制代码 
# 安装IPython
pip install ipython

# 启动IPython
ipython

在IPython中：

python 复制代码 
# 导入模块
import your_module

# 查看文档 - 在函数名后加问号
your_module.your_function?

# 查看源码 - 在函数名后加两个问号
your_module.your_function??

# 使用help函数
help(your_module.your_function)

实际示例

假设你有一个 calculator.py 文件：

python 复制代码 
"""
简单的计算器模块

提供基本的数学运算功能。
"""

def add(a, b):
    """
    返回两个数字的和。
    
    Args:
        a (int/float): 第一个数字
        b (int/float): 第二个数字
        
    Returns:
        int/float: 两个数字的和
        
    Example:
        >>> add(2, 3)
        5
    """
    return a + b

class Calculator:
    """简单的计算器类。"""
    
    def multiply(self, a, b):
        """返回两个数字的乘积。"""
        return a * b

在终端中查看文档：

方法1：使用Python交互环境

bash 复制代码 
python3
python 复制代码 
>>> import calculator
>>> help(calculator.add)
>>> print(calculator.add.__doc__)
>>> help(calculator.Calculator.multiply)

方法2：使用一行命令

bash 复制代码 
# 查看add函数的文档
python3 -c "import calculator; print(calculator.add.__doc__)"

# 查看整个模块的文档
python3 -c "import calculator; help(calculator)"

方法3：使用pydoc

bash 复制代码 
# 查看模块文档
pydoc calculator

# 查看特定函数（需要指定完整路径）
pydoc calculator.add

方法4：使用IPython（最佳体验）

bash 复制代码 
ipython
python 复制代码 
In [1]: import calculator

In [2]: calculator.add?        # 查看文档
In [3]: calculator.add??       # 查看源码和文档
In [4]: help(calculator.add)   # 详细帮助

小贴士

  1. 对于本地开发，推荐使用IPython，因为它提供最好的阅读体验
  2. 对于快速查看 ，使用 python3 -c "print(func.__doc__)" 最方便
  3. 对于完整文档浏览 ，使用 pydoc -p 8080 启动本地文档服务器
  4. 确保你的Python路径正确，这样才能找到你的模块

选择最适合你需求的方法来查看文档字符串吧！

复制代码 
我们遇到的问题是：在终端中直接运行Python，然后尝试导入一个模块（名为flash），但是提示找不到该模块。
这是因为模块不在Python的搜索路径中。

解决方法有几种：

将模块所在的目录添加到sys.path中。

设置环境变量PYTHONPATH，包含模块所在的目录。

在代码中使用相对导入（如果是在包内的话）。

根据你的终端路径，你当前在 /Users/junbozheng/xiaomi/miwear/build 目录下，那么你的flash模块可能在这个目录的某个子目录中，或者在其他位置。

假设flash模块就在当前目录下，你可以这样做：

方法1：在Python交互环境中动态添加路径

import sys
sys.path.append('/Users/junbozheng/xiaomi/miwear/build')
import flash

方法2：在启动Python之前，设置环境变量（在终端中执行）
export PYTHONPATH="/Users/junbozheng/xiaomi/miwear/build:$PYTHONPATH"
然后再启动Python并导入

方法3：如果flash是一个包，并且你有__init__.py文件，那么你可以确保当前目录在sys.path中，因为Python会自动将当前目录加入sys.path。但是注意，你启动Python的目录必须是flash模块所在目录的父目录。

但是，从你提供的路径来看，你是在build目录下启动的Python，那么如果flash模块在build目录下，那么应该可以直接导入。如果不在，那么你需要将flash模块所在的路径添加到sys.path。

另外，你看到的错误是"No module named 'flash'"，所以首先确认一下flash模块是否在build目录下，或者是否在Python可以找到的路径。

步骤：

在终端中，先确认flash模块的位置。例如，使用find命令：find /Users/junbozheng/xiaomi/miwear/build -name "flash.py" 或者查找包含__init__.py的flash目录。

如果flash模块在别的路径，比如在/Users/junbozheng/xiaomi/miwear/src/flash，那么你需要将这个路径添加到sys.path。

例如，如果flash模块在/Users/junbozheng/xiaomi/miwear/src/flash，那么你可以：

import sys
sys.path.append('/Users/junbozheng/xiaomi/miwear/src')
import flash

或者，你可以使用相对路径，如果你知道当前目录到flash模块的相对路径。

另外，如果你是在开发一个包，建议使用可编辑安装（使用pip install -e .）这样可以将包添加到Python的路径中。

现在，根据你的情况，你可以在Python交互环境中尝试以下步骤：

import sys
sys.path.append('/Users/junbozheng/xiaomi/miwear/build') # 或者实际包含flash模块的目录
import flash

如果还是不行，请检查flash模块的目录结构，确保它是一个有效的Python模块（包含__init__.py，如果是包的话）。

如果flash是一个文件（flash.py），那么确保它所在的目录在sys.path中。

如果以上都不行，请提供flash模块的具体位置。

你遇到了Python路径问题。这是因为Python在系统路径中找不到你的 flash 模块。有几种方法可以解决：

方法1：直接运行Python文件（推荐）

如果你的 flash.py 文件在当前目录：

bash 复制代码 
# 直接运行Python文件
python flash.py

# 或者在Python中直接执行
python -c "exec(open('flash.py').read())"

方法2：添加当前目录到Python路径

bash 复制代码 
# 启动Python时添加当前路径
PYTHONPATH=. python

# 或者在Python交互环境中添加
python
>>> import sys
>>> sys.path.append('.')  # 添加当前目录到路径
>>> import flash

方法3：使用相对导入

如果你的 flash.py 文件在当前目录，可以这样导入：

bash 复制代码 
python
>>> import sys
>>> sys.path.insert(0, '.')  # 确保当前目录在路径最前面
>>> import flash

方法4：使用模块方式运行

bash 复制代码 
# 如果flash.py在当前目录
python -m flash

# 注意：这需要flash.py中有可执行的__main__部分

方法5：使用绝对路径导入

bash 复制代码 
python
>>> import sys
>>> sys.path.append('/Users/junbozheng/xiaomi/miwear/build')
>>> import flash

实际演示

假设你的目录结构是这样的：

复制代码 
/Users/junbozheng/xiaomi/miwear/build/
├── flash.py
└── 其他文件...

在终端中操作：

bash 复制代码 
# 1. 确保你在正确的目录
cd /Users/junbozheng/xiaomi/miwear/build

# 2. 启动Python并添加当前路径
python
python 复制代码 
# 在Python交互环境中
>>> import sys
>>> sys.path.insert(0, '.')  # 添加当前目录
>>> import flash  # 现在应该可以导入了

# 查看文档字符串
>>> help(flash)
>>> print(flash.your_function.__doc__)

更简单的方法：使用IPython

bash 复制代码 
# 安装IPython（如果还没有）
pip install ipython

# 在build目录下启动IPython
cd /Users/junbozheng/xiaomi/miwear/build
ipython

在IPython中会自动处理当前路径，通常可以直接导入：

python 复制代码 
In [1]: import flash  # 应该可以直接工作

In [2]: flash?        # 查看模块文档
In [3]: flash.your_function?  # 查看函数文档

如果你想要更持久的解决方案

创建一个 .pythonrc 文件或修改你的Python配置文件，自动添加常用路径：

bash 复制代码 
# 在 ~/.bashrc 或 ~/.zshrc 中添加
export PYTHONPATH="${PYTHONPATH}:/Users/junbozheng/xiaomi/miwear/build"

检查当前Python路径

python 复制代码 
>>> import sys
>>> print(sys.path)  # 查看当前Python搜索路径
>>> print(__file__)  # 如果你在flash.py文件中，查看文件位置

推荐的工作流程

  1. 进入包含你的Python文件的目录

    bash 复制代码 
    cd /Users/junbozheng/xiaomi/miwear/build

  2. 使用IPython（推荐）或Python

    bash 复制代码 
    ipython

  3. 导入并查看文档

    python 复制代码 
    In [1]: import sys
In [2]: sys.path.insert(0, '.')  # 如果IPython没有自动添加
In [3]: import flash
In [4]: help(flash)  # 或使用 flash? 在IPython中

这样应该就能成功导入你的模块并查看文档字符串了！

相关推荐
山海青风1 小时前
用 Meta MMS-TTS + Python在本地把藏文文本变成藏语语音
python·音视频
摸爬滚打李上进1 小时前
Pycharm编辑HTML文件注释问题
python·pycharm·django·bootstrap·html5
二川bro1 小时前
内存泄漏检测：Python内存管理深度解析
java·开发语言·python
武子康2 小时前
AI研究-133 Java vs Kotlin/Go/Rust/Python/Node：2025 详细对比分析 定位与取舍指南
java·javascript·python·golang·rust·kotlin·node
执笔论英雄2 小时前
【RL]expand_requests干啥的
服务器·开发语言·python
kesifan2 小时前
JAVA线程的建立方法
java·开发语言·python
TechMasterPlus2 小时前
调用千问大模型服务
人工智能·python
apocelipes2 小时前
Linux的binfmt_misc机制
linux·c语言·c++·python·golang·linux编程·开发工具和环境
中工钱袋2 小时前
Java Stream 流详解
java·windows·python
热门推荐
01GitHub 镜像站点02BongoCat - 跨平台键盘猫动画工具03UV安装并设置国内源04安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）05Linux下V2Ray安装配置指南06【保姆级教程】免费使用Gemini3的5种方法！免翻墙/国内直连0746个Nano-banana 精选提示词，持续更新中08“我的电脑”图标没了怎么办 4种方法找回09全球最强模型Grok4，国内已可免费使用！（附教程）10在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）