Python 代码规范权威指南

# 使用括号换行
foo_bar(self, width, height, color='black', design=None, 
        x='foo', emphasis=None, highlight=0)

# 字符串连接
x = ('This will build a very long long '
     'long long long long long long string')

class MyClass:
    """一个示例类。"""

    def __init__(self):
        """初始化方法。"""
        self.value = 0

    def method_one(self):
        """第一个方法。"""
        return self.value

    def method_two(self):
        """第二个方法。"""
        return self.value * 2


def standalone_function():
    """独立函数。"""
    pass

def square(x):
    """返回 x 的平方。"""
    return x * x

def complex_function(arg1, arg2, **kwargs):
    """执行复杂的计算操作。

    这个函数接受两个必需参数和可选的关键字参数，
    执行复杂的数学计算并返回结果。

    Args:
        arg1 (int): 第一个操作数
        arg2 (float): 第二个操作数
        **kwargs: 可选的配置参数

    Returns:
        float: 计算结果

    Raises:
        ValueError: 当参数无效时抛出
        TypeError: 当参数类型错误时抛出

    Example:
        >>> result = complex_function(10, 3.14, precision=2)
        >>> print(result)
        31.4
    """
    if not isinstance(arg1, int):
        raise TypeError("arg1 must be an integer")
    return arg1 * arg2

def greet(name: str) -> str:
    """问候函数。
    
    Args:
        name: 被问候者的姓名
        
    Returns:
        问候语
    """
    return f"Hello, {name}!"

# 变量注解
age: int = 25
price: float = 99.99
is_active: bool = True

from typing import List, Dict, Tuple, Set, Optional, Union

def process_items(items: List[str]) -> Dict[str, int]:
    """处理项目列表。
    
    Args:
        items: 字符串列表
        
    Returns:
        字符串到整数的映射
    """
    return {item: len(item) for item in items}

# 复杂类型注解
coordinates: Tuple[float, float] = (10.5, 20.3)
user_ids: Set[int] = {1, 2, 3, 4}
config: Dict[str, Union[str, int, bool]] = {
    "debug": True,
    "port": 8080,
    "host": "localhost"
}

# 标准库导入
import os
import sys
from typing import List, Dict, Optional

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

# 本地应用导入
from myproject import config
from myproject.utils import helper_function
from myproject.models import User

# 模块和包名：小写，可使用下划线
import user_manager
from data_processing import csv_parser

# 类名：大驼峰命名法（CapWords）
class UserManager:
    pass

class HTTPConnectionPool:
    pass

# 函数和方法名：小写，使用下划线分隔
def calculate_total():
    pass

def get_user_by_id():
    pass

# 变量名：小写，使用下划线分隔
user_count = 10
max_retry_attempts = 3

# 常量：全部大写，使用下划线分隔
MAX_CONNECTIONS = 100
DEFAULT_TIMEOUT = 30
API_BASE_URL = "https://api.example.com"

# 计算复杂度为 O(n log n) 的排序算法
# 适用于大型数据集，但对于小数据集可能不如简单排序快
def merge_sort(arr):
    if len(arr) <= 1:
        return arr
    
    # 分割数组为两半
    mid = len(arr) // 2
    left = merge_sort(arr[:mid])
    right = merge_sort(arr[mid:])
    
    # 合并已排序的两半
    return merge(left, right)

def validate_email(email: str) -> bool:
    """验证邮箱格式。
    
    Args:
        email: 待验证的邮箱地址
        
    Returns:
        True 如果邮箱格式有效，False 否则
    """
    import re
    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    return bool(re.match(pattern, email))

def send_notification(
    recipient: str,
    subject: str,
    message: str,
    notification_type: str = 'email'
) -> bool:
    """发送通知。
    
    Args:
        recipient: 接收者
        subject: 主题
        message: 消息内容
        notification_type: 通知类型（email, sms, push）
        
    Returns:
        True 如果发送成功，False 否则
        
    Raises:
        ValueError: 当通知类型不支持时
    """
    if notification_type not in ['email', 'sms', 'push']:
        raise ValueError(f"Unsupported notification type: {notification_type}")
    
    if notification_type == 'email' and not validate_email(recipient):
        return False
    
    # 发送逻辑
    return True