Python 項目入口點：__main__.py、腳本執行與包結構最佳實踐

直接回答

Python **無固定單一入口文件**，入口由**執行方式決定**：

• python main.py → main.py 是入口。
• python -m mypackage → mypackage/__main__.py 是入口。
• pip install . 生成 console_scripts → setup.py/pyproject.toml 指定的函數是入口。

標準項目結構推薦

myproject/
├── pyproject.toml          # 現代構建配置 (PEP 621)
├── README.md
├── src/
│   └── mypackage/
│       ├── __init__.py
│       ├── __main__.py     # `python -m mypackage` 入口
│       ├── cli.py          # 命令行解析 (argparse/click/typer)
│       ├── core.py         # 核心業務邏輯
│       └── utils.py
├── tests/
│   └── test_core.py
└── scripts/                # 可選：部署/運維腳本
    └── deploy.sh

關鍵文件內容示例

1. src/mypackage/__main__.py

# 當執行 `python -m mypackage` 時運行
from .cli import main

if __name__ == "__main__":
    main()

2. src/mypackage/cli.py

import argparse
from .core import run_task

def main():
    parser = argparse.ArgumentParser(description="My Awesome Project")
    parser.add_argument("input", help="輸入文件路徑")
    parser.add_argument("-o", "--output", help="輸出目錄")
    parser.add_argument("-v", "--verbose", action="store_true")
    args = parser.parse_args()

    run_task(args.input, args.output, args.verbose)

if __name__ == "__main__":
    main()

3. pyproject.toml (現代標準)

[build-system]
requires = ["setuptools>=61", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "myproject"
version = "0.1.0"
description = "Demo project structure"
authors = [{name = "You", email = "you@example.com"}]
license = {text = "MIT"}
readme = "README.md"
requires-python = ">=3.8"
dependencies = ["click", "requests"]

[project.optional-dependencies]
dev = ["pytest", "black", "ruff"]

[project.scripts]
mycli = "mypackage.cli:main"  # 安裝後生成 `mycli` 命令

[tool.setuptools.packages.find]
where = ["src"]

三種啟動方式對比

避坑指南

❌ 在包根目錄放 main.py 並 python main.py

導入包內模塊時需調整 sys.path，易出錯。

❌ 缺少 __main__.py 卻用 python -m mypackage

報錯 No module named __main__。

✅ 使用 src/ 佈局 (src layout)

防止「可導入但未安裝」的測試假陽性，強制通過安裝驗證導入。