obabot 0.1.0__tar.gz

obabot-0.1.0/.github/SECRETS_SETUP.md

@@ -0,0 +1,100 @@
+# Настройка секретов для тестов
+
+Для запуска тестов в GitHub Actions необходимо добавить тестовые токены в секреты репозитория.
+
+## Шаги настройки
+
+1. Перейдите в настройки репозитория: **Settings** → **Secrets and variables** → **Actions**
+
+2. Добавьте следующие секреты:
+
+   - **TG_TEST_TOKEN** - токен Telegram бота для тестирования
+   - **MAX_TEST_TOKEN** - токен Max бота для тестирования
+
+3. Нажмите **New repository secret** для каждого токена
+
+## Получение тестовых токенов
+
+### Telegram
+1. Создайте бота через [@BotFather](https://t.me/BotFather)
+2. Получите токен командой `/newbot`
+3. Используйте этот токен как `TG_TEST_TOKEN`
+
+### Max
+1. Перейдите на [developers.max.ru](https://developers.max.ru)
+2. Создайте приложение и бота
+3. Получите токен бота
+4. Используйте этот токен как `MAX_TEST_TOKEN`
+
+## Структура тестов в CI
+
+GitHub Actions запускает тесты параллельно для максимальной скорости:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Unit Tests                              │
+│  (Python 3.10, 3.13, 3.14 - параллельно)                    │
+└─────────────────────┬───────────────────────────────────────┘
+                      │
+        ┌─────────────┴─────────────┐
+        │                           │
+        ▼                           ▼
+┌───────────────────┐     ┌───────────────────┐
+│   E2E Telegram    │     │     E2E Max       │
+│   (параллельно)   │     │   (параллельно)   │
+└─────────┬─────────┘     └─────────┬─────────┘
+          │                         │
+          └───────────┬─────────────┘
+                      │
+                      ▼
+            ┌─────────────────────┐
+            │  Integration Tests  │
+            │  (требуют токены)   │
+            └─────────────────────┘
+```
+
+### Jobs в CI
+
+| Job | Описание | Зависимости |
+|-----|----------|-------------|
+| `unit-tests` | Быстрые unit тесты без внешних зависимостей | - |
+| `e2e-telegram` | E2E тесты для Telegram | `unit-tests` |
+| `e2e-max` | E2E тесты для Max | `unit-tests` |
+| `compatibility` | Тесты совместимости с разными версиями aiogram | `unit-tests` |
+| `integration` | Интеграционные тесты с реальными API | `e2e-telegram`, `e2e-max` |
+
+## Тесты без токенов
+
+Если токены не указаны:
+- **Unit тесты** — выполняются полностью
+- **E2E тесты** — выполняются с симулированными payload'ами
+- **Integration тесты** — пропускаются (skip)
+
+## Локальный запуск тестов
+
+```bash
+# Все тесты
+pytest tests/ -v
+
+# Только unit тесты
+pytest tests/ -v --ignore=tests/test_e2e_migration.py --ignore=tests/test_integration.py
+
+# Только E2E тесты для Telegram
+pytest tests/test_e2e_migration.py -v -k "telegram"
+
+# Только E2E тесты для Max
+pytest tests/test_e2e_migration.py -v -k "max"
+
+# Тесты для обеих платформ
+pytest tests/test_e2e_migration.py -v -k "dual"
+```
+
+## Маркеры тестов
+
+| Маркер | Описание |
+|--------|----------|
+| `@pytest.mark.e2e` | End-to-end тесты |
+| `@pytest.mark.telegram` | Тесты для Telegram |
+| `@pytest.mark.max` | Тесты для Max |
+| `@pytest.mark.dual` | Тесты для обеих платформ |
+| `@pytest.mark.integration` | Тесты с реальными API |

obabot-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,234 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  # Unit tests - all Python versions in parallel
+  unit-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.13", "3.14"]
+
+    name: Unit (Py ${{ matrix.python-version }})
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade "typing_extensions>=4.8.0"
+        pip install pytest pytest-asyncio pytest-cov
+        pip install "aiogram>=3.0.0"
+        pip install -e ".[dev]"
+        pip install --upgrade --force-reinstall "typing_extensions>=4.8.0"
+
+    - name: Run unit tests
+      run: |
+        pytest tests/ -v \
+          --ignore=tests/test_e2e_migration.py \
+          --ignore=tests/test_integration.py \
+          --ignore=tests/test_integration_real.py \
+          --ignore=tests/test_webhook_telegram.py \
+          -m "not integration and not e2e"
+
+  # Test mode (no tokens, no network) — always runs in CI.
+  # We do NOT install aiogram-test-framework: that is for the user's project.
+  # Our tests only need: pytest, pytest-asyncio, aiogram, obabot (and umaxbot via obabot).
+  test-mode:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.13"]
+
+    name: Test mode (Py ${{ matrix.python-version }})
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest pytest-asyncio
+        pip install "aiogram>=3.0.0"
+        pip install -e .
+
+    - name: Run test-mode tests
+      run: |
+        pytest tests/test_test_mode.py tests/test_basic.py -v -k "test_mode or test_create_bot_no_tokens"
+
+  # E2E tests for Telegram
+  e2e-telegram:
+    runs-on: ubuntu-latest
+
+    name: E2E Telegram
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.13
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade "typing_extensions>=4.8.0"
+        pip install pytest pytest-asyncio pytest-cov
+        pip install "aiogram>=3.0.0"
+        pip install -e ".[dev]"
+        pip install --upgrade --force-reinstall "typing_extensions>=4.8.0"
+
+    - name: Run E2E Telegram tests
+      env:
+        TG_TOKEN: ${{ secrets.TG_TEST_TOKEN }}
+      run: |
+        pytest tests/test_e2e_migration.py tests/test_webhook_telegram.py -v \
+          -k "telegram or Telegram or tg or dual" \
+          --cov=obabot --cov-report=xml
+
+    - name: Upload coverage
+      uses: codecov/codecov-action@v3
+      with:
+        file: ./coverage.xml
+        flags: e2e-telegram
+
+  # E2E tests for Max
+  e2e-max:
+    runs-on: ubuntu-latest
+
+    name: E2E Max
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.13
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade "typing_extensions>=4.8.0"
+        pip install pytest pytest-asyncio pytest-cov
+        pip install "aiogram>=3.0.0"
+        pip install -e ".[dev]"
+        pip install --upgrade --force-reinstall "typing_extensions>=4.8.0"
+
+    - name: Run E2E Max tests
+      env:
+        MAX_TOKEN: ${{ secrets.MAX_TEST_TOKEN }}
+      run: |
+        pytest tests/test_e2e_migration.py -v \
+          -k "max or Max" \
+          --cov=obabot --cov-report=xml
+
+    - name: Upload coverage
+      uses: codecov/codecov-action@v3
+      with:
+        file: ./coverage.xml
+        flags: e2e-max
+
+  # Compatibility tests - different aiogram versions
+  compatibility:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.10"
+            aiogram-version: "3.0.0"
+            test-name: "aiogram-3.0"
+          - python-version: "3.13"
+            aiogram-version: "3.24"
+            test-name: "aiogram-3.24"
+          - python-version: "3.14"
+            aiogram-version: ""
+            test-name: "aiogram-latest"
+
+    name: Compat ${{ matrix.test-name }}
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade "typing_extensions>=4.8.0"
+        pip install pytest pytest-asyncio pytest-cov
+        
+        if [ "${{ matrix.aiogram-version }}" != "" ]; then
+          pip install "aiogram==${{ matrix.aiogram-version }}"
+        else
+          pip install "aiogram>=3.0.0"
+        fi
+        
+        pip install -e ".[dev]"
+        pip install --upgrade --force-reinstall "typing_extensions>=4.8.0"
+
+    - name: Run compatibility tests
+      run: |
+        pytest tests/test_compatibility.py tests/test_aiogram_comparison.py -v
+
+  # Integration tests - require real tokens
+  integration:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+
+    name: Integration
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.13
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade "typing_extensions>=4.8.0"
+        pip install pytest pytest-asyncio pytest-cov
+        pip install "aiogram>=3.0.0"
+        pip install -e ".[dev]"
+        pip install --upgrade --force-reinstall "typing_extensions>=4.8.0"
+
+    - name: Run integration tests
+      env:
+        TG_TOKEN: ${{ secrets.TG_TEST_TOKEN }}
+        MAX_TOKEN: ${{ secrets.MAX_TEST_TOKEN }}
+      run: |
+        pytest tests/test_integration.py -v -m integration \
+          --cov=obabot --cov-report=xml
+
+    - name: Upload coverage
+      uses: codecov/codecov-action@v3
+      with:
+        file: ./coverage.xml
+        flags: integration

obabot-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+coverage.xml
+*.cover
+
+# Environment variables
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log
+.cursor/
+

obabot-0.1.0/BUSINESS_VALUE.md

@@ -0,0 +1,218 @@
+# Бизнес-ценность obabot
+
+## Что видит новый пользователь
+
+Когда разработчик открывает репозиторий obabot, он видит:
+
+### 🎯 Главная ценность: "Пиши один раз — работай везде"
+
+**Проблема, которую решает библиотека:**
+
+Разработчики ботов сталкиваются с необходимостью поддерживать код для разных мессенджеров (Telegram, Max и др.). Это означает:
+- Дублирование кода
+- Двойная поддержка
+- Сложность миграции между платформами
+- Разные API и подходы
+
+**Решение obabot:**
+
+Один код → работает на Telegram, Max или обеих платформах одновременно.
+
+---
+
+## Основные преимущества
+
+### 1. ⚡ Экономия времени разработки
+
+**Без obabot:**
+```
+Telegram бот: 1000 строк кода
+Max бот:      1000 строк кода (почти идентичных)
+Итого:        2000 строк, двойная поддержка
+```
+
+**С obabot:**
+```
+Универсальный бот: 1000 строк кода
+Итого:             1000 строк, одна поддержка
+```
+
+**Экономия: 50% кода и времени на поддержку**
+
+### 2. 🔄 Простота миграции
+
+**Сценарий:** Вы написали бота для Telegram, но нужно запустить его на Max.
+
+**Без obabot:**
+- Переписывать все хендлеры под API Max
+- Изучать новую библиотеку (aiomax)
+- Адаптировать FSM, клавиатуры, медиа
+- Тестировать заново
+- **Время: дни/недели работы**
+
+**С obabot:**
+- Меняете одну строку: `tg_token` → `max_token`
+- Всё остальное работает автоматически
+- **Время: 30 секунд**
+
+### 3. 💰 Снижение затрат на поддержку
+
+**Проблема:** Два кодабаза = двойные баги, двойные обновления, двойное тестирование
+
+**Решение:** Один кодбаза = один багфикс исправляет обе платформы
+
+**Пример:**
+- Нашли баг в логике регистрации
+- Исправили в одном месте
+- Работает на Telegram и Max автоматически
+
+### 4. 🚀 Быстрый старт на новых платформах
+
+**Сценарий:** У вас есть успешный Telegram-бот, хотите запустить на Max.
+
+**Без obabot:**
+- Нужен разработчик, знающий aiomax
+- Нужно время на изучение API
+- Риск ошибок при портировании
+- **Срок: 1-2 недели**
+
+**С obabot:**
+- Меняете токен
+- Запускаете
+- **Срок: 5 минут**
+
+### 5. 🎛️ Гибкость: одна или обе платформы
+
+**Вариант 1:** Только Telegram
+```python
+bot, dp, router = create_bot(tg_token="TOKEN")
+```
+
+**Вариант 2:** Только Max
+```python
+bot, dp, router = create_bot(max_token="TOKEN")
+```
+
+**Вариант 3:** Обе платформы одновременно
+```python
+bot, dp, router = create_bot(tg_token="TG", max_token="MAX")
+# Один код обрабатывает сообщения с обеих платформ!
+```
+
+---
+
+## Реальные сценарии использования
+
+### Сценарий 1: Стартап с ограниченным бюджетом
+
+**Ситуация:** Нужен бот для Telegram и Max, но бюджет на разработку ограничен.
+
+**С obabot:**
+- Написали один раз
+- Запустили на обеих платформах
+- Экономия: 50% бюджета на разработку
+
+### Сценарий 2: Миграция с Telegram на Max
+
+**Ситуация:** Решили перейти с Telegram на Max (или наоборот).
+
+**Без obabot:**
+- Переписывать весь код
+- Риск потерять функциональность
+- Долгий процесс миграции
+
+**С obabot:**
+- Меняете токен
+- Всё работает
+- Миграция за минуты
+
+### Сценарий 3: Мультиплатформенный бот
+
+**Ситуация:** Нужен бот, который работает и в Telegram, и в Max одновременно.
+
+**Без obabot:**
+- Два отдельных бота
+- Дублирование логики
+- Сложная синхронизация данных
+
+**С obabot:**
+- Один бот, одна логика
+- Автоматическая обработка обеих платформ
+- Простота поддержки
+
+---
+
+## Технические преимущества
+
+### ✅ Совместимость с aiogram
+
+Если вы уже знаете aiogram — вы уже знаете obabot. API идентичен.
+
+### ✅ Минимальные изменения при миграции
+
+```python
+# Было (aiogram):
+from aiogram import Bot, Dispatcher, Router
+bot = Bot(token="...")
+dp = Dispatcher()
+router = Router()
+
+# Стало (obabot):
+from obabot import create_bot
+bot, dp, router = create_bot(tg_token="...")
+```
+
+**Изменения: 2 строки импорта + 1 строка инициализации**
+
+### ✅ Нативная производительность для Telegram
+
+Telegram работает напрямую через aiogram — без накладных расходов.
+
+### ✅ Прозрачная адаптация для Max
+
+Max автоматически адаптируется под API aiogram — вы не замечаете разницы.
+
+---
+
+## Итоговая ценность
+
+### Для разработчика:
+- ⏱️ **Экономия времени:** пишете код один раз
+- 🧠 **Меньше когнитивной нагрузки:** один API вместо двух
+- 🐛 **Меньше багов:** один кодбаза = меньше мест для ошибок
+
+### Для бизнеса:
+- 💵 **Экономия денег:** меньше разработки = меньше затрат
+- ⚡ **Быстрее на рынок:** запуск на новой платформе за минуты
+- 🔒 **Меньше рисков:** миграция между платформами безболезненна
+- 📈 **Масштабируемость:** легко добавить третью платформу в будущем
+
+### Для проекта:
+- 📦 **Один кодбаза:** проще поддерживать
+- 🧪 **Одно тестирование:** тесты покрывают обе платформы
+- 📝 **Одна документация:** не нужно дублировать
+
+---
+
+## Кому подходит obabot?
+
+✅ **Разработчикам ботов на aiogram** — минимальная миграция  
+✅ **Стартапам** — экономия бюджета на разработку  
+✅ **Компаниям с мультиплатформенными ботами** — упрощение поддержки  
+✅ **Проектам, планирующим миграцию** — снижение рисков  
+✅ **Командам с ограниченными ресурсами** — максимум результата при минимуме кода
+
+---
+
+## ROI (Return on Investment)
+
+**Инвестиция:** Изучение obabot (30 минут) + миграция (1 час)
+
+**Возврат:**
+- Экономия 50% времени на разработку для второй платформы
+- Экономия 50% времени на поддержку
+- Возможность быстрого запуска на новых платформах
+- Снижение рисков при миграции
+
+**Вывод:** Инвестиция окупается уже при первом использовании.
+