# Анимированный логгер - Документация

## Обзор

`AnimatedRequestLogger` - это расширенная версия `RequestLogger` с анимациями:
- 🔄 **Спиннер** во время выполнения запроса
- ✨ **Анимированный результат** - круг заполняется и превращается в ✓ или ✗
- 🎨 **Цветные спиннеры** - можно выбрать цвет для разных типов запросов

## Как это выглядит

### 1. Во время запроса (спиннер)
```
⠋ 23:40:48 | FETCH.PROFILE        | N/A
⠙ 23:40:48 | FETCH.PROFILE        | N/A
⠹ 23:40:48 | FETCH.PROFILE        | N/A
⠸ 23:40:48 | FETCH.PROFILE        | N/A
```

### 2. Анимация результата
```
○ 23:40:50 |  1.732с    | FETCH.PROFILE        | httpbin.org/get                [200]
◔ 23:40:50 |  1.732с    | FETCH.PROFILE        | httpbin.org/get                [200]
◑ 23:40:50 |  1.732с    | FETCH.PROFILE        | httpbin.org/get                [200]
◕ 23:40:50 |  1.732с    | FETCH.PROFILE        | httpbin.org/get                [200]
● 23:40:50 |  1.732с    | FETCH.PROFILE        | httpbin.org/get                [200]
✓ 23:40:50 |  1.732с    | FETCH.PROFILE        | httpbin.org/get                [200]
```

### 3. Финальный вывод

**Успех:**
```
✓ 23:40:50 |  1.732с    | FETCH.PROFILE        | httpbin.org/get                [200]
  └─ response:
     └─ body: {
  "origin": "31.202.139.105",
  "url": "https://httpbin.org/get"
}
```

**Ошибка:**
```
✗ 23:40:52 |  1.088с    | FETCH.BALANCE        | httpbin.org/status/404         [404]
```

## Использование

### Базовый пример

```python
from animated_logger import AnimatedRequestLogger, ResponseValidator
from action import LOG_ACTION

@AnimatedRequestLogger.log(
    LOG_ACTION.FETCH.PROFILE,
    log_level="full",
    show_body=True,
    animate=True  # Включить анимацию
)
@ResponseValidator.status([200])
async def get_profile(client):
    return await client.get('https://api.example.com/profile')
```

### С настройкой цвета спиннера

```python
@AnimatedRequestLogger.log(
    LOG_ACTION.SEND.FORM,
    log_level="full",
    show_body=True,
    show_response_headers=True,
    show_request_headers=True,
    animate=True,
    spinner_color="\033[95m"  # Magenta спиннер
)
@ResponseValidator.status([200])
async def submit_form(client):
    return await client.post(
        'https://api.example.com/submit',
        json={"data": "test"},
        headers={"X-API-Key": "secret"}
    )
```

### Без анимации (как обычный логгер)

```python
@AnimatedRequestLogger.log(
    LOG_ACTION.FETCH.DATA,
    log_level="success_error",
    show_body=True,
    animate=False  # БЕЗ анимации
)
@ResponseValidator.status([200])
async def get_data(client):
    return await client.get('https://api.example.com/data')
```

## Параметры декоратора

```python
@AnimatedRequestLogger.log(
    action: str,                          # Название действия (обязательно)
    log_level: Literal["full", "success_error", "error_only"] = "full",
    show_body: bool = False,              # Показывать тело ответа
    len_text: int = 150,                  # Макс. длина текста
    show_response_headers: bool = False,  # Показывать заголовки ответа
    show_request_headers: bool = False,   # Показывать заголовки запроса
    animate: bool = True,                 # Включить анимации
    spinner_color: str = "\033[96m",      # ANSI цвет спиннера
    enabled: bool = True,                 # Включить/выключить логирование
)
```

## Цвета спиннера

Доступные ANSI коды цветов:

```python
"\033[90m"  # gray (серый)
"\033[91m"  # red (красный)
"\033[92m"  # green (зеленый)
"\033[93m"  # yellow (желтый)
"\033[94m"  # blue (синий)
"\033[95m"  # magenta (пурпурный)
"\033[96m"  # cyan (голубой) - по умолчанию
"\033[97m"  # white (белый)
```

## Примеры из демонстрации

### 1. GET запрос с анимацией
```python
@AnimatedRequestLogger.log(
    LOG_ACTION.FETCH.PROFILE,
    log_level="full",
    show_body=True,
    len_text=200,
    animate=True
)
@ResponseValidator.status([200])
async def test_simple_get(client):
    return await client.get('https://httpbin.org/get')
```

**Результат:**
- Спиннер показывается во время запроса
- Анимированный переход: ○ → ◔ → ◑ → ◕ → ● → ✓
- Отображается тело ответа

