my_project/                  # 项目根目录 (例如，Git 仓库的根)
│
├── my_package/              # 主要的 Python 包 (你的应用或库的核心代码)
│   ├── __init__.py          # 将 'my_package' 标记为一个 Python 包，可包含包级别初始化代码
│   ├── module1.py           # 包内的模块文件
│   ├── module2.py           # 另一个模块文件
│   ├── subpackage/          # 包内可以有子包
│   │   ├── __init__.py      # 使 'subpackage' 成为一个子包
│   │   └── submodule.py     # 子包内的模块
│   └── utils/               # 常用的工具或辅助函数可以组织在子包中
│       ├── __init__.py
│       └── helpers.py       # 辅助函数模块
│
├── tests/                   # 存放所有测试代码的目录
│   ├── __init__.py          # 使 'tests' 成为一个包 (有些测试运行器需要)
│   ├── test_module1.py      # 针对 my_package.module1 的测试
│   └── test_subpackage_submodule.py # 针对子包模块的测试
│
├── docs/                    # 项目文档 (例如使用 Sphinx 或 MkDocs 生成)
│   ├── conf.py              # Sphinx 配置文件 (如果使用 Sphinx)
│   ├── index.rst            # Sphinx 主文档文件 (或 index.md)
│   └── api.rst              # API 文档等
│
├── examples/                # 如何使用你的包或库的示例代码
│   └── usage_example.py
│
├── .gitignore               # 指定 Git 应忽略的文件和目录
├── LICENSE                  # 项目的许可证文件 (例如 MIT, Apache 2.0)
├── README.md                # 项目的详细说明、安装指南、使用方法等 (Markdown 格式)
├── requirements.txt         # 列出项目运行所需的基本依赖包及其版本
├── setup.py                 # (传统方式) Python 项目的构建脚本 (用于打包、分发)
├── pyproject.toml           # (现代方式) 项目元数据和构建系统配置 (推荐与 setup.py/setup.cfg 结合或替代)
└── tox.ini                  # (可选) tox 配置文件，用于自动化测试不同 Python 环境

# === 代码质量与 PEP 8 实践演示 ===
from print_utils import * 
import os # 标准库导入
import sys # 标准库导入
from collections import defaultdict # 标准库导入，from ... import ...
from typing import List, Tuple, Any, Optional, Union, Dict # 类型注解

# 第三方库导入 (示例)
# import numpy as np
# import pandas as pd

# 本地应用/库导入 (示例)
# from my_package import my_module_example 

# =============================================================
# 0. 模块级别文档字符串与常量
# =============================================================
print_header("代码质量与 PEP 8 核心实践演示")

"""
本模块旨在演示 Python PEP 8 风格指南中的常见规则和一些编码最佳实践。
PEP 8 官方文档: https://www.python.org/dev/peps/pep-0008/
"""

# 常量名应全部大写，单词间用下划线分隔
MAX_RETRIES: int = 3
DEFAULT_GREETING: str = "Hello"


# =============================================================
# 1. 类定义与文档字符串
# =============================================================
print_subheader("1. 类定义与文档字符串")

class SampleClass:
    """
    一个示例类，用于演示 PEP 8 规范和良好实践。

    这个类的主要目的是展示命名约定、文档字符串格式、
    方法定义以及属性的组织方式。

    Attributes:
        name (str): 对象的名称。
        value (Optional[int]): 一个可选的整数值。
        _protected_member (str): 一个受保护的成员变量。
        __private_member (float): 一个私有的成员变量。
    """
    CLASS_LEVEL_CONSTANT: str = "This is a class-level constant"

    def __init__(self, name: str, value: Optional[int] = None) -> None:
        """
        初始化 SampleClass 对象。

        Args:
            name (str): 对象的名称。
            value (Optional[int], optional): 一个可选的整数值。默认为 None。
        """
        print_info(f"  Initializing SampleClass(name='{name}', value={value})")
        self.name: str = name
        self.value: Optional[int] = value
        self._protected_member: str = "I am protected" # 受保护成员以下划线开头
        self.__private_member: float = 3.14          # 私有成员以双下划线开头 (会被名称修饰)

    def display_info(self, prefix: str = "Info") -> str:
        """
        显示对象的信息。

        如果参数列表过长，可以像下面这样换行和缩进：
        def another_method(
            self,
            param1: type,
            param2: type,
            very_long_parameter_name: type = default_value
        ) -> ReturnType:
            pass
        
        Args:
            prefix (str, optional): 信息输出的前缀。默认为 "Info"。

        Returns:
            str: 格式化后的信息字符串。
        """
        # 行长度通常建议不超过 79 个字符 (或团队约定的长度，如 88, 100, 120)
        # 长字符串或表达式可以分行，通常在操作符之后换行，并适当缩进
        info_string: str = (
            f"{prefix}: Name='{self.name}', Value={self.value}, "
            f"Protected='{self._protected_member}', "
            f"Private (mangled name access): {self._SampleClass__private_member}" # 访问被名称修饰的私有变量
        )
        # 在二元运算符之前或之后换行都是PEP 8允许的，但团队内应保持一致
        # calculation_example = (var1 + var2 + var3
        #                        - var4 - var5)
        return info_string

    @property
    def name_uppercase(self) -> str:
        """一个只读属性，返回大写的名称。"""
        return self.name.upper()

