stagex/py-setuptools

python3-distutils-enhanced 镜像文档

镜像概述和主要用途

python3-distutils-enhanced 是一个基于 Python 3 的 Docker 镜像，集成了对标准库 distutils 的增强工具集合。该镜像旨在简化 Python 项目的构建、打包与分发流程，通过扩展 distutils 的原生功能，提供更高效、灵活的项目管理能力，适用于从简单脚本到复杂库的各类 Python 项目。

核心功能和特性

增强的打包能力

• 支持自动识别并包含项目数据文件（如配置模板、静态资源等），无需手动在 setup.py 中声明
• 内置依赖解析优化，可自动检测并处理项目依赖关系，减少手动维护 install_requires 的工作量
• 支持动态版本号生成（基于 Git 标签、文件哈希等），简化版本管理流程

简化的配置体验

• 提供精简的 setup.py 语法糖，支持 YAML/JSON 格式的配置文件（替代传统 setup.py 硬编码）
• 内置常用打包规则模板（如 CLI 工具、Web 应用、库项目等），减少重复配置工作

兼容性与工具集成

• 兼容 Python 3.6+ 版本，支持主流打包工具（setuptools、wheel、twine）
• 无缝集成 pip、tox、pytest 等开发工具，支持一站式构建-测试-分发流程
• 兼容 PyPI 及私有仓库（如 Azure Artifacts、GitLab Packages）的上传规范

性能与安全性优化

• 内置缓存机制，加速重复构建过程（缓存依赖包、编译结果等）
• 自动校验打包文件完整性，防止损坏或篡改的分发包生成

使用场景和适用范围

适用场景

• Python 项目开发：需快速配置复杂打包逻辑的项目（如多模块结构、跨平台分发）
• 开源库维护：需标准化分发流程（如自动生成 wheel/sdist 包、同步版本信息）
• 企业内部应用部署：统一 Python 项目构建标准，降低环境差异导致的分发问题
• 教学与演示：简化 Python 打包教学中的环境配置，聚焦核心逻辑讲解

适用范围

• 支持所有基于 distutils/setuptools 的 Python 项目
• 兼容主流操作系统（Linux x86_64/ARM64、macOS、Windows WSL2）
• 推荐用于 Python 3.6+ 项目，对 Python 2 项目不提供支持

使用方法和配置说明

获取镜像

通过 Docker Hub 拉取最新版本：

bash
docker pull docker.xuanyuan.run/python3-distutils-enhanced:latest

或从源码构建（需本地克隆镜像仓库）：

bash
git clone https://github.com/example/python3-distutils-enhanced.git
cd python3-distutils-enhanced
docker build -t python3-distutils-enhanced:local .

基本使用示例

1. 快速打包当前项目

将当前目录下的 Python 项目打包为 wheel 格式：

bash
docker run --rm -v $(pwd):/app -w /app docker.xuanyuan.run/python3-distutils-enhanced:latest \
  python -m setup bdist_wheel

• -v $(pwd):/app：挂载当前项目目录到容器内 /app 路径
• -w /app：设置工作目录为 /app
• python -m setup bdist_wheel：执行 wheel 打包命令（setup 为增强版打包入口）

2. 使用配置文件自定义打包规则

创建项目配置文件 distutils.yaml：

yaml
# distutils.yaml 示例
project:
  name: "myproject"
  version: "1.0.0"
  author: "Dev Team"
files:
  include:
    - "src/**/*.py"
    - "data/*.json"
  exclude:
    - "tests/**/*"
dependencies:
  install_requires:
    - "requests>=2.25.0"
    - "pyyaml>=5.4.0"

通过环境变量指定配置文件路径，执行打包：

bash
docker run --rm -v $(pwd):/app -w /app \
  -e DISTUTILS_CONFIG=/app/distutils.yaml \
  docker.xuanyuan.run/python3-distutils-enhanced:latest \
  python -m setup sdist

Docker Compose 配置示例

创建 docker-compose.yml，集成项目构建与测试流程：

yaml
version: "3.8"
services:
  build:
    image: docker.xuanyuan.run/python3-distutils-enhanced:latest
    volumes:
      - ./:/app  # 挂载项目目录
      - ./dist:/app/dist  # 持久化输出的包文件
    environment:
      - PYTHONPATH=/app  # 设置 Python 路径
      - DISTUTILS_CONFIG=/app/distutils.yaml  # 指定配置文件
      - PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple  # 国内 PyPI 镜像（可选）
    command: >
      sh -c "python -m setup bdist_wheel && 
             twine check dist/*"  # 打包后校验包完整性

启动服务执行构建：

bash
docker-compose up build

配置参数说明

环境变量

卷挂载建议

命令行参数（python -m setup）

注意事项

1. 项目需确保存在 setup.py 或配置文件（DISTUTILS_CONFIG 指定路径），否则会使用默认模板生成基础配置
2. 缓存目录 /root/.cache 为非持久化路径，若需保留缓存，建议通过卷挂载到宿主机
3. 动态版本号生成依赖 Git 环境，需确保项目目录包含 .git 仓库（或通过环境变量 VERSION 手动指定版本）