seven45/pdm-ci

pdm-ci Docker镜像文档

1. 镜像概述

pdm-ci 是一个集成了 https://github.com/pdm-project/pdm%EF%BC%88Python 包管理器）的 Docker 镜像，旨在简化 Python 项目的依赖管理、构建流程及持续集成（CI）配置。该镜像版本命名规则与官方 Python 镜像保持一致（如 3.10、3.10-alpine、3.10-slim 等），便于用户根据项目需求选择匹配的 Python 版本。

2. 核心功能与特性

• 集成 PDM 包管理器：内置 PDM，支持 Python 项目的依赖解析、安装、打包等全流程包管理。
• 多阶段构建支持：优化 Docker 镜像构建流程，通过多阶段构建分离依赖安装与应用部署，减小最终镜像体积。
• CI 流程适配：提供开箱即用的 CI 配置示例，支持代码 linting、测试、覆盖率分析等自动化流程。
• 动态版本控制：支持从文件读取版本信息，实现项目版本的动态管理。
• 版本对齐：版本命名与官方 Python 镜像一致（如 3.10、3.10-alpine），确保环境一致性。

3. 适用场景

• Python 项目 Docker 化构建：通过多阶段构建简化 Python 应用的容器化流程。
• 持续集成/持续部署（CI/CD）：在 CI 环境（如 GitLab CI、GitHub Actions 等）中统一依赖管理、代码检查与测试流程。
• 开发环境一致性：确保团队成员及 CI 环境使用相同版本的 PDM 和 Python，避免“本地正常，CI 失败”的环境差异问题。

4. 使用方法

4.1 项目结构

推荐的项目目录结构如下（my_project 为工作目录）：

my_project/
├── src/                # 源代码目录
│   ├── __init__.py
│   ├── __main__.py     # 应用入口
│   └── ...（其他源码文件/文件夹）
├── tests/              # 测试代码目录
├── Dockerfile          # Docker 构建配置
├── pdm.lock            # PDM 依赖锁定文件
├── pyproject.toml      # PDM 项目配置文件
└── README.md           # 项目说明文档

4.2 Python 多阶段构建

通过多阶段构建，可在构建阶段使用 pdm-ci 镜像安装依赖，再将依赖复制到轻量的官方 Python 镜像中，优化最终镜像体积。

Dockerfile 示例：

dockerfile
# 定义 Python 版本，默认 3.10
ARG PYTHON_VERSION=3.10

# 第一阶段：使用 pdm-ci 镜像安装依赖
FROM docker.xuanyuan.run/seven45/pdm-ci:$PYTHON_VERSION as pdm
WORKDIR /project
# 复制依赖配置文件
COPY pyproject.toml pdm.lock /project/
# 创建虚拟环境（--copies 确保依赖文件复制而非链接）
RUN python -m venv --copies .venv
# 安装生产依赖（--prod：仅生产依赖；--no-self：不安装项目本身；--no-lock：信任 pdm.lock；--no-editable：非编辑模式）
RUN pdm install --prod --no-self --no-lock --no-editable

# 第二阶段：构建最终运行镜像
FROM docker.xuanyuan.run/python:$PYTHON_VERSION
WORKDIR /project
# 从构建阶段复制虚拟环境
COPY --from=pdm /project/.venv /project/.venv
# 将虚拟环境 bin 目录添加到 PATH，确保可直接调用依赖命令
ENV PATH="/project/.venv/bin:$PATH"
# 复制源代码
COPY src /project/src
# 启动命令：执行应用入口
CMD ["python", "src/__main__.py"]

4.3 持续集成配置

4.3.1 PDM 配置（pyproject.toml）

在 pyproject.toml 中配置开发依赖（如测试、lint 工具）及 PDM 脚本，实现 CI 流程自动化。

示例配置：

toml
[project]
name = "my_project"
description = "A Python project managed by PDM"
# 其他项目元信息...

[tool.pdm.dev-dependencies]
# 测试依赖
testing = ["pytest-cov>=4.0.0"]
# Lint 依赖
linting = [
    "setuptools>=65.6.3",          # 基础工具
    "black>=22.12.0",              # 代码格式化
    "isort>=5.11.4",               # 导入排序
    "flake8-pyproject>=1.2.2"      # 代码检查（支持 pyproject.toml 配置）
]

[tool.pdm.scripts]
# 本地 lint（格式化并检查）
lint = {composite = ["black src tests", "isort src tests", "flake8p src tests"]}
# CI 环境 lint（仅检查，不修改文件）
lint_check = {composite = ["black src tests --check", "isort src tests --check-only", "flake8p src tests"]}
# 基础测试
test = "pytest -vvv -s tests"
# 带覆盖率的测试（生成 coverage.xml）
test_cov = "pytest --cov-branch --cov-report=xml --cov=src tests"
# 指定文件测试（接收参数）
test_file = "pytest -s -vv ./{args}"
# 运行所有测试和 lint 检查
test_all = {composite = ["test", "lint_check"]}

4.3.2 CI 流程配置（以 GitLab CI 为例）

在 .gitlab-ci.yml 中定义 CI 阶段（如 lint、测试），使用 pdm-ci 镜像执行自动化任务。

示例配置：

yaml
stages:
  - lint       # 代码检查阶段
  - test       # 测试阶段

# Lint 任务
linters:
  stage: lint
  image: docker.xuanyuan.run/seven45/pdm-ci:3.10-alpine  # 使用 alpine 版本减小 CI 镜像拉取体积
  only: [ "merge_requests" ]         # 仅在合并请求时触发
  script:
    - pdm install --no-default -G linting  # 安装 linting 分组的开发依赖
    - pdm run lint_check                   # 执行 lint 检查（不修改文件）

# 测试任务
pytest:
  stage: test
  image: docker.xuanyuan.run/seven45/pdm-ci:3.10-slim   # 使用 slim 版本平衡体积与功能
  only: [ "merge_requests" ]
  script:
    - pdm install -dG testing       # 安装 testing 分组的开发依赖（-d：开发依赖）
    - pdm run test_cov              # 执行带覆盖率的测试
  coverage: '/(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/'  # 解析覆盖率报告
  artifacts:
    paths:
      - coverage.xml  # 保存覆盖率报告作为产物

5. 扩展用法：动态版本控制

通过配置 pyproject.toml，可从文件中读取项目版本，实现动态版本管理（无需手动修改 pyproject.toml 中的版本字段）。

5.1 版本文件配置

在 src/__version__.py 中定义版本：

python
__version__ = "0.1.0"  # 项目版本号

5.2 PDM 配置调整

在 pyproject.toml 中添加以下配置，指定版本来源为文件：

toml
[project]
# 标记 version 为动态字段（从外部源获取）
dynamic = ["version"]

[tool.pdm]
build = {includes = ["src"]}  # 构建时包含 src 目录
version = { source = "file", path = "src/__version__.py" }  # 版本来源：文件路径

配置后，PDM 将自动从 src/__version__.py 读取 __version__ 变量作为项目版本，支持 pdm build 等命令使用动态版本号。