如何正确打包可调用Python脚本/模块并解决分发异常

我来一步步帮你搞定这些问题，从项目结构调整到打包配置修复，再到最终让终端用户能顺畅调用你的脚本。

一、先搞定子目录导入失败的问题 #

你提到把脚本放进子目录后，无法从data子目录导入模块，核心是要让项目结构符合Python包的规范，同时调整导入方式：

调整后的规范项目结构 #

先把data目录放到formatter包内部（让它成为子包），结构如下：

MyProject/
├── formatter/
│   ├── __init__.py       # 空文件也行，标记这是Python包
│   ├── __main__.py
│   ├── formatter.py
│   ├── addfilename.py
│   ├── addscrapertype.py
│   └── data/
│       ├── __init__.py
│       ├── helper.py
│       └── csv_formatter.py
├── README.md
├── MANIFEST.in
└── setup.py

修正导入语句 #

在包内的脚本里，用绝对导入（推荐）或者相对导入来调用子模块：

• 绝对导入示例（比如在csv_formatter.py里导入formatter.main）：

  from formatter.formatter import main
  from formatter.data.helper import xxx_function
  

• 相对导入示例（同一包内的文件互相调用）：

  from ..formatter import main
  from .helper import xxx_function
  

这样不管脚本放在哪个目录，只要包结构正确，导入就不会出错。

二、修复setup.py的几个关键错误 #

你遇到的README.md找不到、formatter目录不存在、命令调用失败这几个问题，逐个解决：

1. 解决“README.md不存在”的报错 #

如果你的README.md确实在项目根目录，做两个操作兜底：

• 给MANIFEST.in添加正确的文件包含规则：

  include README.md
  include *.csv *.rst *.txt
  recursive-include formatter/data *.py *.csv
  

• 在setup.py里增加异常捕获，避免找不到README导致打包失败：

  try:
      with open("README.md", "r") as fh:
          long_description = fh.read()
  except FileNotFoundError:
      long_description = "A package for cleaning and reformatting csv data"
  

2. 解决“package directory 'formatter' does not exist”的报错 #

这个错误大概率是你没在项目根目录运行打包命令。请确保：

• 打开终端，进入MyProject文件夹（就是包含setup.py的那个目录）
• 确认formatter目录存在，并且里面有__init__.py文件（哪怕是空的）

3. 修复console_scripts的命令调用问题 #

你现在的entry_points只配置了formatter命令，但用户需要调用addfilename，所以要把所有需要暴露的命令都加进去：

entry_points={
    "console_scripts": [
        "formatter=formatter.formatter:main",
        "addfilename=formatter.addfilename:main",  # 注意：addfilename.py里必须有main()函数作为入口
        "addscrapertype=formatter.addscrapertype:main"  # 同理，每个命令对应一个脚本的main函数
    ]
},

重要提醒：每个要作为命令调用的脚本（比如addfilename.py），必须定义一个main()函数，作为命令执行的入口逻辑。

4. 正确包含data子目录的文件 #

因为data是formatter的子包，所以调整package_data配置：

package_data={
    "formatter.data": ["*.csv"],  # 如果data里有csv等资源文件需要打包，就这么写
},

配合MANIFEST.in的规则，确保打包时不会遗漏子目录的文件。

另外，把setup.py里的packages=["formatter"]改成packages=setuptools.find_packages()，它会自动发现所有包含__init__.py的包（包括formatter.data），比手动写更可靠。

三、正确的打包与测试流程 #

完成上述调整后，按以下步骤操作：

1. 进入MyProject根目录
2. 生成打包文件：python setup.py sdist（会在dist目录下生成tar.gz包）
3. 用虚拟环境测试安装（避免干扰全局环境）：
   • 创建虚拟环境：python -m venv myenv
   • 激活虚拟环境：
     • Windows：myenv\Scripts\activate
     • Linux/Mac：source myenv/bin/activate
   • 安装包：pip install dist/formatter-1.0.1.tar.gz
4. 测试命令：
   • 运行formatter "你的参数"
   • 运行addfilename "C:\Users\Username\Desktop\Python Scripts\"

四、额外注意事项 #

• 所有依赖库都要列在install_requires里，比如你已经加了pandas，如果还有其他库也要补上
• Windows用户测试时，确保虚拟环境的Scripts目录在系统PATH里，这样才能直接调用命令
• 如果想支持python -m formatter运行，要在__main__.py里写入口逻辑，比如：

  from .formatter import main
  if __name__ == "__main__":
      main()
  

内容的提问来源于stack exchange，提问作者BLitE.exe