Python项目安装时自动解压数据文件的实现方案

要在Poetry管理的Python项目中分发压缩的大文件并在安装时自动解压，你可以通过自定义setup.py配合setuptools的安装钩子实现，具体步骤如下：

1. 项目结构调整 #

把压缩后的大文件（比如large_data.zip或large_data.gz）放到你的Python包目录下的子文件夹中，示例结构：

my_project/
├── my_project/
│   ├── __init__.py
│   ├── data/
│   │   └── large_data.zip  # 你的压缩数据文件
│   └── core/
│       └── ...  # 项目代码
├── pyproject.toml
└── setup.py

2. 配置pyproject.toml #

修改pyproject.toml，切换到setuptools构建系统，并确保压缩文件被包含在发行包中：

[tool.poetry]
name = "my-project"
version = "0.1.0"
authors = ["Your Name <your@email.com>"]
packages = [{ include = "my_project" }]  # 自动包含包内所有文件，包括data下的压缩包

[tool.poetry.dependencies]
python = "^3.8"

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

3. 编写自定义setup.py #

创建setup.py文件，重写安装命令，在安装完成后自动解压压缩包并清理原压缩文件：

import os
import zipfile
from setuptools import setup
from setuptools.command.install import install

class PostInstallUnzip(install):
    def run(self):
        # 先执行默认安装流程
        install.run(self)
        
        # 定位安装后的压缩包路径（替换为你的实际包名和文件路径）
        package_data_dir = os.path.join(self.install_lib, "my_project", "data")
        zip_file_path = os.path.join(package_data_dir, "large_data.zip")
        
        # 解压文件到目标目录
        with zipfile.ZipFile(zip_file_path, "r") as zip_ref:
            zip_ref.extractall(package_data_dir)
        
        # 可选：删除原压缩包以节省空间
        os.remove(zip_file_path)

# 如果是gzip格式，替换为以下解压逻辑：
# import gzip
# import shutil
# with gzip.open(zip_file_path, 'rb') as f_in:
#     with open(os.path.join(package_data_dir, "large_data"), 'wb') as f_out:
#         shutil.copyfileobj(f_in, f_out)
# os.remove(zip_file_path)

setup(
    cmdclass={"install": PostInstallUnzip}
)

4. 打包与测试 #

• 执行poetry build生成发行包：sdist格式的.tar.gz文件会保留压缩的数据源，pip安装时会触发解压逻辑；wheel格式的.whl会在构建阶段完成解压，最终包内是解压后的文件。
• 测试安装：创建虚拟环境后运行pip install dist/my-project-0.1.0.tar.gz，安装完成后检查site-packages/my_project/data目录，确认已解压出目标文件。

关键注意事项 #

• Wheel包的局限性：如果分发wheel包，构建过程中会执行解压逻辑，最终wheel包内是解压后的文件（不符合你"分发压缩文件"的需求）。如果必须分发压缩状态的文件，建议优先提供sdist包。
• 跨平台兼容：代码中使用os.path处理路径，确保在Windows、Linux、macOS下都能正常工作。
• 权限问题：解压后的文件权限会继承压缩包的设置，若有特殊权限需求，可在解压后手动调整。

内容的提问来源于stack exchange，提问作者deanj