# pyresourcedemo

**Repository Path**: graviton/pyresourcedemo

## Basic Information

- **Project Name**: pyresourcedemo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: LGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-20
- **Last Updated**: 2026-01-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PyResource Demo

演示如何使用 `pyproject.toml` 打包 Python package 的 data 文件(`images`, `.so`, `.dll`, 模型文件等),
以及如何使用 `importlib.resources` 读取二进制文件,
包括打包阶段用 `zipapp`/`pex` 把 `data/` 丢进 zip 文件.

## 项目结构

```
pyresourcedemo/
├── pyproject.toml              # 项目配置和打包设置
├── src/                        # 源代码 root
│   └── pyresourcedemo/
│       ├── __init__.py         # 包初始化
│       ├── resource_loader.py  # 核心资源加载模块
│       ├── cli.py              # 命令行接口
│       └── data/               # 数据文件目录
│           ├── config.txt      # 配置文件
│           ├── binary_data.bin # 二进制数据
│           ├── images/
│           │   └── sample.png  # 图片文件
│           ├── models/
│           │   └── neural_network.txt  # 模型文件
│           └── libs/
│               ├── native_lib.dll     # Windows DLL
│               └── native_lib.so      # Linux SO
├── tests/                      # 测试文件
└── examples/                   # 示例代码
```

## 核心功能

### 1. 资源加载器 (resource_loader.py)

支持 Python 3.8+ 的 `importlib.resources` API, 兼容新旧版本:

```python
from pyresourcedemo import resource_loader

# 加载文本文件
config = resource_loader.load_text_file("config.txt")

# 加载二进制文件
binary_data = resource_loader.load_binary_file("images/sample.png")

# 加载特定类型文件
image_data = resource_loader.load_image_sample()
model_info = resource_loader.load_model_sample()
lib_data = resource_loader.load_library_sample("native_lib.dll")

# 检查文件是否存在
exists = resource_loader.check_resource_exists("config.txt")

# 获取文件信息
info = resource_loader.get_resource_info("config.txt")

# 列出数据文件
files = resource_loader.list_data_files("images")
```

### 2. 命令行工具

安装后可以使用 `pyresourcedemo` 命令:

```bash
##======================================== uv venv 环境
# 列出所有数据文件
uv run pyresourcedemo list
# 加载文件内容
uv run pyresourcedemo load config.txt
uv run pyresourcedemo load images/sample.png
# 显示文件信息
uv run pyresourcedemo info config.txt
# 运行完整演示
uv run pyresourcedemo demo

##======================================== 使用 global python
pyresourcedemo list
pyresourcedemo load config.txt
pyresourcedemo load images/sample.png
pyresourcedemo info config.txt
pyresourcedemo demo
```

## 打包配置

### pyproject.toml 关键配置

```toml
[tool.setuptools.package-data]
pyresourcedemo = [
    "data/*.txt",      # 文本文件
    "data/*.bin",      # 二进制文件
    "data/images/*",   # 图片文件
    "data/models/*",   # 模型文件
    "data/libs/*.so",  # Linux 共享库
    "data/libs/*.dll", # Windows 动态链接库
    "data/libs/*.dylib" # macOS 动态库
]

[tool.setuptools]
include-package-data = true
```

## 安装和测试

### 1. 开发模式安装

```bash
cd pyresourcedemo
pip install -e .
```

### 2. 运行测试

```bash
pip install -e .[dev]
pytest tests/
```

### 3. 使用命令行工具

```bash
# 运行演示
pyresourcedemo demo

# 查看可用文件
pyresourcedemo list

# 加载配置文件
pyresourcedemo load config.txt
```

### 4. Python API 使用

```python
from pyresourcedemo import resource_loader

# 加载配置文件
config = resource_loader.load_text_file("config.txt")
print("配置文件内容:", config)

# 加载图片文件
image_data = resource_loader.load_image_sample()
print(f"图片大小: {len(image_data)} 字节")

# 加载模型文件
model_info = resource_loader.load_model_sample()
print("模型信息:", model_info[:100] + "...")

# 加载库文件
lib_data = resource_loader.load_library_sample("native_lib.dll")
print(f"库文件大小: {len(lib_data)} 字节")
```

## 高级打包方式

### 1. 构建 Wheel 包

```bash
pip install build
python -m build
```

生成的 wheel 包会包含所有数据文件.

### 2. ZipApp 打包

```bash
##======================================== uv venv 环境
## 创建 zipapp
uv run -m zipapp src/pyresourcedemo -m pyresourcedemo.cli:main -o pyresourcedemo.pyz
## 运行 zipapp
uv run pyresourcedemo.pyz demo

##======================================== 使用 global python
python -m zipapp pyresourcedemo -m pyresourcedemo.cli:main -o pyresourcedemo.pyz
python pyresourcedemo.pyz demo
```

### 3. Pex 打包

```bash
# 安装 pex
pip install pex

# 创建 pex 文件
pex . -e pyresourcedemo.cli:main -o pyresourcedemo.pex

# 运行 pex
python pyresourcedemo.pex demo
```

## 技术要点

### 1. importlib.resources 使用

- **Python 3.9+**: 使用新的 `files()` API
- **Python 3.8**: 使用兼容的 `open_text()` / `open_binary()` API
- **跨版本兼容**: 自动检测 Python 版本并选择合适的 API

### 2. 二进制文件处理

```python
# 读取二进制文件
data = load_binary_file("images/sample.png")

# 可以进一步处理, 如图片解码, 模型加载等
# image = PIL.Image.open(io.BytesIO(data))
# model = pickle.loads(data)
```

### 3. ZipApp 兼容性

使用 `importlib.resources` 确保在 zipapp 中也能正确读取资源文件, 因为:

- 不依赖实际的文件系统路径
- 通过资源 API 访问包内文件
- 支持从 ZIP 文件中读取数据

### 4. 跨平台支持

- 支持 Windows (.dll), Linux (.so), macOS (.dylib)
- 统一的 API 访问不同平台的数据文件
- 路径处理使用 POSIX 风格, 确保跨平台兼容性

## 实际应用场景

1. **机器学习模型部署**: 打包模型权重文件
2. **图像处理应用**: 打包图像模板, 图标等资源
3. **科学计算**: 打包数据集, 配置文件
4. **桌面应用**: 打包 UI 资源, 本地化文件
5. **命令行工具**: 打包配置模板, 示例文件

## 最佳实践

1. **数据文件分类**: 按类型放在不同子目录
2. **文件命名**: 使用描述性名称, 避免特殊字符
3. **大小控制**: 大数据文件考虑压缩或外部存储
4. **版本管理**: 数据文件变更时更新版本号
5. **测试覆盖**: 为资源加载编写测试用例

## 注意事项

1. **Python 版本**: 确保使用支持 `importlib.resources` 的 Python 版本
2. **包结构**: 数据文件必须在包目录内, 不能在外部
3. **构建工具**: 使用支持 `pyproject.toml` 的现代构建工具
4. **文件大小**: 特大数据文件考虑其他部署方式

## 相关文档

- [importlib.resources 文档](https://docs.python.org/3/library/importlib.resources.html)
- [setuptools 文档](https://setuptools.pypa.io/en/latest/)
- [Python 打包指南](https://packaging.python.org/)
- [zipapp 文档](https://docs.python.org/3/library/zipapp.html)
- [pex 文档](https://pex.readthedocs.io/)