diff --git a/Learning-Materials/Teaching-File-Toolkit/README.md b/Learning-Materials/Teaching-File-Toolkit/README.md new file mode 100644 index 0000000..9aef894 --- /dev/null +++ b/Learning-Materials/Teaching-File-Toolkit/README.md @@ -0,0 +1,62 @@ +# 教學檔案處理工具包 + +結論:這個資料夾提供教學檔案處理常用的 Python 套件清單與驗證工具,適合處理 Word、Excel、PowerPoint、PDF、圖片、QR code、Markdown 轉換與 OCR 前處理。 + +## 成功標準 + +1. 可以用 `requirements.txt` 安裝核心 Python 套件。 +2. `setup_teaching_file_toolkit.py verify` 顯示全部核心 Python 套件匯入成功。 +3. `setup_teaching_file_toolkit.py check-system` 能列出 Tesseract、Poppler、ffmpeg、Office 是否已在 PATH。 + +## 建議安裝方式 + +在此 repo 根目錄建立虛擬環境: + +```powershell +python -m venv .venv +.\.venv\Scripts\python.exe -m pip install --upgrade pip +.\.venv\Scripts\python.exe Learning-Materials\Teaching-File-Toolkit\setup_teaching_file_toolkit.py install +``` + +驗證: + +```powershell +.\.venv\Scripts\python.exe Learning-Materials\Teaching-File-Toolkit\setup_teaching_file_toolkit.py verify +.\.venv\Scripts\python.exe Learning-Materials\Teaching-File-Toolkit\setup_teaching_file_toolkit.py check-system +``` + +## 核心套件 + +- Word:`python-docx`、`docxcompose`、`docx2pdf` +- Excel:`openpyxl`、`xlsxwriter`、`pandas` +- PowerPoint:`python-pptx` +- PDF:`pypdf`、`PyMuPDF`、`pdfplumber`、`pdf2image`、`reportlab`、`fpdf2` +- 圖片與圖表:`pillow`、`matplotlib` +- 其他:`qrcode`、`markitdown`、`ocrmypdf` +- Windows Office 自動化:`pywin32` + +## 選用影音套件 + +影音、字幕、旁白或 YouTube 處理才需要安裝: + +```powershell +.\.venv\Scripts\python.exe -m pip install -r Learning-Materials\Teaching-File-Toolkit\optional-media-requirements.txt +``` + +## 系統相依 + +這些不是 pip 套件,需另外安裝: + +- Tesseract OCR:`ocrmypdf` 做掃描 PDF OCR 時需要。 +- Poppler:`pdf2image` 轉圖時需要。 +- ffmpeg:`openai-whisper` 或影音處理時需要。 +- Microsoft Word / PowerPoint:`docx2pdf` 與 Office COM 轉 PDF 時需要。 + +Windows 可用的常見安裝方式: + +```powershell +winget install UB-Mannheim.TesseractOCR +winget install Gyan.FFmpeg +``` + +Poppler 可用 Chocolatey 安裝,或下載 Windows 版 Poppler 後加入 PATH。 diff --git a/Learning-Materials/Teaching-File-Toolkit/optional-media-requirements.txt b/Learning-Materials/Teaching-File-Toolkit/optional-media-requirements.txt new file mode 100644 index 0000000..56b23c2 --- /dev/null +++ b/Learning-Materials/Teaching-File-Toolkit/optional-media-requirements.txt @@ -0,0 +1,4 @@ +openai-whisper +edge-tts +yt-dlp +youtube-transcript-api diff --git a/Learning-Materials/Teaching-File-Toolkit/requirements.txt b/Learning-Materials/Teaching-File-Toolkit/requirements.txt new file mode 100644 index 0000000..04b2710 --- /dev/null +++ b/Learning-Materials/Teaching-File-Toolkit/requirements.txt @@ -0,0 +1,19 @@ +python-docx +docxcompose +openpyxl +xlsxwriter +pandas +python-pptx +pypdf +PyMuPDF +pdfplumber +pdf2image +reportlab +fpdf2 +pillow +matplotlib +qrcode +markitdown +ocrmypdf +docx2pdf +pywin32; platform_system == "Windows" diff --git a/Learning-Materials/Teaching-File-Toolkit/setup_teaching_file_toolkit.py b/Learning-Materials/Teaching-File-Toolkit/setup_teaching_file_toolkit.py new file mode 100644 index 0000000..7eac663 --- /dev/null +++ b/Learning-Materials/Teaching-File-Toolkit/setup_teaching_file_toolkit.py @@ -0,0 +1,138 @@ +"""教學檔案處理工具包安裝與驗證工具。 + +用法: + python setup_teaching_file_toolkit.py verify + python setup_teaching_file_toolkit.py install + python setup_teaching_file_toolkit.py check-system +""" + +from __future__ import annotations + +import argparse +import importlib +import platform +import shutil +import subprocess +import sys +from pathlib import Path + + +PACKAGE_IMPORTS = { + "python-docx": "docx", + "docxcompose": "docxcompose", + "openpyxl": "openpyxl", + "xlsxwriter": "xlsxwriter", + "pandas": "pandas", + "python-pptx": "pptx", + "pypdf": "pypdf", + "PyMuPDF": "fitz", + "pdfplumber": "pdfplumber", + "pdf2image": "pdf2image", + "reportlab": "reportlab", + "fpdf2": "fpdf", + "pillow": "PIL", + "matplotlib": "matplotlib", + "qrcode": "qrcode", + "markitdown": "markitdown", + "ocrmypdf": "ocrmypdf", + "docx2pdf": "docx2pdf", +} + +WINDOWS_PACKAGE_IMPORTS = { + "pywin32": "win32com.client", +} + +SYSTEM_DEPENDENCIES = { + "Tesseract OCR": ["tesseract"], + "Poppler": ["pdftoppm", "pdfinfo"], + "ffmpeg": ["ffmpeg"], +} + +WINDOWS_SYSTEM_DEPENDENCIES = { + "Microsoft Word": ["winword"], + "Microsoft PowerPoint": ["powerpnt"], +} + + +def requirements_path() -> Path: + return Path(__file__).with_name("requirements.txt") + + +def install_core_packages() -> None: + """安裝核心 pip 套件。""" + command = [sys.executable, "-m", "pip", "install", "-r", str(requirements_path())] + subprocess.check_call(command) + + +def validate_imports() -> dict[str, str]: + """回傳無法 import 的套件與錯誤訊息;空 dict 代表全部成功。""" + targets = dict(PACKAGE_IMPORTS) + if platform.system() == "Windows": + targets.update(WINDOWS_PACKAGE_IMPORTS) + + failures: dict[str, str] = {} + for package_name, import_name in targets.items(): + try: + importlib.import_module(import_name) + except Exception as exc: # noqa: BLE001 - 驗證工具需回報所有 import 失敗原因。 + failures[package_name] = f"{type(exc).__name__}: {exc}" + return failures + + +def check_system_dependencies() -> dict[str, list[str]]: + """檢查 PATH 上可找到的系統工具。""" + dependencies = dict(SYSTEM_DEPENDENCIES) + if platform.system() == "Windows": + dependencies.update(WINDOWS_SYSTEM_DEPENDENCIES) + + found: dict[str, list[str]] = {} + for dependency, commands in dependencies.items(): + found[dependency] = [command for command in commands if shutil.which(command)] + return found + + +def print_import_report() -> int: + failures = validate_imports() + if not failures: + print("全部核心 Python 套件匯入成功") + return 0 + + print("以下 Python 套件匯入失敗:") + for package_name, reason in failures.items(): + print(f"- {package_name}: {reason}") + return 1 + + +def print_system_report() -> int: + results = check_system_dependencies() + missing = [] + for dependency, commands in results.items(): + if commands: + print(f"{dependency}: 已找到 ({', '.join(commands)})") + else: + print(f"{dependency}: 未在 PATH 找到") + missing.append(dependency) + return 1 if missing else 0 + + +def main() -> int: + parser = argparse.ArgumentParser(description="教學檔案處理工具包安裝與驗證") + parser.add_argument( + "command", + choices=["install", "verify", "check-system"], + help="install 安裝核心套件;verify 驗證 import;check-system 檢查外部工具。", + ) + args = parser.parse_args() + + if args.command == "install": + install_core_packages() + return print_import_report() + if args.command == "verify": + return print_import_report() + if args.command == "check-system": + return print_system_report() + return 2 + + +if __name__ == "__main__": + raise SystemExit(main())