PyPI包嵌入JSON读取技巧解析

本文深入解析了在 PyPI 包开发中嵌入和读取 JSON 静态资源的完整实践，直击因资源文件未正确打包导致的 FileNotFoundError 运行时崩溃痛点——从通过 MANIFEST.in 或 setup.py 的 package_data 显式声明资源，到使用 importlib.resources（Python 3.9+）或 pkg_resources（兼容旧版）安全、跨平台地定位并加载包内 JSON 文件，再到发布前验证与关键避坑指南，手把手教你构建健壮、可移植、开箱即用的 Python 包，让内置数据真正“随包而行、稳如磐石”。

本文详解如何在发布 PyPI 包时正确打包并安全读取内置 JSON 资源文件，解决因 FileNotFoundError 导致的运行时数据加载失败问题。

本文详解如何在发布 PyPI 包时正确打包并安全读取内置 JSON 资源文件，解决因 `FileNotFoundError` 导致的运行时数据加载失败问题。

在开发 Python 包（如用于查询印度机构缩写映射的 Abbre）时，将静态数据（如 output_2.json）作为包内资源嵌入是常见需求。但若未显式声明数据文件的打包规则，setuptools 默认不会包含非 Python 文件——这正是报错 FileNotFoundError: [Errno 2] No such file or directory: 'Abbre\\output_2.json' 的根本原因。

✅ 正确打包数据文件的两种方式（任选其一）

方式一：使用 MANIFEST.in（推荐用于复杂资源结构）

在项目根目录（与 setup.py 同级）创建 MANIFEST.in 文件，内容如下：

include Abbre/output_2.json

⚠️ 注意路径分隔符使用正斜杠 /（跨平台兼容），即使在 Windows 下也无需写成 \。

方式二：在 setup.py 中配置 package_data

确保 setup.py 中包含以下关键参数：

from setuptools import setup, find_packages

setup(
    name="Abbre",
    version="0.1.0",
    packages=find_packages(),
    package_dir={"": "."},  # 指定源码根目录
    package_data={
        "Abbre": ["output_2.json"]  # 明确声明 Abbre 包需包含该 JSON 文件
    },
    include_package_data=True,  # 启用 MANIFEST.in 或 package_data
    # 其他参数...
)

✅ 安全读取包内资源文件（替代 open() 的健壮方案）

原始代码中直接使用 open('Abbre\output_2.json') 是错误的：它依赖当前工作目录，且无法定位已安装包内的文件。应改用 importlib.resources（Python 3.9+ 推荐）或 pkg_resources（兼容旧版本）：

✅ 推荐（Python ≥ 3.9）：

import json
from importlib import resources

def Abbreviation(arr):
    # 安全读取包内 JSON（自动处理路径、编码和安装位置）
    with resources.files("Abbre").joinpath("my_data/output_2.json").open("r") as f:
        loaded_dict = json.load(f)

    arr1 = arr.lower().strip()
    result = loaded_dict.get(arr1)
    if result is not None:
        return [result]  # 返回列表，避免重复 print
    else:
        print("The data is not available")
        return []

✅ 兼容方案（Python < 3.9）：

import json
import pkg_resources

def Abbreviation(arr):
    json_file_path = pkg_resources.resource_filename("Abbre", "my_data/output_2.json")
    with open(json_file_path, "r", encoding="utf-8") as f:  # 显式指定编码
        loaded_dict = json.load(f)
    # ... 后续逻辑同上

? 验证是否打包成功

发布前可本地验证：

# 构建源码包
python setup.py sdist

# 解压生成的 .tar.gz，检查 Abbre/ 目录下是否存在 output_2.json
tar -tzf dist/Abbre-0.1.0.tar.gz | grep output_2.json

? 关键注意事项

• ❌ 不要使用相对路径 open('Abbre/output_2.json') —— 安装后该路径无效；
• ✅ 始终通过 importlib.resources 或 pkg_resources 获取资源路径；
• ✅ 在 setup.py 或 MANIFEST.in 中显式声明所有非 .py 文件；
• ✅ JSON 文件建议放在包目录内（如 Abbre/my_data/output_2.json），而非项目根目录；
• ✅ 发布前务必运行 twine check dist/* 验证包元数据完整性。

遵循以上步骤，即可确保 Abbre 包在任何环境安装后都能稳定读取内置数据，彻底规避 FileNotFoundError。

本篇关于《PyPI包嵌入JSON读取技巧解析》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！