Python venv安装pi3d模块时缺失pointer.png文件问题排查

• pip安装到venv不是文件缺失的原因：虚拟环境仅用于隔离依赖环境，不会过滤包内的资源文件。
• --no-warn-script-location参数无法解决问题：该参数仅用于关闭脚本位置的警告提示，和资源文件是否被打包安装完全无关。
• 核心问题出在包的打包配置上，需检查以下配置文件：
  • 若使用setup.py，要在package_data中声明需包含的资源文件：

    from setuptools import setup, find_packages
    
    setup(
        # 其他配置项...
        packages=find_packages("src"),
        package_dir={"": "src"},
        package_data={
            "pi3d.util.icons": ["*.png"],
        },
    )
    

  • 若使用pyproject.toml（现代打包方式），需在对应区块配置：

    [tool.setuptools.package-data]
    "pi3d.util.icons" = ["*.png"]
    

  • 旧打包方式可能需要MANIFEST.in文件，添加规则：

    include src/pi3d/util/icons/*.png
    

• 此前无问题大概率是打包配置被误修改，或是升级setuptools等打包工具后，默认行为变化导致资源文件未被纳入分发包。
• 验证方式：本地将包打包成wheel或sdist文件，解压后检查是否包含pointer.png，确认配置生效后再重新上传到PyPI。

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