一、關于Python項目結構
Python 項目并沒有完全統一的 “固定結構”，但行業內有一些廣泛遵循的約定俗成的目錄結構（尤其針對可分發的包或大型項目）。同時，確實有工具可以快速生成這些標準化結構，提高開發效率，這在實際開發中非常常見。
對于需要打包、發布或多人協作的項目，典型結構如下：
對于簡單腳本或小項目，結構可以簡化（例如只有?src/?目錄和幾個核心文件）。
二、快速生成項目結構的工具Cookiecutter
今天我們介紹一下最流行的項目模板工具Cookiecutter，支持通過模板快速生成標準化結構，不僅限于 Python。
Cookiecutter 是一個由?Audrey Roy Greenfeld（開源社區活躍開發者）發起并主導開發的開源項目，其核心維護團隊包括多位社區貢獻者，并非由特定商業公司作為 “發行人” 或 “ publisher ” 進行官方發布。
2.1、安裝cookiecutter
如果要安裝到虛擬化環境下，在虛擬化終端執行“pip install cookiecutter”命令：
2.2、調用標準模板
運行：cookiecutter https://github.com/audreyr/cookiecutter-pypackage（Python 包標準模板），前提是能訪問github。
提示：執行改命令要提前安裝了git，在宿主機上安裝即可，并將git.exe所在目錄添加到了path環境變量中。
如果已經創建過項目的話，cookiecutter會在本地創建緩存模板，這樣的話可以直接用本地的，用法有：
cookiecutter C:\Users\yourname\.cookiecutters\cookiecutter-pypackage
或者
cookiecutter cookiecutter-pypackage
系統會自動從默認的緩存路徑?~/.cookiecutters/?下去尋找名為?cookiecutter-pypackage?的模板。
如果長時間用本地的，模板源有更新了，可以在聯網時用下面的命令更新本地模板：
cookiecutter https://github.com/audreyfeldroy/cookiecutter-pypackage.git --overwrite-if-exists
下載的模板文件默認緩存在本地的如下目錄下：
2.3、創建項目結構
接下來根據模板要求一次輸入下面的full_name，可以是作者名稱，團隊名稱，git上的用戶名或者昵稱，依次輸入下面的名稱，：
各字段的含義，我列個表：
| 提示信息 | 含義 | 示例回答 | 重要性 |
|---|---|---|---|
full_name | 作者/維護者的全名（會寫入版權和作者信息） | Haitao Luo | ????? |
email | 作者的聯系郵箱 | your.email@example.com | ????? |
github_username | 您的 GitHub 用戶名 | your-github-username | ???? |
project_name | 項目的正式名稱（可以包含空格，給人看的） | My Awesome Project | ????? |
project_slug | 項目的短標識（用于包名、目錄名，電腦看的） | my_awesome_project | ????? |
pypi_username | 您在 PyPI 上的用戶名（如果打算發布） | your-pypi-username | ?? |
project_short_description | 項目的一句話簡短描述 | A Python package that does awesome things. | ???? |
version | 項目的初始版本號 | 0.1.0 | ??? |
use_pytest | 是否使用 pytest 作為測試框架 | y?(推薦) | ??? |
use_pypi_deployment_with_travis | 是否配置 Travis CI 自動發布到 PyPI | n?(除非您明確需要) | ? |
add_pyup_badge | 是否添加 Pyup 安全更新徽章 | n?(可選) | ? |
command_line_interface | 是否添加命令行接口（CLI） | Click?(推薦) 或?Argparse?或?No | ?? |
漏了一個pypi_package_name?就是您的包在“Python應用商店”（PyPI）里的“商品名”，需要獨一無二且便于用戶查找和安裝。
創建結束后可以看到左側樹上有了對應的項目結構，并在windows資源管理器查看：
Cookiecutter創建項目結構說明
1. 核心目錄
| 名稱 | 說明 |
|---|---|
src/ | 源代碼根目錄。這是現代 Python 打包（PyPA）推薦的結構。您的實際包（package）就在這里的某個文件夾下。這種結構可以避免無意中導入本地其他文件而非已安裝的包。 |
tests/ | 測試代碼目錄。存放所有單元測試和集成測試文件。通常與?src/?下的模塊結構一一對應（例如?src/mypackage/core.py?的測試文件是?tests/test_core.py）。 |
docs/ | 項目文檔目錄。通常使用 Sphinx 或 MkDocs 來構建項目的詳細文檔。 |
.github/ | GitHub 工作流配置。里面通常有?workflows/?文件夾，存放 GitHub Actions 的 YAML 配置文件，用于實現CI/CD（持續集成/持續部署），如自動運行測試、自動發布等。 |
2. 配置文件（關鍵文件）
| 名稱 | 說明 |
|---|---|
pyproject.toml | 現代Python項目的核心配置文件。取代了舊的?setup.py。它定義了項目構建依賴（如setuptools）、項目元數據（名稱、版本、作者）、以及各種工具（如pytest、black、flake8）的配置。這是最重要的文件之一。 |
LICENSE | 開源許可證。規定了他人使用您代碼的權利和義務。常見的有MIT、Apache 2.0、GPL等。 |
README.md | 項目首頁文檔。這是項目的門面，通常包含項目介紹、安裝方法、快速使用示例、貢獻指南等。在GitHub和PyPI上會直接顯示。 |
.gitignore | Git忽略規則。指定哪些文件或目錄不應該被納入版本控制（如虛擬環境?venv/、編譯緩存?__pycache__/、IDE配置等）。 |
MANIFEST.in | 打包附加文件清單。當構建分發包（sdist）時，pyproject.toml?可能不會自動包含所有非代碼文件（如文檔、靜態資源）。這個文件用來指明需要額外包含哪些文件。 |
.editorconfig | 編輯器配置。幫助在不同編輯器和IDE之間保持代碼風格（如縮進、字符集）的一致性。 |
3. 文檔與規范文件
| 名稱 | 說明 |
|---|---|
CODE_OF_CONDUCT.md | 行為準則。規定了社區交流合作的規范，為所有貢獻者創造一個友好的環境。 |
CONTRIBUTING.md | 貢獻指南。詳細說明如何為項目做貢獻，如如何提交Issue、如何拉取請求（Pull Request）、代碼風格要求等。 |
HISTORY.md | 更新日志。記錄每個版本的重大變更、新增功能和修復的Bug。 |
justfile | Just命令運行器配置。just?是一個類似?make?的命令運行工具，用于定義和管理項目常用的命令（如運行測試、構建文檔、格式化代碼等）。這是一個可選但很方便的工具。 |
需要注意的是，此時的venv虛擬化環境和通過cookiecutter創建的項目是同一目錄級別，這種情況下是一個虛擬化環境適配多個project，如果想做個項目隔離，那么venv虛擬化目錄在你創建的project里面，這個換一篇再介紹。
)
