从源码到Docker全方位解析Python项目打包完整指南

# setup.py - 基础配置
from setuptools import setup, find_packages

setup(
    name="myproject",
    version="1.0.0",
    author="Your Name",
    author_email="your.email@example.com",
    description="A sample Python project",
    long_description=open("README.md").read(),
    long_description_content_type="text/markdown",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
    classifiers=[
        "Development Status :: 3 - Alpha",
        "Intended Audience :: Developers",
        "License :: OSI Approved :: MIT License",
        "Programming Language :: Python :: 3",
        "Programming Language :: Python :: 3.8",
        "Programming Language :: Python :: 3.9",
        "Programming Language :: Python :: 3.10",
    ],
    python_requires=">=3.8",
    install_requires=[
        "requests>=2.25.0",
        "click>=8.0.0",
    ],
    entry_points={
        "console_scripts": [
            "myproject=mypackage.main:main",
        ],
    },
)

# setup.cfg - 现代配置方式
[metadata]
name = myproject
version = 1.0.0
author = Your Name
author_email = your.email@example.com
description = A sample Python project
long_description = file: README.md
long_description_content_type = text/markdown
url = https://github.com/username/myproject
classifiers =
    Development Status :: 3 - Alpha
    Intended Audience :: Developers
    License :: OSI Approved :: MIT License
    Programming Language :: Python :: 3
    Programming Language :: Python :: 3.8
    Programming Language :: Python :: 3.9
    Programming Language :: Python :: 3.10

[options]
packages = find:
package_dir =
    = src
python_requires = >=3.8
install_requires =
    requests>=2.25.0
    click>=8.0.0

[options.packages.find]
where = src

[options.entry_points]
console_scripts =
    myproject = mypackage.main:main

# 安装构建工具
pip install build

# 构建源码包和wheel包
python -m build

# 或者使用传统方式
python setup.py sdist bdist_wheel

# 安装到当前环境（开发模式）
pip install -e .

# 清理构建文件
python setup.py clean --all
rm -rf build dist *.egg-info

# 创建新项目
poetry new myproject
cd myproject

# 或在现有项目初始化
poetry init

# pyproject.toml - Poetry配置
[tool.poetry]
name = "myproject"
version = "1.0.0"
description = "A sample Python project"
authors = ["Your Name <your.email@example.com>"]
readme = "README.md"
license = "MIT"

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.25.0"
click = "^8.0.0"

[tool.poetry.dev-dependencies]
pytest = "^7.0.0"
black = "^22.0.0"
flake8 = "^4.0.0"

[tool.poetry.scripts]
myproject = "myproject.main:main"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

# 可选：工具配置
[tool.black]
line-length = 88
target-version = ['py38']

[tool.pytest.ini_options]
testpaths = ["tests"]

# 安装依赖
poetry install

# 添加依赖
poetry add requests
poetry add --dev pytest

# 构建项目
poetry build

# 发布到PyPI
poetry publish

# 运行脚本
poetry run myproject

# 进入虚拟环境
poetry shell

# 初始化项目
pdm init

# 添加依赖
pdm add requests click
pdm add -d pytest black

[project]
name = "myproject"
version = "1.0.0"
description = "A sample Python project"
authors = [
    {name = "Your Name", email = "your.email@example.com"}
]
dependencies = [
    "requests>=2.25.0",
    "click>=8.0.0"
]
requires-python = ">=3.8"

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=22.0.0"
]

[project.scripts]
myproject = "myproject.main:main"

[build-system]
requires = ["pdm-backend"]
build-backend = "pdm.backend"

# 安装依赖
pdm install

# 构建项目
pdm build

# 运行脚本
pdm run myproject

# 锁定依赖
pdm lock

# build_spec.py - PyInstaller构建配置
import PyInstaller.__main__

PyInstaller.__main__.run([
    'src/mypackage/main.py',
    '--name=myproject',
    '--onefile',  # 单文件打包
    '--windowed',  # 无控制台窗口（GUI应用）
    '--add-data=src/mypackage/data;mypackage/data',  # 包含数据文件
    '--icon=assets/icon.ico',  # 应用图标
    '--hidden-import=some_hidden.module',  # 隐藏导入
    '--clean',  # 清理临时文件
])

# 命令行方式
pyinstaller src/mypackage/main.py --onefile --name myproject

# 使用spec文件
pyinstaller myproject.spec

# setup_cxfreeze.py
import sys
from cx_Freeze import setup, Executable

build_exe_options = {
    "packages": ["os", "sys", "requests"],
    "excludes": ["tkinter"],
    "include_files": ["data/", "config.ini"],
}

base = None
if sys.platform == "win32":
    base = "Win32GUI"  # 用于GUI应用

setup(
    name="myproject",
    version="1.0.0",
    description="My Python Application",
    options={"build_exe": build_exe_options},
    executables=[Executable("src/mypackage/main.py", base=base)],
)

