157 lines
3.8 KiB
Markdown
157 lines
3.8 KiB
Markdown
# `ExecFile.DictConfig` 技术文档
|
||
|
||
## 概述
|
||
|
||
本文档介绍如何使用 `ExecFile.DictConfig` 类从 `.dict` 配置文件中加载配置数据，并通过属性访问方式读取嵌套的字典结构。该类提供了一种便捷的方式来将 Python 字典格式的配置文件转换为可动态访问的对象。
|
||
|
||
---
|
||
|
||
## 安装与依赖
|
||
|
||
确保已安装 `ExecFile` 模块。若未安装，请使用以下命令进行安装（假设模块可通过 pip 获取）：
|
||
|
||
```bash
|
||
pip install execfile
|
||
```
|
||
|
||
> 注意：`ExecFile` 并非标准库模块，可能为自定义或第三方库。请确认其来源并正确导入。
|
||
|
||
---
|
||
|
||
## 导入模块
|
||
|
||
```python
|
||
import ExecFile
|
||
```
|
||
|
||
---
|
||
|
||
## 初始化配置对象
|
||
|
||
### 语法
|
||
|
||
```python
|
||
c = ExecFile.DictConfig(path='./config.dict')
|
||
```
|
||
|
||
### 参数说明
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|--------|------|------|
|
||
| `path` | str | 是 | 配置文件路径，指向一个包含合法 Python 字典语法的 `.dict` 文件 |
|
||
|
||
### 示例配置文件 (`config.dict`)
|
||
|
||
```python
|
||
{
|
||
'd': {
|
||
'b': [
|
||
{'c': None},
|
||
{'c': 'value_b1_c'}
|
||
],
|
||
'c': {
|
||
'a': 'value_a',
|
||
'b': 'value_b',
|
||
'c': [
|
||
{}, {}, {},
|
||
{'f': 'value_f'}
|
||
],
|
||
'd': [1, 2, 3]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> ⚠️ 文件内容必须是合法的 Python 表达式，通常是一个字典结构。
|
||
|
||
---
|
||
|
||
## 属性访问方式
|
||
|
||
`DictConfig` 将字典中的键转换为对象的属性，支持链式点号访问（`.`），包括嵌套字典和列表元素。
|
||
|
||
### 访问规则
|
||
|
||
- 字典键 → 对象属性：`config.d.b`
|
||
- 列表元素 → 使用索引访问：`config.d.c.c[3].f`
|
||
- 支持任意层级嵌套访问
|
||
|
||
---
|
||
|
||
## 示例代码解析
|
||
|
||
```python
|
||
import ExecFile
|
||
|
||
# 加载配置文件
|
||
c = ExecFile.DictConfig(path='./config.dict')
|
||
|
||
# 打印多个嵌套值
|
||
print(c.d.b[1].c, c.d.c.a, c.d.c.b, c.d.c.c[3].f)
|
||
|
||
# 打印列表中的第2个元素（索引1）
|
||
print(c.d.c.c[1])
|
||
|
||
# 打印整个列表 d.c.d
|
||
print(c.d.c.d)
|
||
```
|
||
|
||
### 输出示例（基于上述配置）
|
||
|
||
```text
|
||
value_b1_c value_a value_b value_f
|
||
{}
|
||
[1, 2, 3]
|
||
```
|
||
|
||
---
|
||
|
||
## 方法与特性
|
||
|
||
### `__init__(self, path: str)`
|
||
- **功能**：读取指定路径的 `.dict` 文件并解析为嵌套对象。
|
||
- **异常处理**：
|
||
- 若文件不存在，抛出 `FileNotFoundError`
|
||
- 若文件内容不是合法的 Python 表达式，抛出 `SyntaxError` 或 `ValueError`
|
||
|
||
### 动态属性访问
|
||
- 所有字典的 key 均可通过 `.` 访问。
|
||
- 列表和字典保留原生操作方式（如 `[index]`、`.keys()` 等）。
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **安全性警告**：由于 `.dict` 文件通过 `eval` 或 `ast.literal_eval` 解析，应确保文件来源可信，避免执行恶意代码。
|
||
2. **文件格式要求**：配置文件必须是有效的 Python 字面量表达式，不能包含函数调用或其他可执行语句。
|
||
3. **只读设计**：建议将配置视为只读数据；修改运行时对象不会持久化回文件。
|
||
|
||
---
|
||
|
||
## 错误排查
|
||
|
||
| 问题 | 可能原因 | 解决方案 |
|
||
|------|----------|-----------|
|
||
| `ModuleNotFoundError: No module named 'ExecFile'` | 模块未安装或命名错误 | 确认模块名称及安装方式 |
|
||
| `SyntaxError` in config file | 配置文件语法错误 | 使用 Python 解释器测试文件内容是否可执行 |
|
||
| `AttributeError` | 访问了不存在的键 | 检查配置结构与访问路径是否匹配 |
|
||
|
||
---
|
||
|
||
## 扩展建议
|
||
|
||
- 添加 `reload()` 方法以重新加载配置文件。
|
||
- 提供 `to_dict()` 方法导出为标准字典类型。
|
||
- 支持 `.json` 或 `.yaml` 格式作为替代方案。
|
||
|
||
---
|
||
|
||
## 版权与维护
|
||
|
||
- 模块：`ExecFile`
|
||
- 维护者：未知（请查阅实际项目文档）
|
||
- 适用版本：Python 3.6+
|
||
|
||
---
|
||
|
||
✅ **提示**：推荐在生产环境中使用 JSON/YAML 替代 `.dict` 格式以提高安全性和可移植性。 |