如何高效構(gòu)建 Python 腳本結(jié)構(gòu)

編程獅（w3cschool.cn） 2025-06-10 11:47:19 瀏覽數(shù) (1087)

反饋

在 Python 學(xué)習(xí)中，可能一開始是在交互式環(huán)境中探索，比如 Jupyter Notebook 或 Python REPL。這種方式非常適合快速實(shí)驗(yàn)和即時(shí)反饋，但隨著代碼量的增長(zhǎng)，將代碼保存到 .py 文件并進(jìn)行結(jié)構(gòu)化組織變得至關(guān)重要。結(jié)構(gòu)化的腳本不僅能夠提升代碼的可讀性，還能促進(jìn)團(tuán)隊(duì)協(xié)作與開發(fā)效率。本文將帶你從零開始，逐步掌握 Python 腳本結(jié)構(gòu)化的技巧，讓你的代碼更清晰、健壯且易于分享。

腳本結(jié)構(gòu)化的關(guān)鍵優(yōu)勢(shì)

隨著代碼量的增長(zhǎng)，腳本結(jié)構(gòu)化能顯著提升代碼的可維護(hù)性和可擴(kuò)展性。它幫助你將代碼組織得井井有條，使每個(gè)部分的職責(zé)明確，便于后續(xù)的修改與優(yōu)化。同時(shí)，良好的結(jié)構(gòu)使代碼更易于被他人理解，方便團(tuán)隊(duì)協(xié)作開發(fā)。此外，結(jié)構(gòu)化的腳本還能讓你的代碼更具專業(yè)性，為未來的代碼復(fù)用和功能擴(kuò)展打下堅(jiān)實(shí)基礎(chǔ)。

腳本結(jié)構(gòu)化的具體方法

1. 合理組織導(dǎo)入語(yǔ)句

遵循 PEP 8 規(guī)范，將導(dǎo)入語(yǔ)句分為三類：

標(biāo)準(zhǔn)庫(kù)導(dǎo)入：如 import os、import sys 等。
第三方庫(kù)導(dǎo)入：如 import requests、import numpy 等。
本地模塊導(dǎo)入：如 from mymodule import myfunction。

# 標(biāo)準(zhǔn)庫(kù)導(dǎo)入
import os
import sys
import logging
from pathlib import Path


# 第三方庫(kù)導(dǎo)入
import requests
import numpy as np
import pandas as pd


# 本地模塊導(dǎo)入
from mymodule import myfunction

2. 使用 shebang 線（適用于 Unix 系統(tǒng)）

在腳本開頭添加 shebang 線，指定使用哪個(gè) Python 解釋器運(yùn)行腳本，并通過 chmod +x script.py 命令使腳本可直接執(zhí)行。

#!/usr/bin/env python3


# 腳本內(nèi)容...

3. 定義腳本入口

使用 if __name__ == "__main__": 定義腳本的入口，確保某些代碼僅在腳本直接運(yùn)行時(shí)執(zhí)行，而不是在被導(dǎo)入時(shí)執(zhí)行。

def main():
    # 主邏輯代碼
    print("腳本開始執(zhí)行...")
    # 其他邏輯...


if __name__ == "__main__":
    main()

4. 使用 PEP 723 管理依賴

在腳本中嵌入依賴信息，方便工具（如 uv 或 pipx）自動(dòng)生成運(yùn)行環(huán)境。

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


# 腳本內(nèi)容...

5. 處理命令行參數(shù)

使用 argparse 或第三方庫(kù)（如 Click）定義命令行參數(shù)，使腳本更靈活和用戶友好。

import argparse


def main():
    parser = argparse.ArgumentParser(description="處理命令行參數(shù)")
    parser.add_argument("--name", type=str, help="輸入你的名字")
    args = parser.parse_args()
    print(f"你好，{args.name}！")


if __name__ == "__main__":
    main()

6. 選擇合適的數(shù)據(jù)結(jié)構(gòu)

根據(jù)需求選擇合適的數(shù)據(jù)結(jié)構(gòu)：

枚舉（enum）：用于固定選項(xiàng)或狀態(tài)。
namedtuple：用于簡(jiǎn)單、不可變的數(shù)據(jù)記錄。
數(shù)據(jù)類（dataclass）：用于靈活的數(shù)據(jù)記錄，支持類型提示和方法添加。
自定義類（class）：用于復(fù)雜的面向?qū)ο髨?chǎng)景。

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)


# 數(shù)據(jù)類
@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. 增強(qiáng)腳本反饋

使用 logging 模塊記錄日志，使用 assert 語(yǔ)句進(jìn)行內(nèi)部檢查，使用 Rich 庫(kù)增強(qiáng)終端輸出。

import logging
from rich.console import Console


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


# 使用 logging
logging.info("這是一個(gè)信息日志")


# 使用 assert
def divide(a, b):
    assert b != 0, "除數(shù)不能為零"
    return a / b


# 使用 Rich
console = Console()
console.print("這是一個(gè)富文本輸出", style="bold red")

腳本結(jié)構(gòu)化的實(shí)踐案例

以一個(gè)獲取并處理鳶尾花數(shù)據(jù)集的腳本為例，展示如何應(yīng)用上述結(jié)構(gòu)化技巧。

#!/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():
    """獲取鳶尾花數(shù)據(jù)集"""
    try:
        logger.info("開始獲取數(shù)據(jù)...")
        response = requests.get(IRIS_URL)
        response.raise_for_status()
        data = pd.read_csv(pd.io.BytesIO(response.content))
        logger.info("數(shù)據(jù)獲取成功")
        return data
    except Exception as e:
        logger.error(f"獲取數(shù)據(jù)失敗：{e}")
        raise


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


if __name__ == "__main__":
    main()

Python 腳本結(jié)構(gòu)化總結(jié)與推薦

以下是一些 Python 腳本結(jié)構(gòu)化的關(guān)鍵點(diǎn)和推薦：

追求簡(jiǎn)潔與清晰：使用清晰的常量、函數(shù)和變量命名，避免過度嵌套或抽象。
利用參數(shù)解析進(jìn)行輸入驗(yàn)證：使用 argparse 或 Click 等工具定義參數(shù)并驗(yàn)證用戶輸入。
采用自包含依賴：使用 PEP 723 在腳本文件中聲明依賴，方便他人運(yùn)行。
明智選擇數(shù)據(jù)結(jié)構(gòu)：根據(jù)腳本的復(fù)雜度和目標(biāo)選擇合適的數(shù)據(jù)結(jié)構(gòu)。

結(jié)構(gòu)	適用場(chǎng)景	推薦
`enum.Enum`	表示固定選項(xiàng)、狀態(tài)、模式	用以提高代碼可讀性和類型安全性
`collections.namedtuple`	簡(jiǎn)單、不可變數(shù)據(jù)記錄	用于需要簡(jiǎn)潔、固定記錄且不可變的場(chǎng)景
`dataclasses.dataclass`	靈活數(shù)據(jù)記錄	適用于大多數(shù)結(jié)構(gòu)化數(shù)據(jù)，平衡了功能、可讀性和易用性
`class`（自定義類）	復(fù)雜狀態(tài)、行為、繼承模式	當(dāng)需要完整的面向?qū)ο蠊δ軙r(shí)使用

通過應(yīng)用這些結(jié)構(gòu)化技巧，你的腳本將更具可讀性、可維護(hù)性和可分享性。這些方法將幫助你寫出功能完善、健壯且專業(yè)的 Python 腳本。