new_lottery_bot/docs/UPGRADE_NOTES.md

# Заметки об обновлении до Python 3.12

## Обновлено 15 ноября 2025

### Изменения зависимостей

Все зависимости обновлены для полной совместимости с Python 3.12:

- **aiogram**: 3.1.1 → 3.16.0
- **aiohttp**: 3.8.5 → 3.11.18 (обязательно для Python 3.12)
- **sqlalchemy**: 2.0.23 → 2.0.36
- **alembic**: 1.8.1 → 1.14.0
- **python-dotenv**: 1.0.0 → 1.0.1
- **asyncpg**: 0.28.0 → 0.30.0
- **aiosqlite**: 0.17.0 → 0.20.0

### Изменения кода

#### 1. database.py
- Обновлён импорт: `from sqlalchemy.ext.declarative import declarative_base` → `from sqlalchemy.orm import declarative_base`

#### 2. models.py
- Заменён устаревший `datetime.utcnow` на `datetime.now(timezone.utc)`
- Все поля `created_at` теперь используют timezone-aware datetime

#### 3. Makefile
- Все команды теперь активируют виртуальное окружение через `. .venv/bin/activate`
- Это обеспечивает использование правильных версий Python-пакетов

### Требования к системе

Для успешной установки требуются следующие системные пакеты:
```bash
sudo apt-get install -y build-essential python3-dev libpq-dev libssl-dev pkg-config
```

### Установка

1. Убедитесь, что используете Python 3.12:
```bash
python3 --version  # Должно быть 3.12.x
```

2. Пересоздайте виртуальное окружение:
```bash
rm -rf .venv
python3 -m venv .venv
. .venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
```

3. Примените миграции (если требуется):
```bash
make migrate
```

### Совместимость

- ✅ Полная совместимость с Python 3.12
- ✅ Все устаревшие API обновлены
- ✅ Проверено на Ubuntu 24.04 LTS
- ⚠️ Python 3.11 также поддерживается, но рекомендуется 3.12

### Известные проблемы

1. **aiohttp 3.8.x не компилируется на Python 3.12**
   - Решение: используйте aiohttp >= 3.11.0

2. **datetime.utcnow deprecated**
   - Решение: использован `datetime.now(timezone.utc)`

3. **sqlalchemy.ext.declarative deprecated**
   - Решение: используйте `sqlalchemy.orm.declarative_base`

### Откат к старой версии

Если нужно вернуться к Python 3.11:

```bash
# Установите Python 3.11
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.11 python3.11-venv python3.11-dev

# Пересоздайте окружение
rm -rf .venv
python3.11 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
```

### Тестирование

Проверка успешности обновления:
```bash
make run  # Бот должен запуститься без ImportError
```

Если видите ошибку `Unauthorized`, это нормально — нужно настроить `.env` с вашим BOT_TOKEN.