# 第一阶段：构建阶段
FROM python:3.9-slim as builder

WORKDIR /app

# 安装构建依赖
RUN apt-get update && apt-get install -y \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# 创建虚拟环境
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# 安装依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 第二阶段：运行阶段
FROM python:3.9-slim

WORKDIR /app

# 创建非root用户
RUN groupadd -r appuser && useradd -r -g appuser appuser

# 从构建阶段拷贝虚拟环境
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# 拷贝应用代码
COPY --chown=appuser:appuser . .

# 切换到非root用户
USER appuser

# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["python", "-m", "mypackage.main"]

# 使用多阶段构建优化镜像大小
FROM python:3.9-slim as builder

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# 安装Poetry
RUN pip install poetry

# 配置Poetry不创建虚拟环境
RUN poetry config virtualenvs.create false

# 拷贝依赖文件
COPY pyproject.toml poetry.lock* ./

# 安装依赖（仅运行时）
RUN poetry install --no-dev --no-interaction --no-ansi

# 运行阶段
FROM python:3.9-slim

WORKDIR /app

# 创建非root用户
RUN groupadd -r appuser && useradd -r -g appuser appuser

# 从构建阶段拷贝已安装的包
COPY --from=builder /usr/local/lib/python3.9/site-packages /usr/local/lib/python3.9/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin

# 拷贝应用代码
COPY --chown=appuser:appuser . .

USER appuser

# 设置环境变量
ENV PYTHONPATH=/app
ENV PYTHONUNBUFFERED=1

EXPOSE 8000

CMD ["python", "-m", "mypackage.main"]

# docker-compose.yml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/myapp
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      - db
      - redis
    networks:
      - app-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  db:
    image: postgres:13
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - app-network

  redis:
    image: redis:6-alpine
    volumes:
      - redis_data:/data
    networks:
      - app-network

volumes:
  db_data:
  redis_data:

networks:
  app-network:
    driver: bridge

# 基础编译
nuitka3 --standalone --onefile src/mypackage/main.py

# 优化版本
nuitka3 \
    --standalone \
    --onefile \
    --enable-plugin=pyqt5 \
    --include-package-data=mypackage \
    --output-filename=myapp \
    src/mypackage/main.py

# Windows特定优化
nuitka3 --windows-icon-from-ico=assets/icon.ico src/mypackage/main.py

#!/bin/bash
# build.sh - Python项目自动构建脚本

set -e

echo "🚀 开始构建Python项目..."

# 清理构建目录
echo "🧹 清理构建文件..."
rm -rf build/ dist/ *.egg-info/ .pytest_cache/ __pycache__/
find . -name "*.pyc" -delete

# 代码检查
echo "🔍 运行代码检查..."
python -m flake8 src/
python -m black --check src/
python -m isort --check-only src/

# 运行测试
echo "🧪 运行测试..."
python -m pytest tests/ -v

# 构建包
echo "📦 构建分发包..."
python -m build

# 构建Docker镜像
echo "🐳 构建Docker镜像..."
docker build -t myproject:latest .

echo "✅ 构建完成！"
echo "📦 分发包位置: dist/"
echo "🐳 Docker镜像: myproject:latest"

# .github/workflows/ci-cd.yml
name: Python CI/CD

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.8, 3.9, 3.10]

    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v3
      with:
        python-version: ${{ matrix.python-version }}
        cache: 'pip'
        
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -e .[dev]
        
    - name: Lint with flake8
      run: |
        flake8 src/ tests/ --count --show-source --statistics
        
    - name: Test with pytest
      run: |
        pytest tests/ -v
        
  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Build and push Docker image
      run: |
        echo ${{ secrets.DOCKER_PASSWORD }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
        docker build -t myproject:${{ github.sha }} .
        docker push myproject:${{ github.sha }}

# pyproject.toml - 依赖管理示例
[project]
dependencies = [
    "requests>=2.25.0,<3.0.0",  # 版本范围
    "click>=8.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=22.0.0",
    "flake8>=4.0.0",
]
test = [
    "pytest>=7.0.0",
    "pytest-cov>=3.0.0",
]
docs = [
    "sphinx>=4.0.0",
    "sphinx-rtd-theme>=1.0.0",
]

# 安全加固的Dockerfile
FROM python:3.9-slim

# 安全更新
RUN apt-get update && apt-get upgrade -y && rm -rf /var/lib/apt/lists/*

# 创建非特权用户
RUN groupadd -r appuser && useradd -r -g appuser -s /bin/false appuser

# 应用适当的文件权限
RUN chown -R appuser:appuser /app
USER appuser

# 使用可信的基础镜像
# 定期更新依赖
# 扫描安全漏洞

# 优化版Dockerfile
FROM python:3.9-slim

# 使用国内镜像源加速
RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 禁用缓存和pip版本检查
ENV PIP_NO_CACHE_DIR=1
ENV PIP_DISABLE_PIP_VERSION_CHECK=1

# 优化Python设置
ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1