Win10Toast (jithurjacob/windows-10-toast-notifications)

Win10Toast

https://github.com/jithurjacob/windows-10-toast-notifications
Admin
Win10Toast is a Python library for displaying Windows 10 toast notifications with customizable...

Tokens:1,657
Snippets:14
Trust Score:7.8
Update:1 week ago
Show doc for...
Context Summary (auto-generated)
Raw
# Win10Toast

Win10Toast is a Python library for displaying Windows 10 toast notifications. It provides a simple, easy-to-use interface for creating native Windows notification popups with customizable titles, messages, icons, and display duration. The library leverages the Windows API through pywin32 to create authentic system tray notifications that integrate seamlessly with the Windows 10 notification center.

The library is designed for Windows GUI development and automation scenarios where visual notifications are needed. It supports both blocking and threaded notification modes, allowing developers to either wait for notifications to complete or run them in the background while continuing other operations. The default Python icon is used when no custom icon is specified, making it simple to get started with minimal configuration.

## ToastNotifier Class

The `ToastNotifier` class is the main interface for creating and displaying Windows 10 toast notifications. It manages the Windows message loop and notification lifecycle, handling icon loading, window registration, and cleanup automatically.

```python
from win10toast import ToastNotifier

# Initialize the toast notifier
toaster = ToastNotifier()
```

## show_toast Method

The `show_toast` method displays a Windows 10 toast notification with the specified title, message, icon, and duration. Parameters include `title` (notification title, default "Notification"), `msg` (notification message, default "Here comes the message"), `icon_path` (path to .ico file or None for default), `duration` (seconds to display, default 5), and `threaded` (whether to run in background thread, default False). Returns True on success, or False if a threaded notification is already active.

```python
from win10toast import ToastNotifier
import time

toaster = ToastNotifier()

# Basic notification (blocking - waits for duration)
toaster.show_toast(
    "Hello World!!!",
    "Python is 10 seconds awesome!",
    duration=10
)

# Notification with custom icon
toaster.show_toast(
    "Custom Icon Example",
    "This notification has a custom icon",
    icon_path="custom.ico",
    duration=5
)

# Threaded notification (non-blocking - runs in background)
toaster.show_toast(
    "Background Notification",
    "This notification runs in its own thread!",
    icon_path=None,
    duration=5,
    threaded=True
)

# Wait for threaded notification to finish before continuing
while toaster.notification_active():
    time.sleep(0.1)

print("Notification finished!")
```

## notification_active Method

The `notification_active` method checks whether a threaded notification is currently being displayed. It returns True if a notification thread is active and alive, False otherwise. This is essential for managing threaded notifications to prevent overlapping displays.

```python
from win10toast import ToastNotifier
import time

toaster = ToastNotifier()

# Start a threaded notification
toaster.show_toast(
    "Processing",
    "Task is running in background...",
    duration=10,
    threaded=True
)

# Check if notification is still showing
if toaster.notification_active():
    print("Notification is currently displayed")

# Perform other work while notification shows
counter = 0
while toaster.notification_active():
    counter += 1
    time.sleep(0.5)
    print(f"Working... ({counter})")

print("Notification completed, ready for next one")

# Now safe to show another notification
toaster.show_toast(
    "Complete",
    "All tasks finished!",
    duration=3
)
```

## Command Line Usage

Win10Toast can be run directly as a module to display test notifications. This is useful for verifying the installation works correctly on your Windows system.

```bash
# Run the module directly to see example notifications
python -m win10toast
```

## Summary

Win10Toast is ideal for desktop applications, automation scripts, and system monitoring tools that need to alert users through native Windows notifications. Common use cases include notifying users when long-running tasks complete, displaying alerts for system events, showing reminder messages in productivity applications, and providing feedback in GUI applications without interrupting the user workflow.

Integration is straightforward: install via pip, import the `ToastNotifier` class, and call `show_toast` with your desired parameters. For applications that need to continue processing while showing notifications, use the `threaded=True` parameter combined with `notification_active()` polling to manage notification lifecycle. The library handles all Windows API interactions internally, including window class registration, icon loading, and proper cleanup after notifications are dismissed.