Python 最佳实践指南

项目初始化

在开始编写代码之前，请运行以下命令以初始化新的 Python 项目：

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

这将创建一个虚拟环境并安装必要的构建工具。

代码风格指南

基本原则

1. 遵循 PEP8 标准。
2. 确保代码的可读性和简洁性。
3. 避免使用 from module import * 语句。

示例代码

# 正确示例：
import os

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

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

项目结构

推荐的项目目录结构如下：

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

测试指南

单元测试

使用 unittest 框架进行单元测试。创建一个 tests 目录，并在其中编写测试用例。

示例测试代码

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 查看生成的文档。

依赖管理

使用 requirements 文件

在项目根目录下创建一个 requirements.txt 文件，列出所有依赖项：

setuptools>=60.0.0
wheel>=0.37.1

包构建与发布

环境准备

确保安装了以下工具：

pip install build twine

打包步骤

1. 创建源分发和 wheel 包：

   python -m build
   

2. 检查生成的文件位于 dist/ 目录下。

发布到 TestPyPI 和 PyPI

使用 twine 上传

1. 配置 PyPI 凭据，编辑 ~/.pypirc 文件：

[distutils]
index-servers = pypi testpypi

[pypi]
username = your_username
password = your_password

[testpypi]
username = your_test_username
password = your_test_password

2. 上传到 TestPyPI：

   twine upload --repository testpypi dist/*
   

3. 上传到 PyPI：

   twine upload dist/*
   

使用 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: 重大更新或不向后兼容的更改

安装依赖

使用以下命令安装项目依赖：

pip install -r requirements.txt

最佳实践总结

1. 遵循 PEP8 编码规范。
2. 使用虚拟环境管理依赖。
3. 保持代码简洁和可维护性。
4. 编写充分的测试用例。
5. 使用文档工具记录项目。
6. 正确配置依赖管理。
7. 定期更新项目版本。
8. 通过 CI/CD 实现自动化发布。

如需进一步了解，请参考 Python 官方文档 或加入 Python 开发者社区。