Fastmcp Proper

🚀 Python 最佳實踐指南

本指南旨在為 Python 開發者提供一系列最佳實踐，涵蓋項目初始化、代碼風格、測試、文檔編寫、依賴管理、包構建與發佈等方面，幫助開發者更高效地開發和管理 Python 項目。

🚀 快速開始

在開始編寫代碼之前，請運行以下命令以初始化新的 Python 項目：

python -m venv venv && source venv/bin/activate
pip install --upgrade pip setuptools wheel

這將創建一個虛擬環境並安裝必要的構建工具。

✨ 主要特性

• 遵循 PEP8 標準，保證代碼風格統一。
• 提供完整的項目結構示例，便於項目組織和管理。
• 涵蓋單元測試、測試覆蓋率測量等測試流程。
• 支持使用 Sphinx 創建項目文檔。
• 詳細介紹依賴管理、包構建與發佈的方法。
• 支持通過 GitHub Actions 實現自動化發佈。
• 遵循語義化版本控制標準。

📦 安裝指南

使用以下命令安裝項目依賴：

pip install -r requirements.txt

💻 使用示例

基礎用法

代碼風格示例

# 正確示例：
import os

def greet(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    name = input("請輸入你的名字：")
    print(greet(name))

單元測試示例

import unittest
from src.main import greet

class TestGreet(unittest.TestCase):
    def test_greet_with_name(self):
        self.assertEqual(greet("Alice"), "Hello, Alice!")

if __name__ == "__main__":
    unittest.main()

高級用法

測試覆蓋率測量

使用 coverage 工具來測量測試覆蓋率：

coverage run -m unittest tests/
coverage report

使用 Sphinx 創建文檔

# 1. 安裝 sphinx 和相關工具
pip install sphinx setuptools-sphinx
# 2. 在項目根目錄下創建文檔
cd project
sphinx-apidoc -o docs/ src/
# 3. 打開 docs/index.html 查看生成的文檔

📚 詳細文檔

代碼風格指南

基本原則

1. 遵循 PEP8 標準。
2. 確保代碼的可讀性和簡潔性。
3. 避免使用 from module import * 語句。

項目結構

推薦的項目目錄結構如下：

project/
├── src/
│   ├── __init__.py
│   └── main.py
├── tests/
│   ├── __init__.py
│   └── test_main.py
├── setup.py
└── pyproject.toml

測試指南

單元測試

使用 unittest 框架進行單元測試。創建一個 tests 目錄，並在其中編寫測試用例。

測試覆蓋率

使用 coverage 工具來測量測試覆蓋率。

文檔編寫

使用 sphinx 創建文檔

1. 安裝 sphinx 和相關工具。
2. 在項目根目錄下創建文檔。
3. 打開 docs/index.html 查看生成的文檔。

依賴管理

使用 requirements 文件

在項目根目錄下創建一個 requirements.txt 文件，列出所有依賴項。

包構建與發佈

環境準備

確保安裝了以下工具：

pip install build twine

打包步驟

1. 創建源分發和 wheel 包：

python -m build

2. 檢查生成的文件位於 dist/ 目錄下。

發佈到 TestPyPI 和 PyPI

使用 twine 上傳

1. 配置 PyPI 憑據，編輯 ~/.pypirc 文件。
2. 上傳到 TestPyPI。
3. 上傳到 PyPI。

使用 GitHub Actions 自動化發佈

創建 GitHub Actions 工作流文件 .github/workflows/publish.yml

name: 發佈到 PyPI

on:
  release:
    types: [created]

jobs:
  部署:
    runs-on: ubuntu-latest
    steps:
    - name: 檢出代碼庫
      uses: actions/checkout@v2
      
    - name: 設置虛擬環境並安裝依賴
      run: |
        python -m venv venv && source venv/bin/activate
        pip install --upgrade pip setuptools wheel
        
    - name: 打包項目
      run: python -m build

    - name: 上傳到 PyPI
      uses: twinebot/twine-action@v1
      with:
        twineUserName: ${{ secrets.PYPI_USERNAME }}
        twinePassword: ${{ secrets.PYPI_PASSWORD }}

創建倉庫 Secrets

在 GitHub Actions 中設置以下秘密：

• PYPI_USERNAME：PyPI 用戶名
• PYPI_PASSWORD：PyPI 密碼

語義化版本控制 (Semantic Versioning)

遵循 SemVer 標準，格式為 MAJOR.MINOR.PATCH。

示例版本號含義

• 1.0.0: 初始發佈
• 2.3.1: 功能改進和錯誤修復
• 2.4.0: 新功能添加
• 3.0.0: 重大更新或不向後兼容的更改

最佳實踐總結

1. 遵循 PEP8 編碼規範。
2. 使用虛擬環境管理依賴。
3. 保持代碼簡潔和可維護性。
4. 編寫充分的測試用例。
5. 使用文檔工具記錄項目。
6. 正確配置依賴管理。
7. 定期更新項目版本。
8. 通過 CI/CD 實現自動化發佈。

如需進一步瞭解，請參考 Python 官方文檔 或加入 Python 開發者社區。