# aTools 兼容性说明

## ✅ 支持的 Maya 版本

- **Maya 2017-2020**: Python 2.7
- **Maya 2022+**: Python 3.7+
- **Maya 2023+**: Python 3.9+
- **Maya 2025+**: Python 3.11+

## 🔧 兼容性修复

### 1. Python 2/3 兼容性 ✅

#### 字符串格式化
- ❌ **避免使用**: f-string (Python 3.6+)
  ```python
  # 错误
  print(f"backup: {bkpFolder}")
  ```
- ✅ **推荐使用**: `.format()` 或 `%` 格式化
  ```python
  # 正确
  print("backup: {}".format(bkpFolder))
  print("backup: %s" % bkpFolder)
  ```

#### 已修复的文件
- `animationCrashRecovery.py` - 第 297 行 f-string 已修复

### 2. NoneType 错误防护 ✅

#### 列表/字典访问前检查
```python
# 错误 - 可能导致 TypeError
data = some_function()
value = data[0]  # 如果 data 是 None 会崩溃

# 正确 - 添加检查
data = some_function()
if data and len(data) > 0:
    value = data[0]
else:
    value = default_value
```

#### 已修复的文件
- `setup.py` - 第 63 行添加长度检查
- `animationCrashRecovery.py` - 第 331, 336 行添加 None 检查
- `generalToolsUI.py` - 第 50 行添加 None 检查

### 3. 文件路径处理 ✅

#### 使用 os.path 而非硬编码
```python
# 错误
path = "C:\\Users\\..."

# 正确
import os
path = os.path.join(base_dir, "subfolder", "file.txt")
```

#### 路径分隔符
```python
# 使用 os.sep 而非 \\ 或 /
folder = base_path + os.sep + subfolder
# 或更好的方式
folder = os.path.join(base_path, subfolder)
```

### 4. 导入兼容性 ✅

#### 相对导入
所有内部导入已改为相对导入：
```python
# 之前
from aTools.commonMods import animMod

# 现在
from commonMods import animMod
```

### 5. Maya API 兼容性

#### cmds vs pymel
- 优先使用 `maya.cmds` (更稳定)
- 避免依赖 `pymel` (可选依赖)

#### API 版本检查
```python
import maya.cmds as cmds

maya_version = int(cmds.about(version=True))
if maya_version >= 2022:
    # Python 3 特性
    pass
else:
    # Python 2 兼容代码
    pass
```

## 🛡️ 错误处理最佳实践

### 1. 文件读取
```python
try:
    with open(filepath, 'r') as f:
        content = f.read()
except IOError:
    content = None
    print("Failed to read file: {}".format(filepath))

if content:
    # 处理内容
    pass
```

### 2. 列表访问
```python
def safe_get(lst, index, default=None):
    """安全获取列表元素"""
    try:
        return lst[index] if lst and len(lst) > index else default
    except (IndexError, TypeError):
        return default

# 使用
value = safe_get(data, 0, "default_value")
```

### 3. 字典访问
```python
# 使用 get() 方法
value = my_dict.get('key', default_value)

# 而不是
value = my_dict['key']  # 可能 KeyError
```

## 📋 兼容性检查清单

### 代码检查
- [x] 无 f-string
- [x] 无 Python 3 专有语法
- [x] 所有列表/字典访问有 None 检查
- [x] 文件路径使用 os.path
- [x] 导入语句正确

### 测试检查
- [ ] Maya 2017 (Python 2.7)
- [ ] Maya 2020 (Python 2.7)
- [ ] Maya 2022 (Python 3.7)
- [ ] Maya 2023 (Python 3.9)
- [ ] Maya 2024 (Python 3.10)
- [ ] Maya 2025 (Python 3.11)

### 功能检查
- [ ] 模块导入成功
- [ ] UI 启动正常
- [ ] 所有工具可用
- [ ] 无错误/警告

## 🔍 自动检查工具

运行兼容性检查脚本：
```python
# 在 atools 目录下
python check_compatibility.py
```

## 📝 已知限制

1. **Python 2.7 支持**: 
   - Maya 2017-2020 使用 Python 2.7
   - 必须避免 Python 3 专有特性

2. **Maya API 变化**:
   - 某些 API 在不同版本有变化
   - 使用 try-except 处理版本差异

3. **第三方依赖**:
   - 尽量减少外部依赖
   - 如需依赖，确保跨版本兼容

## 🚀 最佳实践总结

1. ✅ 使用 `.format()` 而非 f-string
2. ✅ 所有数据访问前检查 None
3. ✅ 使用 `os.path` 处理路径
4. ✅ 添加 try-except 错误处理
5. ✅ 测试多个 Maya 版本
6. ✅ 保持代码简洁清晰
7. ✅ 添加详细注释和文档

---

**最后更新**: 2025-11-25  
**状态**: ✅ 兼容性修复完成