# Python 3.8 兼容性说明

## 概述

DataOps Platform 的时区功能已兼容 Python 3.8 和 Python 3.9+。

## 时区模块兼容性

### 代码实现

`app/core/common/timezone_utils.py` 使用了兼容性导入：

```python
try:
    # Python 3.9+
    from zoneinfo import ZoneInfo
except ImportError:
    # Python 3.8 使用 backports
    from backports.zoneinfo import ZoneInfo
```

### 依赖要求

#### Python 3.8 环境

1. **必须安装**: `backports.zoneinfo`
   ```bash
   pip install backports.zoneinfo
   ```

2. **系统依赖**: `tzdata`
   ```bash
   sudo apt-get update
   sudo apt-get install -y tzdata
   ```

#### Python 3.9+ 环境

1. **标准库**: 内置 `zoneinfo`，无需额外安装
2. **系统依赖**: `tzdata`
   ```bash
   sudo apt-get update
   sudo apt-get install -y tzdata
   ```

## 生产环境配置

### 当前生产环境

- **Python 版本**: 3.8
- **已安装**: `backports.zoneinfo`
- **需要**: 确保系统已安装 `tzdata`

### 验证安装

```bash
# 进入虚拟环境
cd /opt/dataops-platform
source venv/bin/activate

# 测试时区模块
python -c "
try:
    from zoneinfo import ZoneInfo
    print('使用标准库 zoneinfo (Python 3.9+)')
except ImportError:
    from backports.zoneinfo import ZoneInfo
    print('使用 backports.zoneinfo (Python 3.8)')

from datetime import datetime
tz = ZoneInfo('Asia/Shanghai')
now = datetime.now(tz)
print(f'当前东八区时间: {now}')
"
```

预期输出：
```
使用 backports.zoneinfo (Python 3.8)
当前东八区时间: 2026-01-12 18:30:45.123456+08:00
```

## requirements.txt 更新

确保 `requirements.txt` 包含以下内容：

```txt
# Python 3.8 时区支持
backports.zoneinfo>=0.2.1; python_version < "3.9"
```

这样可以：
- Python 3.8 环境自动安装 `backports.zoneinfo`
- Python 3.9+ 环境跳过安装（使用标准库）

## 常见问题

### Q1: ModuleNotFoundError: No module named 'zoneinfo'

**原因**: Python 3.8 环境未安装 `backports.zoneinfo`

**解决**:
```bash
pip install backports.zoneinfo
```

### Q2: ZoneInfoNotFoundError: 'No time zone found with key Asia/Shanghai'

**原因**: 系统缺少时区数据

**解决**:
```bash
sudo apt-get update
sudo apt-get install -y tzdata
```

### Q3: 如何确认当前使用的是哪个模块？

**测试代码**:
```python
import sys
try:
    from zoneinfo import ZoneInfo
    print(f"使用标准库 zoneinfo: {sys.modules['zoneinfo']}")
except ImportError:
    from backports.zoneinfo import ZoneInfo
    print(f"使用 backports.zoneinfo: {sys.modules['backports.zoneinfo']}")
```

## 升级路径

### 从 Python 3.8 升级到 3.9+

当升级 Python 版本时：

1. **无需修改代码**: 兼容性导入会自动使用标准库
2. **可选清理**: 卸载 `backports.zoneinfo`
   ```bash
   pip uninstall backports.zoneinfo
   ```
3. **验证**: 运行测试确保时区功能正常

## 性能考虑

- `backports.zoneinfo` 和标准库 `zoneinfo` 性能基本相同
- 两者都使用系统的 IANA 时区数据库
- 升级到 Python 3.9+ 后无性能差异

## 相关文件

- 时区工具模块: `app/core/common/timezone_utils.py`
- 修复脚本: `scripts/fix_startup.sh`
- 故障排查: `scripts/TROUBLESHOOTING.md`
- 快速修复: `QUICK_FIX.md`