Python 模块开发指南

模块基础

Python 模块是包含 Python 定义和语句的文件，文件名就是模块名加上 .py 后缀。模块可以包含函数、类和变量，也可以包含可运行的代码。

标准模块模板

下面是一个符合现代 Python 开发规范的模块模板：

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

"""这是一个模块的文档字符串。

这里可以详细描述模块的功能、使用方法和注意事项。
"""

__author__ = 'Your Name'
__version__ = '0.1.0'
__license__ = 'MIT'

import sys
from typing import List

def main(args: List[str]) -> None:
    """主函数，处理命令行参数"""
    if len(args) == 1:
        print('Hello, world!')
    elif len(args) == 2:
        print(f'Hello, {args[1]}!')
    else:
        print('Too many arguments!')

if __name__ == '__main__':
    main(sys.argv)

模板说明

  1. Shebang 和编码声明：

    • #!/usr/bin/env python3 让脚本在 Unix-like 系统上可直接执行
    • # -*- coding: utf-8 -*- 确保文件使用 UTF-8 编码（Python 3 默认就是 UTF-8，可以省略）

  2. 文档字符串：

    • 模块的第一个字符串是文档字符串，使用三引号格式
    • 可以通过 __doc__ 属性访问

  3. 元信息：

    • __author__: 模块作者
    • __version__: 模块版本
    • __license__: 许可协议

  4. 导入：

    • 使用现代 Python 的类型注解（from typing import List）
    • 导入语句放在模块文档之后，常量定义之前

  5. 主函数：

    • 使用类型注解明确参数和返回值类型
    • 使用 f-string 进行字符串格式化（Python 3.6+）

模块使用

命令行执行

$ python3 hello.py
Hello, world!

$ python3 hello.py Alice
Hello, Alice!

交互式导入

>>> import hello
>>> hello.main(['hello.py', 'Bob'])
Hello, Bob!

作用域与访问控制

Python 使用命名约定来实现访问控制：

  1. 公共(Public)成员：

    • 普通命名：function_name, variable_name
    • 可以直接导入和使用

  2. 特殊成员：

    • 双下划线开头和结尾：__name__, __doc__
    • 有特殊含义，通常不应自定义此类名称

  3. 私有(Private)成员：

    • 单下划线开头：_internal_function
      • 提示"内部使用"，但外部仍可访问
    • 双下划线开头：__private_function
      • 触发名称修饰（name mangling），更难直接访问

封装示例

def _private_greeting(name: str) -> str:
    """私有函数，生成问候语"""
    return f'Hello, {name}!'

def _private_farewell(name: str) -> str:
    """私有函数，生成告别语"""
    return f'Goodbye, {name}!'

def greet(name: str, formal: bool = True) -> str:
    """公开函数，根据形式返回问候语或告别语
    
    Args:
        name: 要问候的名字
        formal: 是否使用正式问候
        
    Returns:
        生成的问候字符串
    """
    if formal:
        return _private_greeting(name)
    return _private_farewell(name)

最佳实践

  1. 模块组织：

    • 保持模块功能单一
    • 模块大小适中（通常不超过几百行）

  2. 文档：

    • 为模块和公共函数编写详细的文档字符串
    • 使用类型注解提高代码可读性

  3. 测试：

    • 使用 if __name__ == '__main__': 包含测试代码
    • 考虑使用 doctest 或 unittest 进行更全面的测试

  4. 版本控制：

    • 在模块中维护 __version__ 变量
    • 遵循语义化版本规范

  5. 依赖管理：

    • 明确声明依赖
    • 考虑使用 try-except 处理可选依赖

通过遵循这些规范，可以创建出结构清晰、易于维护和重用的 Python 模块。