python-import-check

高效能 Python 匯入與模組健康檢查工具（Rust 實作）

工具簡介

python-import-check 是一款以 Rust 開發、專為大型 Python 專案設計的自動化檢查工具。可遞迴掃描指定目錄下所有 Python 檔案，進行依賴分析、深度載入測試、資源監控（記憶體/CPU/載入速度）、循環引用、潛在記憶體洩漏、程式碼風格等多面向檢查，並以分組報表輸出所有異常。

安裝

# 需先安裝 Rust 與 Python3
cargo build --release
# 或直接使用 pip 安裝 Python 部分
pip install .

使用方式

python-import-check [參數]

參數說明

參數	型態	預設值	說明
-d, --dir	選用參數	.	指定要檢查的目錄
-p, --python	選用參數	python3	指定 Python 執行路徑或 docker 指令
-e, --exclude	可多次	無	忽略特定資料夾，可重複指定
--help	flag		顯示說明

• 支援多重排除目錄（可重複 -e）。
• 可指定 docker 執行環境（如 --python "docker:python:3.11"）。
• 預設會遞迴檢查所有 .py 檔案（排除 init.py）。

檢查項目

• 模組載入錯誤（MODULE_LOAD_ERROR）
• 執行時錯誤（RUNTIME_ERROR）
• 載入速度過慢（SLOW_LOAD）
• 記憶體用量異常（HIGH_MEMORY_USAGE）
• CPU 用量異常（HIGH_CPU_USAGE）
• 循環引用（CIRCULAR_REFERENCE）
• 潛在記憶體洩漏（POTENTIAL_MEMORY_LEAK）
• 代碼風格問題（如參數過多、函數過長、全域變數過多、萬用字元 import、import 過多、語法錯誤、單行過長、縮排混用等）
• 模組屬性異常、函數複雜度過高、分析錯誤等

範例

1. 檢查目前目錄下所有 Python 檔案

python-import-check

2. 指定目錄並排除部分資料夾

python-import-check -d ./python_import_check -e tests -e build

3. 排除特定檔案

python-import-check -d . -e test_bad.py -e test_good.py

4. 同時指定多個資料夾或多個檔案

python-import-check -d package1 -d package2 -d python_import_check/utils.py

5. 指定 Python 執行環境

python-import-check -p python3.12
python-import-check -p "docker:python:3.11"

6. 顯示所有參數

python-import-check --help

輸出說明

• 若所有檔案皆通過，顯示：

  所有Python檔案深度檢查通過！
  

• 若有異常，依問題類型與檔案分組詳細列出，並統計各類型數量。

問題類型說明（部分）

類型	說明
MODULE_LOAD_ERROR	模組無法載入（找不到 spec）
RUNTIME_ERROR	執行時錯誤（import 或初始化例外）
SLOW_LOAD	載入速度過慢
HIGH_MEMORY_USAGE	記憶體用量異常
HIGH_CPU_USAGE	CPU 用量異常
CIRCULAR_REFERENCE	偵測到循環引用
POTENTIAL_MEMORY_LEAK	潛在記憶體洩漏
STYLE_TOO_MANY_ARGUMENTS	函數參數過多
STYLE_FUNCTION_TOO_LONG	函數/類別過長
STYLE_TOO_MANY_GLOBALS	全域變數過多
STYLE_WILDCARD_IMPORT	使用萬用字元（*）匯入
STYLE_TOO_MANY_IMPORTS	import 敘述過多
STYLE_SYNTAX_ERROR	語法錯誤
STYLE_LINE_TOO_LONG	單行程式碼過長
STYLE_MIXED_INDENTATION	縮排混用空白與 tab
MANY_ATTRIBUTES	模組屬性過多
MODULE_ATTR_ERROR	模組屬性檢查錯誤
COMPLEX_FUNCTION	函數複雜度過高
FUNCTION_ANALYSIS_ERROR	函數分析錯誤
MODULE_CHECK_ERROR	模組檢查過程發生錯誤

常見問題

• Q: 為何要用 Rust？
  A: 提升大量檔案遞迴、依賴分析與資源監控效能，並可自動產生高效 Python 檢查腳本。

• Q: 是否支援 Docker？
  A: 可用 -p "docker:python:3.11" 或自訂 docker run 指令。

• Q: 是否會修改原始檔案？
  A: 不會，僅讀取與分析，不會更動任何檔案內容。

目錄結構

• python_import_check/
  • complex_module.py
  • config.py
  • database.py
  • high_cpu.py
  • high_resource.py
  • import_errors.py
  • memory_leak.py
  • memory_test.py
  • utils.py
  • circular/
  • package1/
  • package2/