如何用Hatch打包导入名与项目名不同的Python包？

问题原因 #

你遇到的问题是打包配置未将src/package_name目录下的实际代码纳入打包范围，导致安装后仅生成元数据文件（project_name-0.0.1.dist-info），缺少可导入的包代码文件。

方案一：用Hatch实现需求 #

1. 确认正确的目录结构 #

确保项目结构符合标准布局：

项目根目录/
├── src/
│   └── package_name/
│       ├── __init__.py  # 必须存在，空文件也可
│       └── 你的代码模块（比如x.py）
└── pyproject.toml

2. 配置pyproject.toml #

修改配置文件，重点指定要打包的包路径：

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

[project]
name = "project_name"  # 用户执行pip install时的名称
version = "0.0.1"
authors = [
  { name="你的名字", email="你的邮箱" }
]
description = "项目描述"
readme = "README.md"
requires-python = ">=3.8"
classifiers = [
  "Programming Language :: Python :: 3",
  "License :: OSI Approved :: MIT License",
  "Operating System :: OS Independent",
]

# 核心配置：指定要打包的包所在路径
[tool.hatch.build]
packages = ["src/package_name"]

3. 打包、测试与上传 #

• 安装Hatch：pip install hatch
• 本地打包：hatch build，执行后会在dist目录生成wheel和源码包文件
• 本地安装测试：pip install dist/project_name-0.0.1-py3-none-any.whl，之后在Python环境中测试from package_name import x
• 上传到测试PyPI：hatch publish --repo testpypi，安装时用pip install --index-url https://test.pypi.org/simple/ project_name

方案二：用Setuptools（基于pyproject.toml） #

如果不想用Hatch，也可以用Setuptools实现相同需求：

1. 确认目录结构 #

和Hatch方案的目录结构一致，确保src/package_name下有__init__.py

2. 配置pyproject.toml #

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

[project]
name = "project_name"
version = "0.0.1"
# 其他项目信息和Hatch方案一致

# 核心配置：让Setuptools自动发现src目录下的包
[tool.setuptools.packages.find]
where = ["src"]

3. 打包、测试与上传 #

• 升级Setuptools：pip install --upgrade setuptools wheel
• 本地打包：python -m build，生成的包文件在dist目录
• 本地测试安装和上传步骤与Hatch方案一致

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