# =============================================================
# 2. 函数定义与文档字符串
# =============================================================
print_subheader("2. 函数定义与文档字符串")

def calculate_sum_and_average(numbers: List[float]) -> Tuple[float, float]:
    """
    计算一个数字列表的总和与平均值。

    Args:
        numbers (List[float]): 需要计算的浮点数列表。

    Returns:
        Tuple[float, float]: 一个包含总和与平均值的元组。

    Raises:
        ValueError: 如果输入列表为空。
        TypeError: 如果列表中包含非数字类型的元素。
    """
    print_info(f"  Calculating sum and average for: {numbers}")
    if not numbers:
        raise ValueError("输入列表不能为空以计算平均值。")
    
    current_sum: float = 0.0
    try:
        for num in numbers:
            current_sum += num # 操作符两侧通常有空格
    except TypeError as e: # 捕获特定异常
        raise TypeError(f"列表中的所有元素都必须是数字: {e}")

    count: int = len(numbers)
    average: float = current_sum / count
    
    # 正确的空格使用示例:
    # x = 1 + 2  # 运算符两侧
    # my_func(arg1, arg2) # 逗号后，括号内侧通常无空格 (除非是元组只有一个元素 my_tuple = (1,))
    # my_list[0] # 索引/切片操作符内侧无空格
    # my_dict = {"key": "value"} # 冒号后有空格，前面无；花括号内侧通常无空格

    return current_sum, average


# =============================================================
# 3. 条件语句与 Pythonic 表达
# =============================================================
print_subheader("3. 条件语句与 Pythonic 表达")

def check_item_status(item: Optional[Any], status_flags: int = 0) -> str:
    """演示条件语句的推荐写法。"""
    print_info(f"  Checking status for item: {item}, flags: {status_flags}")
    
    # 检查 None: 使用 `is None` 或 `is not None`
    if item is None:
        return "项目为 None。"
    
    # 检查布尔真值: 直接使用 `if item:` 或 `if not item:`
    # 而不是 `if item == True:` 或 `if item == []:`
    if not item: # 适用于空列表、空字符串、空字典、0、None 等
        return "项目为空或具有布尔假值。"
        
    # 复杂条件表达式，如果过长，可以分行并用括号括起来
    # (此处的 status_flags 仅为示例)
    IS_ACTIVE_FLAG = 1
    IS_URGENT_FLAG = 2
    if (isinstance(item, str) and
            len(item) > 5 and
            (status_flags & IS_ACTIVE_FLAG) and # 位运算示例
            not (status_flags & IS_URGENT_FLAG)):
        return f"项目 '{item}' 是一个长度大于5的活动字符串且不紧急。"
        
    return f"项目 '{item}' 具有其他状态。"

# =============================================================
# 4. 推导式与生成器表达式
# =============================================================
print_subheader("4. 推导式与生成器表达式")

def demonstrate_comprehensions(data: List[int]) -> None:
    """演示列表推导式和生成器表达式。"""
    print_info(f"  Original data: {data}")
    
    # 列表推导式
    squared_numbers: List[int] = [x**2 for x in data]
    print_success(f"    Squared numbers (list comprehension): {squared_numbers}")
    
    even_squared_numbers: List[int] = [x**2 for x in data if x % 2 == 0]
    print_success(f"    Even squared numbers (with condition): {even_squared_numbers}")
    
    # 生成器表达式 (更节省内存，按需生成)
    sum_of_cubes: int = sum(x**3 for x in data) # 生成器表达式在 sum() 中使用
    print_success(f"    Sum of cubes (generator expression): {sum_of_cubes}")
    
    # 字典推导式
    number_to_square_dict: Dict[int, int] = {x: x**2 for x in data}
    print_success(f"    Number to square dict: {number_to_square_dict}")

    # 避免过于复杂的嵌套推导式，如果可读性受损，应拆分为普通循环
    # matrix = [[1, 2], [3, 4]]
    # flattened = [element for row in matrix for element in row] # 尚可接受
    # print_info(f"    Flattened matrix: {flattened}")


