## `ProgressMessage` — умный прогресс-бар в виде строки

Класс `ProgressMessage` генерирует информативную строку с метриками выполнения длительной операции:

- **Прогресс**: `обработано/всего//осталось`
- **Процент завершения**
- **Скорость обработки** (Items Per Second — IPS)
- **Прошедшее время** (Elapsed Time — ET)
- **Оставшееся время** (Remaining Time — RT)

Особенность: поддерживает **умное логирование** — можно выводить прогресс **каждый раз** или **только с заданной
периодичностью**, чтобы не засорять лог.

> ✅ Финальное сообщение (100%) всегда логируется, даже если интервал ещё не прошёл.

---

### 🔧 Пример использования

```python
from datetime import timedelta
from src.onco_cola_utils.progress_message import ProgressMessage


total = 100_000_000

# Логировать прогресс не чаще чем раз в 5 секунд
pm = ProgressMessage(
    total=total,
    every=timedelta(seconds=5)
)

for i in range(1, total + 1):
    # ... ваша полезная работа ...
    pm.update(i)
    
    # Вариант 1: просто напечатать строку (например, в CLI)
    print(f"Обработка: {pm.msg}")
    
    # Вариант 2: делегировать логирование классу — он сам решит, писать ли в лог
    pm.log_me("Обработка: {log}")
```

---

### 📌 Пояснение параметров

| Параметр     | Тип         | Описание                                                                   |
|--------------|-------------|----------------------------------------------------------------------------|
| `total`      | `int`       | Общее количество элементов (обязательно > 0).                              |
| `processed`  | `int`       | Уже обработано (по умолчанию `0`).                                         |
| `start_time` | `float`     | Время начала (в формате `time.time()`). Если не указано — берётся текущее. |
| `every`      | `timedelta` | Интервал между записями в лог. Если `None` — логировать **каждый вызов**.  |

> 💡 При создании объекта автоматически выводится информационное сообщение через `loginf`, указывающее режим логирования.

---

### 🧠 Как работает `log_me()`

Метод `log_me(template="{log}")`:

- Подставляет актуальную строку прогресса вместо `{log}` в шаблон.
- Логирует **всегда**, если достигнут 100% (`processed >= total`).
- Иначе — логирует **только если прошло достаточно времени** (согласно `every`) или если `every=None`.

Это позволяет избежать миллионов строк в логе при обработке больших объёмов данных.

---

### 📦 Интеграция

Класс использует стандартный логгер из `onco_cola_utils`:

- `log()` — для записи прогресса
- `loginf()` — для информационных сообщений при инициализации

Убедитесь, что логирование настроено в вашем проекте.
