保持Python项目良好运行的方法

来源：撰写人

你是不是已经按照我之前文章中提到的最佳做法开始了你的Python项目，对吗？

现在，是时候专注于保持你的项目井井有条、功能正常、易于分享和扩展性好了。

requirements.txt 文件列出了你的项目运行所需的所有依赖项。此文件让其他人可以复现你的运行环境，并在自动化流程中使用。

• 使用以下命令来生成文件

pip freeze > requirements.txt
# 将已安装的包列表输出到requirements.txt文件

• 要从文件中安装依赖项，可以使用：

    pip install -r requirements.txt

（此命令用于安装requirements.txt文件中列出的所有包）

一个文档齐全的项目通常不会出现这种情况。

• 项目简介
• 安装指南及运行说明
• 使用案例
• 贡献指南 开源

• 安装 MkDocs，

pip install mkdocs  

# 或者  

poetry add mkdocs

• 创建一个文档项目：

运行命令 mkdocs new 项目文档

mkdocs new 项目文档

• 可以这样运行网站：

    cd project-docs  
    mkdocs serve 

切换到project-docs目录并启动mkdocs服务。

• 部署到GitHub Pages：

    mkdocs gh-deploy

注释：此命令用于将mkdocs项目部署到GitHub Pages。

现在你将拥有一个详细记录的项目。

预提交钩子（pre-commit hooks）会在更改被提交之前自动执行检查。

这能帮你节省大量时间，并通过避免常见错误来提升代码质量。

• 安装 Pre-commit 可以通过：

：

在命令行中输入以下命令来安装 pre-commit 工具:

pip install pre-commit

• 添加一个 . pre-commit-config.yaml 文件，该文件包含用于处理诸如修复尾随空格或代码格式检查之类的任务的钩子。

    repos:  
      - repo: https://github.com/pre-commit/pre-commit-hooks  
        rev: v4.4.0   
        hooks:  
          - id: check-yaml # check-yaml: 确保 YAML 文件有效。  
          - id: end-of-file-fixer # end-of-file-fixer: 确保文件末尾有一个换行符。  
          - id: trailing-whitespace # trailing-whitespace: 从文件中删除多余的空格。  
          - id: debug-statements # debug-statements: 警告未删除的 print() 或 pdb 语句。  
      - repo: https://github.com/psf/black  
        rev: 23.9.1   
        hooks:  
          - id: black # black: 根据 Black 代码规范格式化 Python 代码。  
            language_version: python3

• 使用以下命令或方法安装挂钩：

    pre-commit install

• 测试预提交钩子的功能：

pre-commit run --all-files
```运行所有文件的预提交检查：`pre-commit run --all-files`

* 预计的回报。

(venv) PS C:\WVS\project-docs> pre-commit run --all-files  
检查 YAML 文件内容 ........................................................... 通过  
修复文件末尾 ................................................................ 通过  
删除多余的空格 ..................................................... 通过  
调试 Python 语句 ...................................................... 通过  
black 代码美化 ................................................................ 通过

现在，每次提交都会自动运行这些检查。

#四 Docker

如果你用 requirements.txt 文件共享项目，也可以试试用 Docker 来共享项目。

让所有项目首先使用Docker，因为这是确保他人能轻松在他们的机器上运行这些项目的最有效方法。

当然，这确保了在开发和测试过程中的环境一致性。

以下是步骤：

* 创建一个名为 _Dockerfile_ 的文件，定义项目所需的环境和依赖项。

# 使用官方 Python 3.12-slim 镜像作为基础镜像  
FROM python:3.12-slim  

# 设置工作目录为 /app  
WORKDIR /app  

# 复制需求文件并安装依赖项  
COPY requirements.txt .  
RUN pip install --no-cache-dir -r requirements.txt  

# 复制应用程序代码到容器中  
COPY src/ ./src/  

# 暴露容器的 5000 端口  
EXPOSE 5000  

# 设置默认命令来运行应用程序  
CMD ["gunicorn", "--bind", "0.0.0.0:5000", "src.app:app"]

* 构建 Docker 图像。:

docker build -t api .  # 构建名为api的Docker镜像

* 来试试运行 Docker 实例吧：（命令或步骤）

docker run -p 5000:5000 --env-file .env api

运行 Docker 容器并将端口 5000 映射到主机上的 5000 端口。这里的 `docker run` 命令用于启动 Docker 容器，`--env-file .env` 表示使用 `.env` 文件中的环境变量，`api` 是要运行的容器名称。

**小技巧:** 如有必要，添加一个 _.dockerignore_ 文件以避免不必要的文件被复制到 Docker 镜像中。

# 5\. 测试驱动开发（TDD）。

在开始实现功能之前，我们先编写测试，这就是测试驱动开发（TDD，即测试驱动开发，Test-Driven Development）。

你可以写一些测试来模拟某些操作，而不是自己手动测试。

## 步骤如下：

* 安装测试所需的依赖项。

pip install pytest  # pytest 是一个用于 Python 的测试框架

# 或者说

poetry add pytest  # poetry 是一个 Python 依赖管理工具

* 创建一个名为_tests/的目录
* 这里是一个来自我代码的例子：

import sys  
import os  
import pytest  

# 将 'src' 目录添加到 Python 路径  
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '../src')))  

from app import app  

@pytest.fixture  
def client():  
    app.config['TESTING'] = True  
    with app.test_client() as test_client:  
        yield test_client  

def test_api_is_up(client):  
    # 发送一个 GET 请求到根端点  
    response = client.get('/')  

    # 响应的状态码应为 200 (OK)  
    assert response.status_code == 200

* 用 _pytest_ 运行测试：

pytest

* 预期收益:

=========================================== 测试会话开始于 ===========================================  
平台 win32 -- Python 3.11.5, pytest-8.3.3, pluggy-1.5.0  
根目录: C:\wvs\api  
配置文件: pyproject.toml  
扩展: flask-1.3.0  
收集到 1 项测试  

tests\test_app.py .                                                                                  [100%]  

============================================ 1 项通过，耗时 0.31 秒 ============================================

# 6. CI/CD（持续集成和持续交付）

CI/CD 自动化了像测试和部署代码这样的步骤。

当然测试是必要的，但让 CI/CD 管道自动为你完成测试和部署。

## 步骤如下：

* 创建一个配置文件，例如 _.github/workflows/pipeline.yml_:

 name: Python Only CI    

on:   
  push:  
    branches:  
      - main  
  pull_request:  
    branches:  
      - main    

jobs:    
  build:    
    runs-on: ubuntu-latest    

    steps:    
    - uses: actions/checkout@v3    

    - name: 配置 Python    
      uses: actions/setup-python@v4    
      with:    
        python-version: '3.12'    

    - name: 安装依赖项    
      run: pip install -r requirements.txt    

    - name: 运行单元测试    
      run: pytest   

这保证了每次代码被推送或有拉取请求时，测试会自动执行。

通过遵循这些实践，你可以确保项目显得更加专业。

不过，别在这里停下来，每一个我提到的话题都有一个全新的世界等着你来探索。

这两篇文章只是简单介绍了你能够达成的成就。

走了走了，拜拜！

[_行动起来，做需要去做的事情_](https://linktr.ee/lorenzo_uriel)