Telegram Muter

Утилита для автоматического выключения уведомлений Telegram групп до следующего рабочего дня.

Описание

Telegram Muter — это Python-приложение, которое подключается к Telegram API и выключает уведомления во всех группах до начала следующего рабочего дня. Приложение поддерживает сложную логику определения рабочих дней с учетом выходных, рабочих выходных и нерабочих будней.

Функциональность

• Мульти-расписания с наследованием:

  • Создание нескольких именованных расписаний
  • Наследование расписаний от родительских с возможностью переопределения любых свойств
  • Настройка различных расписаний для разных групп по имени или регулярному выражению

• Умное определение следующего рабочего дня с учетом:

  • Обычных выходных дней (по умолчанию суббота и воскресенье)
  • Рабочих выходных (например, рабочая суббота)
  • Нерабочих будней (например, праздничные дни)
  • Временных зон
  • Времени начала и окончания рабочего дня

• Поддержка различных типов чатов:

  • Обычные группы (Chat)
  • Супергруппы и каналы (Channel)
  • Автоматическое пропуск личных чатов

• Два режима работы:

  • mute — выключение уведомлений до следующего рабочего дня (с учетом индивидуальных расписаний групп)
  • unmute — включение уведомлений для чатов, заглушенных до начала следующего рабочего дня

• Защита от заглушения во время рабочих часов:

  • Автоматическая проверка, не находимся ли мы в рабочее время (между start_of_day и end_of_day)
  • Параметр --finish-the-day для принудительного заглушения в конце дня

• Поддержка русских и английских названий дней недели

• Обработка rate limiting от Telegram API

• Пропуск уже заглушенных групп

• Подробное логирование процесса

Алгоритм определения следующего рабочего дня

1. Если текущее время меньше start_of_day в указанной временной зоне, то начальный день = сегодня, иначе завтра.
2. Если день недели начального дня указан в weekends, то это выходной, иначе это будний день.
3. Если это выходной и он указан в working_weekends, то это будний день, иначе добавляем 1 день к начальному дню и переходим к шагу 2.
4. Если это будний день и он указан в nonworking_weekdays (приоритет выше чем у working_weekends), то добавляем 1 день к начальному дню и переходим к шагу 2, иначе мы нашли дату.

Установка

1. Склонируйте репозиторий:

git clone https://github.com/aensidhe/telegram-muter.git
cd telegram-muter

2. Установите зависимости:

pip install -r requirements.txt

3. Создайте файл конфигурации:

cp config.template.toml config.toml

4. Настройте config.toml:

Конфигурация расписаний

[auth]
api_id = 12345  # Ваш API ID от https://my.telegram.org
api_hash = "your_api_hash"  # Ваш API Hash
phone_number = "+1234567890"  # Ваш номер телефона

# Определение расписаний - минимум требуется расписание "default"
[[schedules]]
name = "default"          # Обязательное расписание "default"
start_of_day = "10:00:00" # Время начала рабочего дня
end_of_day = "19:00:00"   # Время окончания рабочего дня - скрипт не будет заглушать в рабочие часы
timezone = "auto"         # "auto" для системной зоны или "Europe/Moscow"
weekends = ["Sat", "Sun"] # Выходные дни

# Рабочие выходные (конкретные даты или интервалы)
working_weekends = [
    "2025-11-01",  # Одиночная дата
    ["2025-12-25", "2025-12-31"]  # Интервал дат
]

# Нерабочие будни (конкретные даты или интервалы)
nonworking_weekdays = [
    "2025-12-31",  # Новый год
    ["2026-01-01", "2026-01-07"]  # Новогодние каникулы
]

# Дополнительные расписания с наследованием

[[schedules]]
name = "work"
parent = "default"        # Наследуется от "default"
start_of_day = "09:00:00" # Переопределение: рабочий день начинается раньше
timezone = "UTC"          # Переопределение: использовать UTC

[[schedules]]
name = "duty"
parent = "work"           # Наследуется от "work"
weekends = []             # Переопределение: дежурство 24/7, выходных нет
working_weekends = []     # Очистка родительских настроек

# Настройки групп (привязка групп к расписаниям)
[[group_settings]]
name = "Рабочий чат"
schedule = "work"         # Точное совпадение имени группы

[[group_settings]]
name_pattern = "duty.*"   # Регулярное выражение для групп начинающихся с "duty"
schedule = "duty"         # Использовать расписание "duty"

[[group_settings]]
name_pattern = "weekend.*"
schedule = "default"      # Группы выходного дня используют расписание по умолчанию

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

Заглушить уведомления (режим по умолчанию)

python telegram_muter.py
# или явно
python telegram_muter.py mute

Принудительно заглушить в конце рабочего дня

python telegram_muter.py mute --finish-the-day

Включить уведомления

python telegram_muter.py unmute

Справка

python telegram_muter.py --help

При первом запуске вам потребуется:

1. Ввести код подтверждения из SMS
2. При необходимости ввести пароль двухфакторной аутентификации

Примечание: Команда unmute найдет и включит уведомления только для тех чатов, которые были заглушены до начала следующего рабочего дня этой программой. Чаты, заглушенные на другое время, останутся заглушенными.

Формат дат и времени

• Время: Формат HH:MM:SS (например, "10:00:00")
• Даты: Только формат ISO8601 YYYY-MM-DD (например, "2025-12-31")
• Дни недели:
  • Английские: Mon, Tue, Wed, Thu, Fri, Sat, Sun
  • Русские: Пн, Вт, Ср, Чт, Пт, Сб, Вс
• Интервалы дат: Массив из двух дат ["2025-12-25", "2025-12-31"] (включая обе границы)

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

Запуск тестов:

# Запуск всех тестов
pytest

# Запуск конкретных тестов
pytest test_working_days.py -v
pytest test_integration.py -v

Структура проекта

• telegram_muter.py — основной файл приложения
• config_tester.py — утилита для тестирования конфигурации
• config.template.toml — шаблон конфигурации
• test_working_days.py — тесты алгоритма рабочих дней
• test_integration.py — интеграционные тесты
• requirements.txt — зависимости Python

Требования

• Python 3.8+
• Telegram API credentials (получите на https://my.telegram.org)
• Активная учетная запись Telegram

Лицензия

MIT — см. файл LICENSE

Поддержка

Если у вас возникли проблемы или вопросы, создайте issue в репозитории GitHub.