如何用setuptools和pyproject.toml打包单模块并附带py.typed文件？

架构老林

2026-6-12

解决方案

方法1：通过`data_files`配置安装`py.typed`

保持单文件项目结构不变：

sample.py
py.typed
pyproject.toml

修改pyproject.toml，在[project]区块添加data_files配置，将py.typed安装到与模块相同的site-packages根目录：

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

[project]
name = "sample"
version = "0.1.0"
requires-python = ">=3.8"
# 按需添加作者、描述等其他元信息

# 空字符串表示将文件安装到site-packages根目录
data_files = [("", ["py.typed"])]

# 指定要打包的单文件模块
[tool.setuptools]
py-modules = ["sample"]

打包安装后，sample.py和py.typed会共存于site-packages根目录，既支持直接from sample import whatever导入，类型检查工具也能识别到类型提示配置。

方法2：利用`include-package-data`与`package-data`

无需创建子目录，借助setuptools对单文件模块的隐含包处理，配置package-data包含py.typed：

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

[project]
name = "sample"
version = "0.1.0"
requires-python = ">=3.8"
# 按需添加其他元信息

[tool.setuptools]
py-modules = ["sample"]
include-package-data = true

# 空键表示匹配所有包（单文件模块会被视为根包的一部分）
[tool.setuptools.package-data]
"" = ["py.typed"]

这种配置的最终安装效果和方法1完全一致，同样满足直接导入的需求。