Update

2023/scripts/animation_tools/atools/COMPATIBILITY.md

@@ -0,0 +1,198 @@
+# 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  
+**状态**: ✅ 兼容性修复完成