如何高效构建 Python 脚本结构

在 Python 学习中，可能一开始是在交互式环境中探索，比如 Jupyter Notebook 或 Python REPL。这种方式非常适合快速实验和即时反馈，但随着代码量的增长，将代码保存到 .py 文件并进行结构化组织变得至关重要。结构化的脚本不仅能够提升代码的可读性，还能促进团队协作与开发效率。本文将带你从零开始，逐步掌握 Python 脚本结构化的技巧，让你的代码更清晰、健壮且易于分享。

脚本结构化的关键优势

随着代码量的增长，脚本结构化能显著提升代码的可维护性和可扩展性。它帮助你将代码组织得井井有条，使每个部分的职责明确，便于后续的修改与优化。同时，良好的结构使代码更易于被他人理解，方便团队协作开发。此外，结构化的脚本还能让你的代码更具专业性，为未来的代码复用和功能扩展打下坚实基础。

脚本结构化的具体方法

1. 合理组织导入语句

遵循 PEP 8 规范，将导入语句分为三类：

标准库导入：如 import os、import sys 等。
第三方库导入：如 import requests、import numpy 等。
本地模块导入：如 from mymodule import myfunction。

# 标准库导入
import os
import sys
import logging
from pathlib import Path


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


# 本地模块导入
from mymodule import myfunction

2. 使用 shebang 线（适用于 Unix 系统）

在脚本开头添加 shebang 线，指定使用哪个 Python 解释器运行脚本，并通过 chmod +x script.py 命令使脚本可直接执行。

#!/usr/bin/env python3


# 脚本内容...

3. 定义脚本入口

使用 if __name__ == "__main__": 定义脚本的入口，确保某些代码仅在脚本直接运行时执行，而不是在被导入时执行。

def main():
    # 主逻辑代码
    print("脚本开始执行...")
    # 其他逻辑...


if __name__ == "__main__":
    main()

4. 使用 PEP 723 管理依赖

在脚本中嵌入依赖信息，方便工具（如 uv 或 pipx）自动生成运行环境。

# coding: utf-8
# embed:pyproject
[tool.poetry.dependencies]
requests = "^2.28.1"
numpy = "^1.23.5"
pandas = "^1.5.3"


# 脚本内容...

5. 处理命令行参数

使用 argparse 或第三方库（如 Click）定义命令行参数，使脚本更灵活和用户友好。

import argparse


def main():
    parser = argparse.ArgumentParser(description="处理命令行参数")
    parser.add_argument("--name", type=str, help="输入你的名字")
    args = parser.parse_args()
    print(f"你好，{args.name}！")


if __name__ == "__main__":
    main()

6. 选择合适的数据结构

根据需求选择合适的数据结构：

枚举（enum）：用于固定选项或状态。
namedtuple：用于简单、不可变的数据记录。
数据类（dataclass）：用于灵活的数据记录，支持类型提示和方法添加。
自定义类（class）：用于复杂的面向对象场景。

from enum import Enum
from dataclasses import dataclass
from collections import namedtuple


# 枚举
class Color(Enum):
    RED = 1
    GREEN = 2
    BLUE = 3


# namedtuple
Point = namedtuple("Point", ["x", "y"])
p = Point(1, 2)


# 数据类
@dataclass
class Person:
    name: str
    age: int
    def greet(self):
        print(f"你好，我叫{self.name}，今年{self.age}岁。")


# 自定义类
class Animal:
    def __init__(self, name):
        self.name = name
    def speak(self):
        pass

7. 增强脚本反馈

使用 logging 模块记录日志，使用 assert 语句进行内部检查，使用 Rich 库增强终端输出。

import logging
from rich.console import Console


# 配置日志
logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")


# 使用 logging
logging.info("这是一个信息日志")


# 使用 assert
def divide(a, b):
    assert b != 0, "除数不能为零"
    return a / b


# 使用 Rich
console = Console()
console.print("这是一个富文本输出", style="bold red")

脚本结构化的实践案例

以一个获取并处理鸢尾花数据集的脚本为例，展示如何应用上述结构化技巧。

#!/usr/bin/env python3
# coding: utf-8
# embed:pyproject
[tool.poetry.dependencies]
requests = "^2.28.1"
pandas = "^1.5.3"
click = "^8.1.3"
rich = "^12.6.0"


import os
import logging
import requests
import pandas as pd
import click
from rich.console import Console


# 配置日志
logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
logger = logging.getLogger(__name__)


# 常量定义
IRIS_URL = "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv"


# shebang 线和编码声明
def fetch_iris_data():
    """获取鸢尾花数据集"""
    try:
        logger.info("开始获取数据...")
        response = requests.get(IRIS_URL)
        response.raise_for_status()
        data = pd.read_csv(pd.io.BytesIO(response.content))
        logger.info("数据获取成功")
        return data
    except Exception as e:
        logger.error(f"获取数据失败：{e}")
        raise


@click.command()
@click.option("--operation", type=click.Choice(["summary", "describe"]), default="summary", help="操作类型")
def main(operation):
    """主函数"""
    data = fetch_iris_data()
    console = Console()
    if operation == "summary":
        console.print("数据集摘要：", style="bold blue")
        console.print(data.info())
    elif operation == "describe":
        console.print("数据集描述：", style="bold blue")
        console.print(data.describe())


if __name__ == "__main__":
    main()

Python 脚本结构化总结与推荐

以下是一些 Python 脚本结构化的关键点和推荐：

追求简洁与清晰：使用清晰的常量、函数和变量命名，避免过度嵌套或抽象。
利用参数解析进行输入验证：使用 argparse 或 Click 等工具定义参数并验证用户输入。
采用自包含依赖：使用 PEP 723 在脚本文件中声明依赖，方便他人运行。
明智选择数据结构：根据脚本的复杂度和目标选择合适的数据结构。

结构	适用场景	推荐
`enum.Enum`	表示固定选项、状态、模式	用以提高代码可读性和类型安全性
`collections.namedtuple`	简单、不可变数据记录	用于需要简洁、固定记录且不可变的场景
`dataclasses.dataclass`	灵活数据记录	适用于大多数结构化数据，平衡了功能、可读性和易用性
`class`（自定义类）	复杂状态、行为、继承模式	当需要完整的面向对象功能时使用

通过应用这些结构化技巧，你的脚本将更具可读性、可维护性和可分享性。这些方法将帮助你写出功能完善、健壮且专业的 Python 脚本。