# =============================================================
# 5. 异常处理 (try-except-else-finally)
# =============================================================
print_subheader("5. 异常处理")

def perform_safe_operation(value1: Any, value2: Any) -> Optional[float]:
    """一个演示安全操作的函数，包含完整的异常处理。"""
    print_info(f"  Attempting operation with {value1} and {value2}")
    result: Optional[float] = None
    try:
        # 假设这是一个可能抛出多种异常的操作
        if not (isinstance(value1, (int, float)) and isinstance(value2, (int, float))):
            raise TypeError("输入值必须是数字类型。")
        if value2 == 0:
            raise ValueError("除数不能为零。") # 自定义 ValueError 而非直接 ZeroDivisionError
        result = float(value1 / value2)
    except ValueError as ve: # 捕获特定的、预期的异常
        print_error(f"    操作失败 (ValueError): {ve}")
        # logger.error(f"ValueError during operation: {ve}", exc_info=True) # 实际项目中用日志
    except TypeError as te:
        print_error(f"    操作失败 (TypeError): {te}")
    except Exception as e: # 捕获其他所有 Exception 子类的异常 (作为最后防线)
        print_error(f"    发生未知错误: {type(e).__name__} - {e}")
    else:
        # 如果 try 块中没有发生任何异常，则执行 else 块
        print_success(f"    操作成功完成，结果: {result}")
    finally:
        # 无论 try 块中是否发生异常，finally 块总会执行
        # 通常用于资源清理
        print_info("    操作尝试已结束 (finally 块执行)。")
    return result


# =============================================================
# 6. 上下文管理器 (with 语句)
# =============================================================
print_subheader("6. 上下文管理器 (with 语句)")

def read_content_from_file_safely(filepath: str) -> Optional[str]:
    """使用上下文管理器安全地读取文件内容。"""
    print_info(f"  Attempting to read file: {filepath}")
    try:
        # 'with' 语句确保文件在操作完成后（即使发生异常）也会被正确关闭
        with open(filepath, "r", encoding="utf-8") as file_handle:
            content: str = file_handle.read()
            print_success(f"    成功读取文件 '{filepath}'。")
            return content
    except FileNotFoundError:
        print_error(f"    文件 '{filepath}' 未找到。")
        return None
    except IOError as e:
        print_error(f"    读取文件 '{filepath}' 时发生 IO 错误: {e}")
        return None


if __name__ == "__main__":
    # 主程序块，用于调用演示函数
    print_info("--- 开始演示 SampleClass ---")
    my_object = SampleClass(name="ProriseInstance", value=100)
    print_success(my_object.display_info(prefix="Object"))
    print_success(f"  Uppercase name: {my_object.name_uppercase}")

    print_info("\n--- 开始演示 calculate_sum_and_average ---")
    numbers_list: List[float] = [10.0, 15.5, 20.0, 5.5]
    total, avg = calculate_sum_and_average(numbers_list)
    print_success(f"  对于列表 {numbers_list}，总和: {total}, 平均值: {avg:.2f}")
    try:
        calculate_sum_and_average([])
    except ValueError as e:
        print_warning(f"  捕获到预期错误: {e}")

    print_info("\n--- 开始演示 check_item_status ---")
    print_info(f"  {check_item_status(None)}")
    print_info(f"  {check_item_status('')}")
    print_info(f"  {check_item_status('A very long active string', status_flags=1)}") # IS_ACTIVE_FLAG = 1

    print_info("\n--- 开始演示 demonstrate_comprehensions ---")
    demonstrate_comprehensions([1, 2, 3, 4, 5, 6])

    print_info("\n--- 开始演示 perform_safe_operation ---")
    perform_safe_operation(10, 2)
    perform_safe_operation(10, 0)
    perform_safe_operation("abc", 2)
    perform_safe_operation(10, "xyz")
    
    print_info("\n--- 开始演示 read_content_from_file_safely ---")
    # 创建一个临时文件用于读取演示
    temp_file_for_read = "temp_read_example.txt"
    with open(temp_file_for_read, "w", encoding="utf-8") as f_temp:
        f_temp.write("Hello from with statement example!\nSecond line.")
    
    file_contents = read_content_from_file_safely(temp_file_for_read)
    if file_contents:
        print_info(f"    文件内容 (前50字符): '{file_contents[:50]}...'")
    read_content_from_file_safely("non_existent_file.txt") # 测试文件不存在的情况
    
    if os.path.exists(temp_file_for_read): # 清理临时文件
        os.remove(temp_file_for_read)
        print_info(f"  已删除临时读取文件: {temp_file_for_read}")

    print_header("代码质量与 PEP 8 实践演示结束。")