基于Hatchling的Python命令行应用PyPI打包配置疑问

问题1：安装时生成的.exe文件机制确认 #

你推测的完全正确，.exe文件不会出现在分发的*.tar.gz源包中，它是pip安装过程中由Hatchling、setuptools这类打包后端动态生成的启动器文件。

具体机制细节：

• *.tar.gz属于源分发包，仅包含项目源码、配置文件等原始内容，不会包含预编译的可执行文件。
• 当pip执行安装流程时，打包后端会读取pyproject.toml里[project.scripts]的配置，在目标Python环境的Scripts目录（Windows）或bin目录（Linux/macOS）生成对应的可执行入口：
  • Windows下的.exe是轻量级包装启动器，核心作用是定位当前环境的Python解释器，再调用你配置的入口函数（比如<package>.<script_module>:main）。
  • 这类启动器并非编译后的二进制文件，而是与当前Python环境绑定的脚本包装，目的是让用户无需手动输入python ...，就能直接通过命令行调用你的应用。

问题2：配置src目录下独立脚本模块为入口 #

要让Hatchling/pip识别src目录下不属于<package>的独立脚本模块，需完成以下两步配置：

1. 调整打包规则，将独立模块纳入分发包 #

在pyproject.toml中添加Hatchling的打包包含规则，确保src目录下的独立.py文件被打包进分发包：

[tool.hatch.build.targets.wheel.includes]
"src/*.py" = true

2. 配置脚本入口并修复开发环境路径 #

• 在[project.scripts]中直接使用独立模块的名称配置入口：

  [project.scripts]
  exe_basename = 'script_module:main'
  

• 开发环境（PyCharm）中，需要将project\src目录标记为Sources Root：
  右键点击src目录 → 选择Mark Directory as → Sources Root，这样PyCharm会自动将src目录加入sys.path，就能识别到该目录下的独立模块了。

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