Python 扩展约定

作为IT工程师，在Python项目开发中遵循良好的扩展约定可以提高代码的可维护性和可读性。以下是一些重要的Python扩展约定：

1. 文件命名约定

• 模块文件应使用小写字母和下划线命名：module_name.py
• 避免使用特殊字符和空格
• 测试文件应以test_开头：test_module.py

2. 包结构约定

project_name/
├── __init__.py
├── module1.py
├── module2.py
├── subpackage/
│   ├── __init__.py
│   ├── submodule1.py
│   └── submodule2.py
└── tests/
    ├── __init__.py
    ├── test_module1.py
    └── test_module2.py

3. 导入约定

# 标准库导入
import os
import sys

# 第三方库导入
import numpy as np
import pandas as pd

# 本地应用/库特定导入
from . import module1
from .subpackage import submodule1

4. 类型提示扩展

from typing import List, Dict, Optional, Union

def process_data(
    data: List[Dict[str, Union[int, float]]],
    threshold: Optional[float] = None
) -> Dict[str, float]:
    """处理数据并返回结果字典"""
    ...

5. 文档字符串约定

def calculate_average(values: List[float]) -> float:
    """计算给定数值列表的平均值。

    Args:
        values: 包含数值的列表

    Returns:
        计算得到的平均值

    Raises:
        ValueError: 如果列表为空
    """
    if not values:
        raise ValueError("列表不能为空")
    return sum(values) / len(values)

6. 测试扩展约定

import pytest
from module1 import calculate_average

class TestCalculateAverage:
    """测试calculate_average函数"""

    def test_normal_case(self):
        """测试正常情况"""
        assert calculate_average([1, 2, 3]) == 2.0

    def test_empty_list(self):
        """测试空列表情况"""
        with pytest.raises(ValueError):
            calculate_average([])

7. 日志记录约定

import logging

logger = logging.getLogger(__name__)

def process_data(data):
    try:
        logger.debug("开始处理数据")
        # 处理逻辑
        logger.info("数据处理完成")
    except Exception as e:
        logger.error(f"数据处理失败: {str(e)}")
        raise

8. 配置管理约定

from configparser import ConfigParser
import os

config = ConfigParser()
config.read(os.path.join(os.path.dirname(__file__), 'config.ini'))

DATABASE_URL = config.get('database', 'url')
API_KEY = config.get('api', 'key')

9. 异步编程约定

import asyncio
from typing import Awaitable

async def fetch_data(url: str) -> Awaitable[dict]:
    """异步获取数据"""
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.json()

10. 代码格式化工具

推荐使用以下工具保持代码风格一致： - black - 自动格式化代码 - isort - 自动排序导入语句 - flake8 - 代码风格检查 - mypy - 静态类型检查

遵循这些约定可以使Python项目更加规范，便于团队协作和维护。