221 lines
5.4 KiB
Markdown
221 lines
5.4 KiB
Markdown
# `unidict.py` 技术文档
|
||
|
||
本模块提供了一组用于处理 Python 中字符串编码转换的工具函数，主要用于将字节串（`bytes`）安全地转换为 Unicode 字符串（`str`），并递归地对复杂数据结构（如字典、列表）中的字符串进行统一编码处理。适用于 Python 2/3 兼容环境或需要处理混合编码数据的场景。
|
||
|
||
---
|
||
|
||
## 模块依赖
|
||
|
||
```python
|
||
import locale
|
||
```
|
||
|
||
- 使用 `locale.getdefaultlocale()` 获取系统默认编码，作为解码失败时的备用方案。
|
||
|
||
---
|
||
|
||
## 函数说明
|
||
|
||
### `unicoding(d, coding='utf8')`
|
||
|
||
将输入对象 `d` 转换为 Unicode 字符串（`str` 类型）。支持字符串、字节串等类型的输入，并具备多级解码容错机制。
|
||
|
||
#### 参数
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `d` | `str`, `bytes`, 或其他 | 待转换的对象。通常为字符串或字节串。 |
|
||
| `coding` | `str` | 建议使用的编码格式，默认为 `'utf8'`。 |
|
||
|
||
#### 返回值
|
||
|
||
- 若 `d` 已是 `str` 类型，直接返回。
|
||
- 若 `d` 是 `bytes` 类型，则尝试按指定编码解码为 `str`。
|
||
- 解码失败时，依次尝试：系统默认编码 → UTF-8 → 原始值（不解码）。
|
||
- 其他类型直接返回原对象。
|
||
|
||
#### 解码优先级顺序
|
||
|
||
1. 使用参数 `coding` 指定的编码（若非 `None`）
|
||
2. 系统默认编码（通过 `locale.getdefaultlocale()[1]` 获取）
|
||
3. `utf8`
|
||
4. 若全部失败，返回原始 `bytes` 对象
|
||
|
||
> ⚠️ 注意：代码中存在拼写错误 `Noene` 应为 `None`，这会导致逻辑错误！
|
||
|
||
#### 示例
|
||
|
||
```python
|
||
>>> unicoding(b'hello')
|
||
'hello'
|
||
|
||
>>> unicoding('already unicode')
|
||
'already unicode'
|
||
|
||
>>> unicoding(b'\xe4\xb8\xad\xe6\x96\x87', 'utf8')
|
||
'中文'
|
||
```
|
||
|
||
#### 修复建议
|
||
|
||
原代码中：
|
||
|
||
```python
|
||
if coding is not Noene:
|
||
```
|
||
|
||
应更正为：
|
||
|
||
```python
|
||
if coding is not None:
|
||
```
|
||
|
||
否则会抛出 `NameError: name 'Noene' is not defined`。
|
||
|
||
---
|
||
|
||
### `uObject(obj, coding='utf8')`
|
||
|
||
递归处理任意对象，将其内部的字符串或可解码对象转换为 Unicode 字符串。
|
||
|
||
#### 参数
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `obj` | 任意类型 | 输入对象（如字符串、列表、字典、自定义对象等） |
|
||
| `coding` | `str` | 解码所用编码，默认 `'utf8'` |
|
||
|
||
#### 行为逻辑
|
||
|
||
| 输入类型 | 处理方式 |
|
||
|---------|----------|
|
||
| `str`（Unicode） | 直接返回 |
|
||
| `dict` | 调用 `uDict(obj, coding)` 进行递归处理 |
|
||
| `list` 或 `tuple` | 遍历每个元素，递归调用 `uObject(i, coding)` |
|
||
| 具有 `.decode` 方法的对象（如 `bytes`） | 调用其 `decode(coding)` 方法 |
|
||
| 其他类型 | 不处理，原样返回 |
|
||
|
||
#### 返回值
|
||
|
||
转换后的对象，所有字符串均尽可能转为 Unicode。
|
||
|
||
#### 示例
|
||
|
||
```python
|
||
>>> uObject([b'item1', b'item2'])
|
||
['item1', 'item2']
|
||
|
||
>>> uObject({'key': b'value'})
|
||
{'key': 'value'}
|
||
```
|
||
|
||
---
|
||
|
||
### `uDict(dict, coding='utf8')`
|
||
|
||
专门用于将字典中所有的键和值（包括嵌套结构）转换为 Unicode 字符串。
|
||
|
||
#### 参数
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `dict` | `dict` | 输入字典 |
|
||
| `coding` | `str` | 编码方式，默认 `'utf8'` |
|
||
|
||
#### 实现逻辑
|
||
|
||
- 创建新字典 `d`
|
||
- 遍历原字典的所有 `(k, v)` 键值对
|
||
- 对键 `k` 和值 `v` 分别调用 `uObject(...)` 进行递归转换
|
||
- 将结果存入新字典并返回
|
||
|
||
#### 特点
|
||
|
||
- 支持嵌套字典、列表等复合结构
|
||
- 安全处理不可变类型与非字符串类型
|
||
|
||
#### 示例
|
||
|
||
```python
|
||
data = {
|
||
b'name': b'张三',
|
||
b'hobbies': [b'读书', b'游泳'],
|
||
b'meta': {b'city': b'北京'}
|
||
}
|
||
|
||
result = uDict(data)
|
||
# 输出：
|
||
# {'name': '张三', 'hobbies': ['读书', '游泳'], 'meta': {'city': '北京'}}
|
||
```
|
||
|
||
---
|
||
|
||
## 使用场景
|
||
|
||
- 处理来自网络、文件或数据库的混合编码数据
|
||
- 在 Web 开发中清洗请求参数或 JSON 数据
|
||
- 跨平台兼容性处理（尤其是 Windows 和 Linux 编码差异）
|
||
- 构建健壮的数据预处理管道
|
||
|
||
---
|
||
|
||
## 注意事项与改进建议
|
||
|
||
### ❗ Bug 提示
|
||
|
||
```python
|
||
if coding is not Noene:
|
||
```
|
||
|
||
这是明显的拼写错误，`Noene` 应改为 `None`，否则运行时报错。
|
||
|
||
✅ 正确写法：
|
||
|
||
```python
|
||
if coding is not None:
|
||
```
|
||
|
||
---
|
||
|
||
### ✅ 建议改进点
|
||
|
||
1. **增加类型注解**（Python 3+ 更佳体验）
|
||
|
||
```python
|
||
def unicoding(d: bytes, coding: str = 'utf8') -> str:
|
||
```
|
||
|
||
2. **使用 `six` 或 `typing` 提高兼容性**
|
||
|
||
可引入 `six.string_types`, `six.binary_type` 来更好地区分文本与二进制类型。
|
||
|
||
3. **日志记录代替静默捕获异常**
|
||
|
||
当前使用 `except:` 捕获所有异常，不利于调试。建议记录警告信息。
|
||
|
||
4. **避免重复解码尝试**
|
||
|
||
可以预先获取系统编码，减少多次调用 `locale.getdefaultlocale()`
|
||
|
||
5. **性能优化**
|
||
|
||
对于大型嵌套结构，递归调用可能影响性能，可考虑迭代实现或缓存机制。
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
`unidict.py` 是一个轻量但实用的编码统一工具模块，特别适合在处理不确定编码来源的数据时使用。尽管存在一个小 bug（`Noene`），但整体设计清晰，功能明确，经过适当修正后可在生产环境中稳定使用。
|
||
|
||
---
|
||
|
||
## 版本信息
|
||
|
||
- 作者：未知
|
||
- 语言：Python 2/3 兼容风格
|
||
- 文件名：`unidict.py`
|
||
- 最后修订：需修复 `Noene` 错误
|
||
|
||
---
|
||
|
||
📌 **推荐用途**：数据清洗、API 接口预处理、日志解析、配置加载等涉及编码转换的场景。 |