WinToastCreator 0.2.4

WinToastCreator — модуль для отправки уведомлений в Windows

WinToastCreator — модуль для отправки уведомлений в Windows

Лёгкий import WinToastCreator.creator‑модуль (несколько КБ) для создания и управления всплывающими уведомлениями (toast) в Windows через WinRT API.

Что нового в версии 0.2.4:

• В инструкции добавлены все методы из WinToastCreator.settings
• Теперь наша библиотека работает полноценно в Windows 8.1 (не в 8.0)

Возможности

• Отправка простых уведомлений с заголовком и текстом.
• Добавление иконок, изображений, прогресса.
• Воспроизведение звуков и речи (TTS).
• Обработка кликов, закрытия и ошибок.
• Поддержка ввода и выбора в уведомлениях.
• Обновление прогресса и очистка уведомлений.
• Асинхронный и синхронный интерфейсы.

Установка

Модуль не требует установки внешних зависимостей — использует встроенные WinRT‑библиотеки Windows.

pip install WinToastCreator

В таблице ниже перечислены все параметры, доступные в методах toast и toast_async.

Параметр	Тип	Описание
title	str	Заголовок уведомления. Отображается крупным шрифтом в верхней части.
body	str	Основной текст уведомления. Располагается под заголовком.
on_click	callable	Функция‑обработчик, вызываемая при клике по уведомлению. Принимает аргументы события.
icon	str / dict	Иконка уведомления: – строка — путь к файлу иконки; – словарь — с ключами placement, hint-crop, src.
image	str / dict	Дополнительное изображение: – строка — путь к файлу; – словарь — с ключами src, placement.
progress	dict	Параметры индикатора прогресса: ключи value (доля, напр. 0.5), title (заголовок прогресса), status (текст статуса).
audio	str / dict	Звук уведомления: – строка — путь к аудиофайлу или системный префикс ms- (напр. ms-wakeup); – словарь — с ключом src.
dialogue	str	Текст для озвучивания через синтез речи (TTS). Будет произнесён при показе уведомления.
duration	str	Длительность отображения: "short" (короткий) или "long" (длинный).
input	str / dict	Поле ввода: – строка — ID поля; – словарь — с ключами id, type ("text" и др.), placeHolderContent (подсказка).
inputs	list	Список полей ввода (каждый элемент — строка или словарь, как для input).
selection	str / list	Элемент выбора: – строка — значение элемента; – список — набор вариантов (каждый — строка или словарь с id, content).
selections	list	Список элементов выбора (каждый — строка или словарь с id, content).
button	str / dict	Кнопка: – строка — текст кнопки (и аргумент запуска); – словарь — с ключами content (текст), activationType (тип активации), arguments (аргументы запуска).
buttons	list	Список кнопок (каждый элемент — строка или словарь, как для button).
xml	str	Шаблон XML для уведомления. По умолчанию — стандартный toast‑шаблон.
app_id	str	ID приложения, под которым показывается уведомление. По умолчанию: "import WinToastCreator.creator".
ocr	str / dict	Путь к изображению для распознавания текста (OCR): – строка — путь к файлу; – словарь — с ключом ocr (путь) и опционально lang (язык).
on_dismissed	callable	Функция‑обработчик, вызываемая при закрытии уведомления. Принимает аргумент события.
on_failed	callable	Функция‑обработчик, вызываемая при ошибке показа уведомления. Принимает аргумент ошибки.
scenario	str	Сценарий уведомления (напр., "email", "im", "reminder"). Влияет на поведение и внешний вид.
tag	str	Тег уведомления. Используется для идентификации при обновлении или удалении.
group	str	Группа уведомлений. Позволяет управлять набором уведомлений по группе (очистка, обновление).
timeout	float	Тайм‑аут в секундах для ожидания событий (клик, закрытие и т.п.). По истечении — функция завершается.

В таблице ниже перечислены все методы, доступные в WinToastCreator.settings.

Параметр	Тип	Описание
toggle_focus	method	Переключает режим «Не беспокоить». Если этот режим включен значит выключит или наоборот, был выключен а теперь включен.
enable_notify_icon_on_the_taskbar	method	Включает иконку уведомления на панели задач (в правом краю).
disable_notify_icon_on_the_taskbar	method	Выключает иконку уведомления на панели задач.

Примечания:

• Для обновления прогресса или очистки уведомлений обязательно указывайте group (иначе возникнет ошибка).
• Параметры tag и group работают совместно: чтобы удалить/обновить конкретное уведомление, нужны оба значения.
• Системные звуки (audio с префиксом ms-) зависят от локализации и версии Windows.

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

1. Простое уведомление

WinToastCreator.creator.toast("Готово!", "Файл загружен успешно")

2. Уведомление с кнопкой

WinToastCreator.creator.toast( "Открыть сайт", "Перейдите на наш ресурс", button="https://example.com", on_click=lambda e: print("Клик:", e['arguments']) )

3. Уведомление с прогрессом

WinToastCreator.creator.toast("Загрузка...", "Идет загрузка файла", progress={'value': '0.5', 'title': 'Прогресс', 'status': '50%'})

4. Обновление прогресса

WinToastCreator.creator.toast("Загрузка", "Начата...", tag="download", group="files") WinToastCreator.creator.update_progress({'value': '0.8', 'status': '80%'}, tag="download", group="files")

5. Очистка уведомлений

WinToastCreator.creator.clear_toast(group="files") # Удалить все уведомления группы "files" WinToastCreator.creator.clear_toast(tag="download", group="files") # Удалить по тегу и группе

6. Асинхронное уведомление с TTS

async def show_notification(): await WinToastCreator.creator.toast_async("Внимание", "Это сообщение будет озвучено", dialogue="Привет, это TTS!") asyncio.run(show_notification())

7. Распознавание текста с изображения (OCR)

WinToastCreator.creator.toast("OCR", ocr="path/to/image.png")

8. Переключение режима «Не беспокоить»

Предупреждение! Этот метод начнёт управлять вашим компьютером WinToastCreator.settings.toggle_focus()

9. Отображение иконки уведомления на панели задач (в правом конце панели задач)

WinToastCreator.settings.enable_notify_icon_on_the_taskbar()

Для работы OCR может потребоваться установка языковых пакетов (см. available_recognizer_languages()).

Звуки (audio) могут быть локальными файлами или системными (ms‑wakeup, ms‑call, и т.п.).

Поля ввода и выбора работают только в поддерживаемых сценариях Windows.

Для обновления/очистки уведомлений обязательно указывайте group (иначе возникнет ошибка).

Вспомогательные функции available_recognizer_languages() — выводит список доступных языков OCR.

play_sound(audio) — воспроизводит звук (асинхронно).

speak(text) — озвучивает текст (TTS, асинхронно).

recognize(ocr) — распознаёт текст с изображения (OCR).

Лицензия MIT — свободно используйте, модифицируйте и распространяйте.

Версия: 0.2.4