Python打包分发实战：除了setup.py，你的egg和wheel里还藏着什么秘密？

当你用 pip install 安装一个Python包时，是否好奇过那些被打包进去的非代码文件最终去了哪里？作为一个Python开发者，你可能已经熟悉了 setup.py 的基本用法，但今天我们要探讨的是打包分发中那些常被忽视的"隐藏资源"——图片、配置文件、模板文件等，以及如何在运行时安全地访问它们。

想象这样一个场景：你开发了一个Web框架插件，需要内置HTML模板文件；或者你构建了一个机器学习工具包，附带预训练模型数据。这些资源文件需要随代码一起分发，但在不同操作系统和部署环境下，传统的文件路径访问方式往往会遇到各种问题。这就是 pkg_resources 模块大显身手的时候。

1. 为什么需要pkg_resources？

在Python打包生态中， .egg 和 .wheel 文件不仅仅是代码的容器。它们实际上是一个完整的资源分发系统，可以包含：

• 纯Python代码（ .py 文件）
• 编译扩展（ .so 、 .pyd 等）
• 数据文件（ .json 、 .csv 等）
• 静态资源（ .png 、 .html 等）
• 文档和测试文件

传统的文件访问方式如 open('data/config.json') 存在几个致命缺陷：

1. 路径不确定性 ：安装后的文件可能位于 site-packages 的任何子目录中
2. 跨平台问题 ：Windows和Unix-like系统的路径分隔符不同
3. 压缩包访问 ：当包以 .egg 或 .whl 形式安装时，文件可能被压缩

# 危险的传统文件访问方式
with open('my_package/templates/default.html') as f:
    template = f.read()

pkg_resources 提供了一套统一的API来解决这些问题，无论你的包是作为压缩文件还是解压目录安装，都能正常工作。

2. 打包非代码资源：MANIFEST.in与package_data

在深入 pkg_resources 的使用前，我们需要先确保资源文件被正确打包。这需要在 setup.py 和 MANIFEST.in 文件中进行配置。

2.1 setup.py中的package_data配置

from setuptools import setup

setup(
    name="my_web_plugin",
    packages=["my_web_plugin"],
    package_data={
        "my_web_plugin": ["templates/*.html", "static/*.css", "data/*.json"]
    },
    include_package_data=True,
)

关键参数说明：

• package_data ：指定每个子包中包含的非Python文件
• include_package_data ：启用MANIFEST.in文件的处理

2.2 MANIFEST.in文件详解

MANIFEST.in 文件使用简单的指令语法来包含额外的文件：

include LICENSE README.md
recursive-include my_web_plugin/templates *.html
recursive-include my_web_plugin/static *.css *.js
recursive-include my_web_plugin/data *.json

常用指令：

指令格式	作用	示例
include	包含单个文件	include LICENSE
recursive-include	递归包含目录中的匹配文件	recursive-include docs *.pdf
global-include	全局匹配包含文件	global-include *.txt
graft	包含整个目录	graft examples

注意： MANIFEST.in 只影响源码分发（sdist），对wheel格式的分发需要使用 package_data

3. pkg_resources核心API实战

现在，让我们深入 pkg_resources 的主要功能，通过一个Web框架插件的案例来演示如何访问打包资源。

3.1 资源访问基础方法

假设我们的包结构如下：

my_web_plugin/
├── __init__.py
├── templates/
│   ├── default.html
│   └── admin.html
└── static/
    ├── style.css
    └── script.js

使用resource_string读取文本内容 ：

import pkg_resources

# 读取模板文件
template = pkg_resources.resource_string(
    'my_web_plugin', 
    'templates/default.html'
).decode('utf-8')

# 读取CSS文件
css = pkg_resources.resource_string(
    'my_web_plugin',
    'static/style.css'
).decode('utf-8')

使用resource_stream处理大文件 ：

对于较大的文件（如数据集），使用流式读取更高效：

with pkg_resources.resource_stream('my_web_plugin', 'data/large_dataset.json') as f:
    for line in f:
        process_line(line)

3.2 资源列表与存在性检查

有时我们需要动态发现包内的资源：

# 列出templates目录下所有文件
templates = pkg_resources.resource_listdir('my_web_plugin', 'templates')

# 检查特定资源是否存在
if pkg_resources.resource_exists('my_web_plugin', 'static/style.css'):
    print("CSS file exists")

3.3 文件系统路径获取

在某些需要真实文件路径的场景（如C扩展库加载），可以使用：

css_path = pkg_resources.resource_filename('my_web_plugin', 'static/style.css')

警告：只有当资源确实存在于文件系统（非压缩包）时才能使用此方法

4. 高级应用场景

4.1 多版本资源管理

pkg_resources 支持根据版本号访问特定资源：

# 获取特定版本的资源
v1_template = pkg_resources.resource_string(
    'my_web_plugin',
    'templates/default.html',
    pkg_resources.Requirement.parse('my_web_plugin==1.0')
)

4.2 插件系统开发

实现一个基于入口点的插件系统：

# setup.py中定义入口点
setup(
    entry_points={
        'web.plugins': [
            'my_plugin = my_web_plugin.core:PluginImpl'
        ]
    }
)

# 运行时加载插件
for entry_point in pkg_resources.iter_entry_points('web.plugins'):
    plugin_class = entry_point.load()
    plugin = plugin_class()
    plugin.register()

4.3 资源覆盖与定制

允许用户覆盖包内默认资源：

def load_template(name):
    # 先检查用户自定义目录
    custom_path = os.path.join('custom_templates', name)
    if os.path.exists(custom_path):
        with open(custom_path) as f:
            return f.read()
    
    # 回退到包内默认模板
    return pkg_resources.resource_string(
        'my_web_plugin',
        f'templates/{name}'
    ).decode('utf-8')

5. 性能考量与最佳实践

虽然 pkg_resources 非常强大，但在性能敏感场景需要注意：

1. 缓存资源引用 ：频繁访问的资源应该缓存
2. 避免压缩包分发 ：对于性能关键应用，优先使用wheel而非egg
3. 批量操作 ：使用 resource_listdir 减少单独检查

# 不好的做法：每次请求都重新加载
def handle_request():
    template = pkg_resources.resource_string('my_pkg', 'template.html')
    return render(template)

# 好的做法：启动时预加载
TEMPLATE_CACHE = {}

def init_app():
    templates = pkg_resources.resource_listdir('my_pkg', 'templates')
    for name in templates:
        content = pkg_resources.resource_string('my_pkg', f'templates/{name}')
        TEMPLATE_CACHE[name] = content.decode('utf-8')

def handle_request():
    return render(TEMPLATE_CACHE['template.html'])

在实际项目中，我发现最常遇到的坑是忘记在 MANIFEST.in 中包含资源文件，导致它们没有被打包。一个有用的调试技巧是在开发时使用：

print(pkg_resources.resource_listdir('my_package', ''))

来验证哪些文件真正被打包进了分发版本。