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 开发者社区。