### 2. POST с заголовками и magenta спиннером
```python
@AnimatedRequestLogger.log(
    LOG_ACTION.SEND.FORM,
    log_level="full",
    show_body=True,
    show_response_headers=True,
    show_request_headers=True,
    animate=True,
    spinner_color="\033[95m"  # Magenta
)
@ResponseValidator.status([200])
async def test_post(client):
    return await client.post(
        'https://httpbin.org/post',
        json={"action": "test", "user_id": 12345},
        headers={"X-API-Key": "secret123"}
    )
```

**Результат:**
- Magenta спиннер во время запроса
- Показываются request и response блоки
- Headers и body отображаются в структурированном виде

### 3. Запрос с ошибкой (yellow спиннер)
```python
@AnimatedRequestLogger.log(
    LOG_ACTION.FETCH.BALANCE,
    log_level="full",
    animate=True,
    spinner_color="\033[93m"  # Yellow
)
@ResponseValidator.status([200])  # Ожидаем 200, но получим 404
async def test_error(client):
    return await client.get('https://httpbin.org/status/404')
```

**Результат:**
- Yellow спиннер во время запроса
- Анимированный переход к ошибке: ○ → ◔ → ◑ → ◕ → ● → ✗
- Красный статус код [404]

### 4. Медленный запрос (2 секунды)
```python
@AnimatedRequestLogger.log(
    LOG_ACTION.FETCH.COOKIES,
    log_level="full",
    show_body=True,
    animate=True
)
@ResponseValidator.status([200])
async def test_slow(client):
    return await client.get('https://httpbin.org/delay/2')
```

**Результат:**
- Спиннер крутится ~2 секунды во время запроса
- Отображается elapsed time: 2.634с
- Показывается тело ответа

## Технические детали

### Как работает спиннер

1. **Запуск в отдельном потоке** - не блокирует выполнение запроса
2. **Анимация кадров** - 10 кадров (⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏) по кругу
3. **Обновление каждые 0.1 сек** - плавная анимация
4. **Автоматическая остановка** - после завершения запроса

### Как работает анимация результата

1. **5 кадров** - ○ → ◔ → ◑ → ◕ → ●
2. **Смена цвета** - желтый (промежуточные) → зеленый/красный (финал)
3. **Длительность** - 0.4 секунды (по 0.08 сек на кадр)
4. **Финальный символ** - ✓ (успех) или ✗ (ошибка)

## Преимущества

### С анимацией:
- ✅ **Визуальная обратная связь** - видно что запрос выполняется
- ✅ **Интересный UX** - приятнее смотреть чем статичные логи
- ✅ **Разные цвета** - можно различать типы запросов
- ✅ **Показывает прогресс** - понятно что система работает

### Без анимации:
- ✅ **Быстрее** - нет задержки на анимацию
- ✅ **Меньше шума** - статичный вывод
- ✅ **Подходит для CI/CD** - где анимации не нужны

## Запуск демонстрации

```bash
python animated_logger.py
```

Демонстрация включает 6 тестов:
1. Простой GET запрос с анимацией
2. POST с заголовками и magenta спиннером
3. Запрос с ошибкой 404 (yellow спиннер)
4. Медленный запрос (2 секунды задержки)
5. Несколько быстрых запросов подряд
6. Запрос БЕЗ анимации (для сравнения)

## Сравнение с обычным логгером

### AnimatedRequestLogger (с анимацией)
```
⠋ 23:40:48 | FETCH.PROFILE        | N/A
⠙ 23:40:48 | FETCH.PROFILE        | N/A
...
○ 23:40:50 |  1.732с    | FETCH.PROFILE        | httpbin.org/get                [200]
◔ 23:40:50 |  1.732с    | FETCH.PROFILE        | httpbin.org/get                [200]
...
✓ 23:40:50 |  1.732с    | FETCH.PROFILE        | httpbin.org/get                [200]
```

### RequestLogger (обычный)
```
23:40:48 | • DEBUG     0.000с |-> FETCH.PROFILE        | N/A                           [000]
23:40:50 | ✓ SUCCESS   1.732с |-> FETCH.PROFILE        | httpbin.org/get               [200]
```

## Рекомендации

### Когда использовать анимацию:
- 🎯 Локальная разработка
- 🎯 Демонстрации и презентации
- 🎯 Интерактивные CLI приложения
- 🎯 Когда запросы занимают >1 секунды

### Когда НЕ использовать анимацию:
- ❌ CI/CD пайплайны
- ❌ Логирование в файлы
- ❌ Очень быстрые запросы (<0.5 сек)
- ❌ Batch обработка большого количества запросов

## Итог

Анимированный логгер добавляет визуальную обратную связь к HTTP запросам, делая CLI более живым и интересным. При этом сохраняется вся функциональность оригинального логгера с иерархической структурой request/response блоков.
