yyds-notify-os 0.2.0__tar.gz

yyds_notify_os-0.2.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: yyds-notify-os
+Version: 0.2.0
+Summary: A high-performance, lightweight, and easy-to-use cross-platform desktop notification library for Python.
+Home-page: https://github.com/yyds-fast/yyds-notify-os
+Author: yyds-fast
+Author-email: yyds.fast@gmail.com
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-python
+Dynamic: summary
+
+# yyds-notify-os
+
+A high-performance, lightweight, and easy-to-use cross-platform desktop notification library for Python.
+
+[中文说明 (Chinese README)](README_CN.md)
+
+---
+
+## 💡 Key Features
+
+* **Zero External Dependencies**: Implemented strictly using the Python standard library. It interacts with native OS notification tools via subprocesses.
+* **Microsecond-Level Startup**: Highly optimized imports (under 1ms), leaving virtually zero performance footprint.
+* **Non-blocking by Default**: Notifications are dispatched asynchronously in background daemon threads, keeping your application GUI or CLI completely lag-free.
+* **Notification Replacement/Updating (`replace_id`)**: Update an existing notification card in-place (ideal for progress bars or dynamic alerts) without cluttering the Action Center.
+* **Modern Windows Customizations**: Uses Microsoft's modern `ToastGeneric` template to support custom application icons (`icon`) and mapped system sounds (`sound`) or mute configurations.
+* **Path Auto-Resolution**: Automatically converts relative icon paths to absolute paths to prevent subprocess path resolution failures.
+* **Robust Fail-Safe Fallbacks**: Under headless environments (e.g. SSH sessions) or when graphical notifications fail, it gracefully falls back to console stderr output without crashing.
+* **Command Line Interface (CLI)**: Out-of-the-box `yyds-notify` / `yyds-notify-os` commands for shell script integrations.
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install -U yyds-notify-os
+```
+
+Or install from source in editable mode for local development:
+```bash
+pip install -e .
+```
+
+---
+
+## 💻 Python API Usage
+
+```python
+import yyds_notify_os as notify
+import time
+
+# 1. Simple Usage (Non-blocking by default)
+notify.send("Task Complete", "Your compilation has finished successfully!")
+
+# 2. Dynamic Update/Replacement (Same ID updates the same card in-place)
+for i in range(1, 6):
+    notify.send("Downloading", f"Progress: {i*20}%", replace_id="download_task_1")
+    time.sleep(1)
+
+# 3. Synchronous Blocking Call (Returns True/False based on execution success)
+success = notify.send("Server Alert", "CPU temperature is too high!", urgency="critical", block=True)
+
+# 4. Custom Cross-Platform Configuration
+notify.send(
+    title="Meeting Reminder",
+    message="Technical review starts at 2:00 PM",
+    subtitle="Sprint Sync",       # Supported on macOS and Linux-zenity
+    icon="assets/bell.png",       # Automatically converted to absolute path (Windows/Linux)
+    sound="sms",                  # Windows SMS tone mapping, default sound on macOS
+    urgency="normal",             # Linux urgency levels: 'low', 'normal', 'critical'
+    timeout=5,                    # Display timeout in seconds (Linux)
+    app_name="yyds-notify"        # Custom application sender name (Windows/Linux)
+)
+```
+
+### Windows Built-in Sound Mappings (`sound` parameter)
+* `"default"`: Default system sound
+* `"im"`: Instant message sound
+* `"mail"`: Email notification sound
+* `"reminder"`: Calendar reminder sound
+* `"sms"`: SMS/Text message sound
+* `"alarm"`: Looping alarm sound
+* `"call"`: Looping ringtone sound
+
+### API Aliases
+The following functions are identical aliases for convenience:
+* `yyds_notify_os.notify(...)`
+* `yyds_notify_os.send(...)`
+* `yyds_notify_os.show(...)`
+
+---
+
+## 🛠️ CLI Usage
+
+Once installed, send system notifications directly from your shell:
+
+```bash
+# Basic notification
+yyds-notify "Notification" "Your build is ready!"
+
+# Specify custom sender name
+yyds-notify "Alert" "High memory usage detected!" -a "SystemMonitor"
+
+# Dynamic notification updates using replace-id
+yyds-notify "Build Status" "Compiling Module A..." -r "build_job_12"
+yyds-notify "Build Status" "Compiling Module B..." -r "build_job_12"
+
+# Complex call with sound and critical urgency
+yyds-notify "Error" "Deployment failed!" -s "CI Pipeline" -u critical --sound
+
+# View full help menu
+yyds-notify --help
+```
+
+---
+
+## 🛡️ Technical Implementation Details
+
+1. **Windows**:
+   - Uses PowerShell to interface with the Windows Runtime (WinRT) `ToastGeneric` visual template.
+   - All string arguments (title, message, icon path) are passed via **process environment variables** to completely avoid shell injection and encoding/truncation issues (e.g. UTF-8/GBK encoding clashes).
+   - Maps `replace_id` to the `ToastNotification.Tag` property for in-place card updates.
+   - Gracefully attempts to initialize the ToastNotifier with your custom `app_name`. If it fails (due to unregistered AppUserModelId on older Windows releases), it falls back to a guaranteed registered PowerShell AppID.
+   - If WinRT initialization fails, it falls back to the classic balloon tip (`System.Windows.Forms.NotifyIcon`).
+
+2. **macOS**:
+   - Executes AppleScript (`osascript`) with display notification instructions.
+   - Implements robust escaping for double quotes and backslashes to eliminate script execution failures.
+
+3. **Linux**:
+   - Detects `DISPLAY` and `WAYLAND_DISPLAY` environments.
+   - If GUI is present, uses `notify-send` with a progressive fallback array (peels off unsupported options like `-r` or `-a` step-by-step if the local `notify-send` version is outdated). Falls back to `zenity --notification` if `notify-send` is completely absent.
+   - If headless (no GUI), automatically prints notification details to standard error (`sys.stderr`) to prevent crashes.

yyds_notify_os-0.2.0/README.md

@@ -0,0 +1,122 @@
+# yyds-notify-os
+
+A high-performance, lightweight, and easy-to-use cross-platform desktop notification library for Python.
+
+[中文说明 (Chinese README)](README_CN.md)
+
+---
+
+## 💡 Key Features
+
+* **Zero External Dependencies**: Implemented strictly using the Python standard library. It interacts with native OS notification tools via subprocesses.
+* **Microsecond-Level Startup**: Highly optimized imports (under 1ms), leaving virtually zero performance footprint.
+* **Non-blocking by Default**: Notifications are dispatched asynchronously in background daemon threads, keeping your application GUI or CLI completely lag-free.
+* **Notification Replacement/Updating (`replace_id`)**: Update an existing notification card in-place (ideal for progress bars or dynamic alerts) without cluttering the Action Center.
+* **Modern Windows Customizations**: Uses Microsoft's modern `ToastGeneric` template to support custom application icons (`icon`) and mapped system sounds (`sound`) or mute configurations.
+* **Path Auto-Resolution**: Automatically converts relative icon paths to absolute paths to prevent subprocess path resolution failures.
+* **Robust Fail-Safe Fallbacks**: Under headless environments (e.g. SSH sessions) or when graphical notifications fail, it gracefully falls back to console stderr output without crashing.
+* **Command Line Interface (CLI)**: Out-of-the-box `yyds-notify` / `yyds-notify-os` commands for shell script integrations.
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install -U yyds-notify-os
+```
+
+Or install from source in editable mode for local development:
+```bash
+pip install -e .
+```
+
+---
+
+## 💻 Python API Usage
+
+```python
+import yyds_notify_os as notify
+import time
+
+# 1. Simple Usage (Non-blocking by default)
+notify.send("Task Complete", "Your compilation has finished successfully!")
+
+# 2. Dynamic Update/Replacement (Same ID updates the same card in-place)
+for i in range(1, 6):
+    notify.send("Downloading", f"Progress: {i*20}%", replace_id="download_task_1")
+    time.sleep(1)
+
+# 3. Synchronous Blocking Call (Returns True/False based on execution success)
+success = notify.send("Server Alert", "CPU temperature is too high!", urgency="critical", block=True)
+
+# 4. Custom Cross-Platform Configuration
+notify.send(
+    title="Meeting Reminder",
+    message="Technical review starts at 2:00 PM",
+    subtitle="Sprint Sync",       # Supported on macOS and Linux-zenity
+    icon="assets/bell.png",       # Automatically converted to absolute path (Windows/Linux)
+    sound="sms",                  # Windows SMS tone mapping, default sound on macOS
+    urgency="normal",             # Linux urgency levels: 'low', 'normal', 'critical'
+    timeout=5,                    # Display timeout in seconds (Linux)
+    app_name="yyds-notify"        # Custom application sender name (Windows/Linux)
+)
+```
+
+### Windows Built-in Sound Mappings (`sound` parameter)
+* `"default"`: Default system sound
+* `"im"`: Instant message sound
+* `"mail"`: Email notification sound
+* `"reminder"`: Calendar reminder sound
+* `"sms"`: SMS/Text message sound
+* `"alarm"`: Looping alarm sound
+* `"call"`: Looping ringtone sound
+
+### API Aliases
+The following functions are identical aliases for convenience:
+* `yyds_notify_os.notify(...)`
+* `yyds_notify_os.send(...)`
+* `yyds_notify_os.show(...)`
+
+---
+
+## 🛠️ CLI Usage
+
+Once installed, send system notifications directly from your shell:
+
+```bash
+# Basic notification
+yyds-notify "Notification" "Your build is ready!"
+
+# Specify custom sender name
+yyds-notify "Alert" "High memory usage detected!" -a "SystemMonitor"
+
+# Dynamic notification updates using replace-id
+yyds-notify "Build Status" "Compiling Module A..." -r "build_job_12"
+yyds-notify "Build Status" "Compiling Module B..." -r "build_job_12"
+
+# Complex call with sound and critical urgency
+yyds-notify "Error" "Deployment failed!" -s "CI Pipeline" -u critical --sound
+
+# View full help menu
+yyds-notify --help
+```
+
+---
+
+## 🛡️ Technical Implementation Details
+
+1. **Windows**:
+   - Uses PowerShell to interface with the Windows Runtime (WinRT) `ToastGeneric` visual template.
+   - All string arguments (title, message, icon path) are passed via **process environment variables** to completely avoid shell injection and encoding/truncation issues (e.g. UTF-8/GBK encoding clashes).
+   - Maps `replace_id` to the `ToastNotification.Tag` property for in-place card updates.
+   - Gracefully attempts to initialize the ToastNotifier with your custom `app_name`. If it fails (due to unregistered AppUserModelId on older Windows releases), it falls back to a guaranteed registered PowerShell AppID.
+   - If WinRT initialization fails, it falls back to the classic balloon tip (`System.Windows.Forms.NotifyIcon`).
+
+2. **macOS**:
+   - Executes AppleScript (`osascript`) with display notification instructions.
+   - Implements robust escaping for double quotes and backslashes to eliminate script execution failures.
+
+3. **Linux**:
+   - Detects `DISPLAY` and `WAYLAND_DISPLAY` environments.
+   - If GUI is present, uses `notify-send` with a progressive fallback array (peels off unsupported options like `-r` or `-a` step-by-step if the local `notify-send` version is outdated). Falls back to `zenity --notification` if `notify-send` is completely absent.
+   - If headless (no GUI), automatically prints notification details to standard error (`sys.stderr`) to prevent crashes.

yyds_notify_os-0.2.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"

yyds_notify_os-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

yyds_notify_os-0.2.0/setup.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+# -*- coding:utf-8 -*-
+
+from setuptools import setup, find_packages
+from codecs import open
+import os
+
+about = {}
+here = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(here, "yyds_notify_os", "__version__.py"), "r", "utf-8") as f:
+    exec(f.read(), about)
+
+try:
+    with open("README.md", "r", encoding="utf-8") as fh:
+        long_description = fh.read()
+except FileNotFoundError:
+    long_description = about["__description__"]
+
+setup(
+    name=about["__title__"],
+    version=about["__version__"],
+    author=about["__author__"],
+    author_email=about["__author_email__"],
+    description=about["__description__"],
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url=about["__url__"],
+    license=about.get("__license__", "MIT"),
+    packages=find_packages(),
+    include_package_data=True,
+    python_requires='>=3.7',
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Operating System :: OS Independent",
+        "License :: OSI Approved :: MIT License",
+    ],
+    install_requires=[],
+    entry_points={
+        "console_scripts": [
+            "yyds-notify = yyds_notify_os.cli:main",
+            "yyds-notify-os = yyds_notify_os.cli:main",
+        ]
+    },
+)

yyds_notify_os-0.2.0/tests/test_notify.py

@@ -0,0 +1,195 @@
+# -*- coding:utf-8 -*-
+
+import unittest
+from unittest.mock import patch, MagicMock
+import os
+import sys
+import platform
+import base64
+
+# Add the parent directory to Python path to import yyds_notify_os
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from yyds_notify_os.core import notify, _escape_applescript, _send_notification_sync, _resolve_icon_path
+
+
+class TestNotifyOS(unittest.TestCase):
+
+    def test_escape_applescript(self):
+        self.assertEqual(_escape_applescript('hello "world"'), 'hello \\"world\\"')
+        self.assertEqual(_escape_applescript('back\\slash'), 'back\\\\slash')
+        self.assertEqual(_escape_applescript(''), '')
+        self.assertEqual(_escape_applescript(None), '')
+
+    @patch("os.path.exists")
+    def test_resolve_icon_path(self, mock_exists):
+        # 1. File exists locally
+        mock_exists.return_value = True
+        resolved = _resolve_icon_path("myicon.png")
+        self.assertTrue(os.path.isabs(resolved))
+        
+        # 2. File does not exist, not Linux -> returns as-is
+        mock_exists.return_value = False
+        with patch("platform.system", return_value="Windows"):
+            resolved = _resolve_icon_path("non_existent_file.png")
+            self.assertEqual(resolved, "non_existent_file.png")
+            
+        # 3. Linux system icon name (no slashes) -> returns as-is
+        with patch("platform.system", return_value="Linux"):
+            resolved = _resolve_icon_path("dialog-information")
+            self.assertEqual(resolved, "dialog-information")
+
+    def test_notify_invalid_inputs(self):
+        with self.assertRaises(ValueError):
+            notify("", "message")
+        with self.assertRaises(ValueError):
+            notify("title", "")
+        with self.assertRaises(ValueError):
+            notify(None, "message")
+
+    @patch("platform.system")
+    @patch("subprocess.run")
+    def test_linux_notify_send_success(self, mock_run, mock_system):
+        mock_system.return_value = "Linux"
+        mock_run.side_effect = [
+            MagicMock(returncode=0),  # which notify-send
+            MagicMock(returncode=0),  # notify-send with -r
+        ]
+
+        with patch.dict(os.environ, {"DISPLAY": ":0"}):
+            res = _send_notification_sync(
+                "MyTitle", "MyMessage", urgency="critical", timeout=3, app_name="TestApp", replace_id=123
+            )
+            self.assertTrue(res)
+
+        self.assertEqual(mock_run.call_count, 2)
+        called_args = mock_run.call_args_list[1][0][0]
+        self.assertIn("notify-send", called_args)
+        self.assertIn("MyTitle", called_args)
+        self.assertIn("MyMessage", called_args)
+        self.assertIn("-t", called_args)
+        self.assertIn("3000", called_args)
+        self.assertIn("-u", called_args)
+        self.assertIn("critical", called_args)
+        self.assertIn("-a", called_args)
+        self.assertIn("TestApp", called_args)
+        self.assertIn("-r", called_args)
+        self.assertIn("123", called_args)
+
+    @patch("platform.system")
+    @patch("subprocess.run")
+    def test_linux_notify_send_replace_id_fallback(self, mock_run, mock_system):
+        mock_system.return_value = "Linux"
+        mock_run.side_effect = [
+            MagicMock(returncode=0),  # which notify-send
+            MagicMock(returncode=1),  # notify-send with -r (fails)
+            MagicMock(returncode=0),  # fallback notify-send without -r (succeeds)
+        ]
+
+        with patch.dict(os.environ, {"DISPLAY": ":0"}):
+            res = _send_notification_sync("MyTitle", "MyMessage", replace_id=456, fallback_to_print=False)
+            self.assertTrue(res)
+
+        self.assertEqual(mock_run.call_count, 3)
+        called_args_r = mock_run.call_args_list[1][0][0]
+        called_args_fallback = mock_run.call_args_list[2][0][0]
+        self.assertIn("-r", called_args_r)
+        self.assertNotIn("-r", called_args_fallback)
+
+    @patch("platform.system")
+    @patch("subprocess.run")
+    def test_linux_zenity_fallback(self, mock_run, mock_system):
+        mock_system.return_value = "Linux"
+        mock_run.side_effect = [
+            Exception("not found"),   # which notify-send
+            MagicMock(returncode=0),  # which zenity
+            MagicMock(returncode=0),  # zenity command
+        ]
+
+        with patch.dict(os.environ, {"DISPLAY": ":0"}):
+            res = _send_notification_sync("MyTitle", "MyMessage", fallback_to_print=False)
+            self.assertTrue(res)
+
+        self.assertEqual(mock_run.call_count, 3)
+        called_args = mock_run.call_args_list[2][0][0]
+        self.assertIn("zenity", called_args)
+        self.assertIn("--notification", called_args)
+        self.assertIn("--text=<b>MyTitle</b>\nMyMessage", called_args)
+
+    @patch("platform.system")
+    @patch("subprocess.run")
+    @patch("sys.stderr.write")
+    def test_headless_fallback_to_print(self, mock_stderr, mock_run, mock_system):
+        mock_system.return_value = "Linux"
+        
+        with patch.dict(os.environ, {}, clear=True):
+            res = _send_notification_sync("Title", "Message", fallback_to_print=True)
+            self.assertFalse(res)
+            mock_run.assert_not_called()
+            mock_stderr.assert_called_once()
+            written_str = mock_stderr.call_args[0][0]
+            self.assertIn("[Notification] Title: Message", written_str)
+
+    @patch("platform.system")
+    @patch("subprocess.run")
+    def test_mac_osascript(self, mock_run, mock_system):
+        mock_system.return_value = "Darwin"
+        mock_run.return_value = MagicMock(returncode=0)
+
+        res = _send_notification_sync(
+            "Hello", 'World "Quotes"', subtitle="Sub", sound=True
+        )
+        self.assertTrue(res)
+        mock_run.assert_called_once()
+        called_args = mock_run.call_args[0][0]
+        self.assertEqual(called_args[0], "osascript")
+        self.assertEqual(called_args[1], "-e")
+        expected_script = 'display notification "World \\"Quotes\\"" with title "Hello" subtitle "Sub" sound name "Tink"'
+        self.assertEqual(called_args[2], expected_script)
+
+    @patch("platform.system")
+    @patch("subprocess.run")
+    @patch("os.path.exists", return_value=True)
+    def test_windows_powershell(self, mock_exists, mock_run, mock_system):
+        mock_system.return_value = "Windows"
+        mock_run.return_value = MagicMock(returncode=0)
+
+        res = _send_notification_sync("WinTitle", "WinMessage", sound="sms", icon="logo.png", replace_id="task_12")
+        self.assertTrue(res)
+        
+        mock_run.assert_called_once()
+        called_args = mock_run.call_args[0][0]
+        self.assertEqual(called_args[0], "powershell")
+        self.assertEqual(called_args[3], "-EncodedCommand")
+        
+        encoded_data = called_args[4]
+        decoded_script = base64.b64decode(encoded_data).decode("utf-16le")
+        # Check ToastGeneric template check & replace tag & app_name notifier
+        self.assertIn("ToastGeneric", decoded_script)
+        self.assertIn("appLogoOverride", decoded_script)
+        self.assertIn("$toast.Tag = $tag", decoded_script)
+        self.assertIn("CreateToastNotifier($app_name)", decoded_script)
+        
+        env = mock_run.call_args[1]["env"]
+        self.assertEqual(env["NOTIFY_TITLE"], "WinTitle")
+        self.assertEqual(env["NOTIFY_MESSAGE"], "WinMessage")
+        self.assertEqual(env["NOTIFY_APP_NAME"], "yyds-notify")
+        self.assertEqual(env["NOTIFY_SOUND_SRC"], "ms-winsoundevent:Notification.SMS")
+        self.assertEqual(env["NOTIFY_SILENT"], "False")
+        self.assertEqual(env["NOTIFY_TAG"], "task_12")
+        self.assertTrue(os.path.isabs(env["NOTIFY_ICON_PATH"]))
+
+    @patch("threading.Thread")
+    def test_async_non_blocking(self, mock_thread):
+        mock_thread_instance = MagicMock()
+        mock_thread.return_value = mock_thread_instance
+
+        res = notify("Title", "Message", block=False)
+        self.assertTrue(res)
+        mock_thread.assert_called_once()
+        self.assertTrue(mock_thread.call_args[1]["daemon"])
+        mock_thread_instance.start.assert_called_once()
+
+
+if __name__ == "__main__":
+    unittest.main()

yyds_notify_os-0.2.0/yyds_notify_os/__init__.py

@@ -0,0 +1,25 @@
+# -*- coding:utf-8 -*-
+
+from yyds_notify_os.core import notify, show, send
+from yyds_notify_os.__version__ import (
+    __title__,
+    __description__,
+    __version__,
+    __author__,
+    __author_email__,
+    __url__,
+    __license__,
+)
+
+__all__ = [
+    "notify",
+    "show",
+    "send",
+    "__title__",
+    "__description__",
+    "__version__",
+    "__author__",
+    "__author_email__",
+    "__url__",
+    "__license__",
+]

yyds_notify_os-0.2.0/yyds_notify_os/__version__.py

@@ -0,0 +1,9 @@
+#   yyds-notify-os
+
+__title__ = "yyds-notify-os"
+__description__ = "A high-performance, lightweight, and easy-to-use cross-platform desktop notification library for Python."
+__version__ = "0.2.0"
+__author__ = "yyds-fast"
+__author_email__ = "yyds.fast@gmail.com"
+__url__ = "https://github.com/yyds-fast/yyds-notify-os"
+__license__ = "MIT"

yyds_notify_os-0.2.0/yyds_notify_os/cli.py

@@ -0,0 +1,48 @@
+# -*- coding:utf-8 -*-
+
+import argparse
+import sys
+from yyds_notify_os.core import notify
+from yyds_notify_os.__version__ import __version__, __title__
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="A beautiful, cross-platform command line notification tool.",
+        prog="yyds-notify"
+    )
+    parser.add_argument("title", help="Title of the notification")
+    parser.add_argument("message", help="Body/message content of the notification")
+    parser.add_argument("-s", "--subtitle", help="Subtitle (supported on macOS/some Linux setups)")
+    parser.add_argument("-i", "--icon", help="Icon name or image path (Linux/Windows support)")
+    parser.add_argument("-u", "--urgency", choices=["low", "normal", "critical"], default="normal",
+                        help="Urgency level (Linux only, default: normal)")
+    parser.add_argument("-t", "--timeout", type=int, default=5,
+                        help="Notification display timeout in seconds (Linux only, default: 5)")
+    parser.add_argument("--sound", action="store_true", help="Play a notification sound")
+    parser.add_argument("-a", "--app-name", default="yyds-notify", help="Application name (default: yyds-notify)")
+    parser.add_argument("-r", "--replace-id", help="Notification replacement ID to update an existing popup (Linux/Windows only)")
+    parser.add_argument("--async", dest="block", action="store_false", default=True,
+                        help="Send notification asynchronously (non-blocking) in background")
+    parser.add_argument("-v", "--version", action="version", version=f"{__title__} {__version__}")
+
+    args = parser.parse_args()
+
+    success = notify(
+        title=args.title,
+        message=args.message,
+        subtitle=args.subtitle,
+        icon=args.icon,
+        urgency=args.urgency,
+        timeout=args.timeout,
+        sound=args.sound,
+        app_name=args.app_name,
+        replace_id=args.replace_id,
+        block=args.block,
+        fallback_to_print=True
+    )
+    
+    # Return exit code 0 on success, 1 on failure
+    sys.exit(0 if success else 1)
+
+if __name__ == "__main__":
+    main()

yyds_notify_os-0.2.0/yyds_notify_os/core.py

@@ -0,0 +1,399 @@
+# -*- coding:utf-8 -*-
+
+import os
+import sys
+import platform
+import subprocess
+import threading
+import logging
+import base64
+
+logger = logging.getLogger("yyds_notify_os")
+
+# Setup default logger formatting to be simple and clean
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.WARNING)
+
+
+# Windows sound events mapping
+WIN_SOUND_MAP = {
+    "default": "ms-winsoundevent:Notification.Default",
+    "im": "ms-winsoundevent:Notification.IM",
+    "mail": "ms-winsoundevent:Notification.Mail",
+    "reminder": "ms-winsoundevent:Notification.Reminder",
+    "sms": "ms-winsoundevent:Notification.SMS",
+    "alarm": "ms-winsoundevent:Notification.Looping.Alarm",
+    "call": "ms-winsoundevent:Notification.Looping.Call",
+}
+
+
+def _escape_applescript(text: str) -> str:
+    """Escapes string inputs for use in AppleScript double quotes."""
+    if not text:
+        return ""
+    return text.replace('\\', '\\\\').replace('"', '\\"')
+
+
+def _resolve_icon_path(icon: str) -> str:
+    """
+    Resolves icon path to an absolute path if it points to a local file.
+    If it is a Linux system icon name, it is returned as-is.
+    """
+    if not icon:
+        return None
+        
+    # Check if local file exists
+    if os.path.exists(icon):
+        return os.path.abspath(icon)
+        
+    # For Linux, standard icon names are valid (e.g. "dialog-information")
+    if platform.system() == "Linux" and "/" not in icon and "\\" not in icon:
+        return icon
+        
+    return icon
+
+
+def _send_notification_sync(
+    title: str,
+    message: str,
+    subtitle: str = None,
+    icon: str = None,
+    urgency: str = "normal",
+    timeout: int = 5,
+    sound = False,
+    app_name: str = "yyds-notify",
+    replace_id = None,
+    fallback_to_print: bool = True,
+) -> bool:
+    """
+    Synchronously triggers a system notification based on the current platform.
+    Returns True if notification succeeded, False if it failed/fell back.
+    """
+    system = platform.system()
+
+    # Validate urgency
+    urgency = urgency.lower()
+    if urgency not in ("low", "normal", "critical"):
+        urgency = "normal"
+
+    # Resolve icon path
+    icon_path = _resolve_icon_path(icon)
+
+    success = False
+
+    # ----------------------------------------------------
+    # WINDOWS IMPLEMENTATION
+    # ----------------------------------------------------
+    if system == "Windows":
+        # We run PowerShell using environment variables to transfer strings safely
+        # and Base64 EncodedCommand to bypass any complex console escaping problems.
+        app_id = f"{{{os.environ.get('COMPUTERNAME', 'Python-Notify')}}}\\WindowsPowerShell\\v1.0\\powershell.exe"
+        
+        # Map sound to Windows sound events
+        sound_src = ""
+        silent = "True"
+        if sound:
+            silent = "False"
+            if isinstance(sound, str) and sound.lower() in WIN_SOUND_MAP:
+                sound_src = WIN_SOUND_MAP[sound.lower()]
+            else:
+                sound_src = WIN_SOUND_MAP["default"]
+
+        ps_script = """
+        $title = $env:NOTIFY_TITLE
+        $message = $env:NOTIFY_MESSAGE
+        $app_name = $env:NOTIFY_APP_NAME
+        $app_id = $env:NOTIFY_APP_ID
+        $icon_path = $env:NOTIFY_ICON_PATH
+        $sound_src = $env:NOTIFY_SOUND_SRC
+        $silent = $env:NOTIFY_SILENT
+        $tag = $env:NOTIFY_TAG
+
+        try {
+            [void][System.Reflection.Assembly]::LoadWithPartialName('Windows.UI.Notifications')
+            [void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime]
+            
+            # Use ToastGeneric template for rich visual capabilities (supports custom icons)
+            $template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastGeneric)
+            $xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+            $xml.LoadXml($template.GetXml())
+            
+            # Set Title & Message
+            $texts = $xml.GetElementsByTagName("text")
+            if ($texts.Count -gt 0) { $texts.Item(0).AppendChild($xml.CreateTextNode($title)) > $null }
+            if ($texts.Count -gt 1) { $texts.Item(1).AppendChild($xml.CreateTextNode($message)) > $null }
+            
+            # Set Icon (appLogoOverride)
+            if ($icon_path) {
+                $binding = $xml.GetElementsByTagName("binding").Item(0)
+                $imageNode = $xml.CreateElement("image")
+                $imageNode.SetAttribute("placement", "appLogoOverride")
+                $imageNode.SetAttribute("src", $icon_path)
+                $binding.AppendChild($imageNode) > $null
+            }
+            
+            # Configure Sound
+            $toastNode = $xml.GetElementsByTagName("toast").Item(0)
+            $audioNode = $xml.CreateElement("audio")
+            if ($silent -eq "True") {
+                $audioNode.SetAttribute("silent", "true")
+            } else {
+                $audioNode.SetAttribute("silent", "false")
+                if ($sound_src) {
+                    $audioNode.SetAttribute("src", $sound_src)
+                }
+            }
+            $toastNode.AppendChild($audioNode) > $null
+            
+            # Instantiate Toast
+            $toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
+            
+            # Set Tag for replacing/updating notifications
+            if ($tag) {
+                $toast.Tag = $tag
+            }
+            
+            # Try to show notification using custom app name first
+            try {
+                [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($app_name).Show($toast)
+            } catch {
+                # Fallback to the registered PowerShell App ID if the custom name causes issues
+                [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($app_id).Show($toast)
+            }
+            exit 0
+        } catch {
+            # Fallback to legacy System.Windows.Forms.NotifyIcon
+            try {
+                [void][System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms')
+                $notification = New-Object System.Windows.Forms.NotifyIcon
+                $notification.Icon = [System.Drawing.SystemIcons]::Information
+                $notification.BalloonTipTitle = $title
+                $notification.BalloonTipText = $message
+                $notification.Visible = $True
+                $notification.ShowBalloonTip(5000)
+                Start-Sleep -Seconds 1
+                $notification.Dispose()
+                exit 0
+            } catch {
+                exit 1
+            }
+        }
+        """
+        # Prepare environment variables
+        env = os.environ.copy()
+        env["NOTIFY_TITLE"] = title
+        env["NOTIFY_MESSAGE"] = message
+        env["NOTIFY_APP_NAME"] = app_name
+        env["NOTIFY_APP_ID"] = app_id
+        env["NOTIFY_ICON_PATH"] = icon_path if icon_path else ""
+        env["NOTIFY_SOUND_SRC"] = sound_src
+        env["NOTIFY_SILENT"] = silent
+        env["NOTIFY_TAG"] = str(replace_id) if replace_id is not None else ""
+
+        # Encode script in UTF-16LE and Base64 as PowerShell requires
+        encoded_script = base64.b64encode(ps_script.encode("utf-16le")).decode("ascii")
+
+        try:
+            res = subprocess.run(
+                ["powershell", "-NoProfile", "-NonInteractive", "-EncodedCommand", encoded_script],
+                env=env,
+                capture_output=True,
+                creationflags=0x08000000 if hasattr(subprocess, "CREATE_NO_WINDOW") else 0, # CREATE_NO_WINDOW
+            )
+            success = (res.returncode == 0)
+        except Exception as e:
+            logger.debug(f"PowerShell notification failed: {e}")
+            success = False
+
+    # ----------------------------------------------------
+    # MACOS IMPLEMENTATION
+    # ----------------------------------------------------
+    elif system == "Darwin":
+        # AppleScript execution
+        esc_title = _escape_applescript(title)
+        esc_msg = _escape_applescript(message)
+        esc_sub = _escape_applescript(subtitle) if subtitle else None
+        
+        script = f'display notification "{esc_msg}" with title "{esc_title}"'
+        if esc_sub:
+            script += f' subtitle "{esc_sub}"'
+        
+        if sound:
+            sound_name = sound if isinstance(sound, str) else "Tink"
+            script += f' sound name "{sound_name}"'
+            
+        try:
+            res = subprocess.run(["osascript", "-e", script], capture_output=True)
+            success = (res.returncode == 0)
+        except Exception as e:
+            logger.debug(f"AppleScript notification failed: {e}")
+            success = False
+
+    # ----------------------------------------------------
+    # LINUX & OTHER UNIX IMPLEMENTATION
+    # ----------------------------------------------------
+    else:
+        # Detect headless (no DISPLAY or WAYLAND_DISPLAY environment variables)
+        is_headless = not (os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+
+        if not is_headless:
+            # Check availability of notify-send
+            has_notify_send = False
+            try:
+                subprocess.run(["which", "notify-send"], capture_output=True, check=True)
+                has_notify_send = True
+            except Exception:
+                pass
+
+            if has_notify_send:
+                # Progressive fallbacks for notify-send command to maximize compatibility
+                cmds_to_try = []
+                
+                # 1. Full command (with replace_id, app_name, icon, timeout, urgency)
+                cmd_full = ["notify-send", title, message, "-t", str(timeout * 1000), "-u", urgency]
+                if app_name:
+                    cmd_full.extend(["-a", app_name])
+                if icon_path:
+                    cmd_full.extend(["-i", icon_path])
+                if replace_id is not None:
+                    cmd_full.extend(["-r", str(replace_id)])
+                cmds_to_try.append(cmd_full)
+                
+                # 2. Try without replace_id (-r option is not supported on older versions)
+                if replace_id is not None:
+                    cmd_no_r = ["notify-send", title, message, "-t", str(timeout * 1000), "-u", urgency]
+                    if app_name:
+                        cmd_no_r.extend(["-a", app_name])
+                    if icon_path:
+                        cmd_no_r.extend(["-i", icon_path])
+                    cmds_to_try.append(cmd_no_r)
+                    
+                # 3. Try without app_name (-a option might not be supported in some environments)
+                cmd_no_a = ["notify-send", title, message, "-t", str(timeout * 1000), "-u", urgency]
+                if icon_path:
+                    cmd_no_a.extend(["-i", icon_path])
+                cmds_to_try.append(cmd_no_a)
+                
+                # 4. Minimal command (just title and message)
+                cmd_minimal = ["notify-send", title, message]
+                cmds_to_try.append(cmd_minimal)
+                
+                # Execute in sequence until one succeeds
+                for current_cmd in cmds_to_try:
+                    try:
+                        res = subprocess.run(current_cmd, capture_output=True)
+                        if res.returncode == 0:
+                            success = True
+                            break
+                    except Exception as e:
+                        logger.debug(f"Command {' '.join(current_cmd)} failed: {e}")
+
+            # Try zenity fallback if notify-send failed or wasn't available
+            if not success:
+                try:
+                    subprocess.run(["which", "zenity"], capture_output=True, check=True)
+                    
+                    zenity_text = f"<b>{title}</b>\n{message}"
+                    if subtitle:
+                        zenity_text = f"<b>{title}</b>\n<i>{subtitle}</i>\n{message}"
+                    
+                    cmd = ["zenity", "--notification", f"--text={zenity_text}"]
+                    if icon_path:
+                        cmd.append(f"--window-icon={icon_path}")
+                    
+                    res = subprocess.run(cmd, capture_output=True)
+                    success = (res.returncode == 0)
+                except Exception as e:
+                    logger.debug(f"zenity command failed: {e}")
+                    success = False
+
+        else:
+            logger.debug("System is running in headless mode. GUI notifications skipped.")
+            success = False
+
+    # ----------------------------------------------------
+    # DEGRADED FALLBACK
+    # ----------------------------------------------------
+    if not success and fallback_to_print:
+        # Fallback print to terminal or stderr
+        fallback_msg = f"[Notification] {title}"
+        if subtitle:
+            fallback_msg += f" ({subtitle})"
+        fallback_msg += f": {message}"
+        
+        try:
+            sys.stderr.write(fallback_msg + "\n")
+            sys.stderr.flush()
+        except Exception:
+            print(fallback_msg)
+            
+        logger.info(fallback_msg)
+        return False
+
+    return success
+
+
+def notify(
+    title: str,
+    message: str,
+    subtitle: str = None,
+    icon: str = None,
+    urgency: str = "normal",
+    timeout: int = 5,
+    sound = False,
+    app_name: str = "yyds-notify",
+    replace_id = None,
+    block: bool = False,
+    fallback_to_print: bool = True,
+) -> bool:
+    """
+    Sends a cross-platform desktop notification.
+
+    Args:
+        title (str): Title of the notification.
+        message (str): Body text of the notification.
+        subtitle (str, optional): Subtitle of the notification (macOS/zenity fallback support).
+        icon (str, optional): Icon name or path (Linux/Windows/zenity support).
+        urgency (str): Urgency level: 'low', 'normal', 'critical' (Linux support).
+        timeout (int): Expiration timeout in seconds (Linux support). Defaults to 5.
+        sound (bool or str): If True, plays default system sound (macOS/Windows). 
+                             On macOS, can also be a string name of the system sound.
+                             On Windows, can be: 'default', 'im', 'mail', 'reminder', 'sms', 'alarm', 'call'.
+        app_name (str): The application name triggering the notification (Linux/Windows support).
+        replace_id (str or int, optional): A unique ID. If specified, sending a new notification 
+                                           with the same ID will replace/update the existing one.
+        block (bool): If True, block calling thread until notification command finishes.
+                      If False (default), dispatch asynchronously on a daemon thread.
+        fallback_to_print (bool): If True (default), prints notification details to terminal 
+                                  when OS notification fails or under headless environment.
+
+    Returns:
+        bool: True if synchronous invocation succeeded or background thread started, 
+              False otherwise.
+    """
+    if not title:
+        raise ValueError("Notification 'title' cannot be empty.")
+    if not message:
+        raise ValueError("Notification 'message' cannot be empty.")
+
+    args = (title, message, subtitle, icon, urgency, timeout, sound, app_name, replace_id, fallback_to_print)
+
+    if block:
+        return _send_notification_sync(*args)
+    else:
+        # Launch asynchronously in a daemon thread so it is completely non-blocking
+        thread = threading.Thread(
+            target=lambda: _send_notification_sync(*args),
+            daemon=True
+        )
+        thread.start()
+        return True
+
+
+# Convenience aliases
+show = notify
+send = notify

yyds_notify_os-0.2.0/yyds_notify_os.egg-info/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: yyds-notify-os
+Version: 0.2.0
+Summary: A high-performance, lightweight, and easy-to-use cross-platform desktop notification library for Python.
+Home-page: https://github.com/yyds-fast/yyds-notify-os
+Author: yyds-fast
+Author-email: yyds.fast@gmail.com
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-python
+Dynamic: summary
+
+# yyds-notify-os
+
+A high-performance, lightweight, and easy-to-use cross-platform desktop notification library for Python.
+
+[中文说明 (Chinese README)](README_CN.md)
+
+---
+
+## 💡 Key Features
+
+* **Zero External Dependencies**: Implemented strictly using the Python standard library. It interacts with native OS notification tools via subprocesses.
+* **Microsecond-Level Startup**: Highly optimized imports (under 1ms), leaving virtually zero performance footprint.
+* **Non-blocking by Default**: Notifications are dispatched asynchronously in background daemon threads, keeping your application GUI or CLI completely lag-free.
+* **Notification Replacement/Updating (`replace_id`)**: Update an existing notification card in-place (ideal for progress bars or dynamic alerts) without cluttering the Action Center.
+* **Modern Windows Customizations**: Uses Microsoft's modern `ToastGeneric` template to support custom application icons (`icon`) and mapped system sounds (`sound`) or mute configurations.
+* **Path Auto-Resolution**: Automatically converts relative icon paths to absolute paths to prevent subprocess path resolution failures.
+* **Robust Fail-Safe Fallbacks**: Under headless environments (e.g. SSH sessions) or when graphical notifications fail, it gracefully falls back to console stderr output without crashing.
+* **Command Line Interface (CLI)**: Out-of-the-box `yyds-notify` / `yyds-notify-os` commands for shell script integrations.
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install -U yyds-notify-os
+```
+
+Or install from source in editable mode for local development:
+```bash
+pip install -e .
+```
+
+---
+
+## 💻 Python API Usage
+
+```python
+import yyds_notify_os as notify
+import time
+
+# 1. Simple Usage (Non-blocking by default)
+notify.send("Task Complete", "Your compilation has finished successfully!")
+
+# 2. Dynamic Update/Replacement (Same ID updates the same card in-place)
+for i in range(1, 6):
+    notify.send("Downloading", f"Progress: {i*20}%", replace_id="download_task_1")
+    time.sleep(1)
+
+# 3. Synchronous Blocking Call (Returns True/False based on execution success)
+success = notify.send("Server Alert", "CPU temperature is too high!", urgency="critical", block=True)
+
+# 4. Custom Cross-Platform Configuration
+notify.send(
+    title="Meeting Reminder",
+    message="Technical review starts at 2:00 PM",
+    subtitle="Sprint Sync",       # Supported on macOS and Linux-zenity
+    icon="assets/bell.png",       # Automatically converted to absolute path (Windows/Linux)
+    sound="sms",                  # Windows SMS tone mapping, default sound on macOS
+    urgency="normal",             # Linux urgency levels: 'low', 'normal', 'critical'
+    timeout=5,                    # Display timeout in seconds (Linux)
+    app_name="yyds-notify"        # Custom application sender name (Windows/Linux)
+)
+```
+
+### Windows Built-in Sound Mappings (`sound` parameter)
+* `"default"`: Default system sound
+* `"im"`: Instant message sound
+* `"mail"`: Email notification sound
+* `"reminder"`: Calendar reminder sound
+* `"sms"`: SMS/Text message sound
+* `"alarm"`: Looping alarm sound
+* `"call"`: Looping ringtone sound
+
+### API Aliases
+The following functions are identical aliases for convenience:
+* `yyds_notify_os.notify(...)`
+* `yyds_notify_os.send(...)`
+* `yyds_notify_os.show(...)`
+
+---
+
+## 🛠️ CLI Usage
+
+Once installed, send system notifications directly from your shell:
+
+```bash
+# Basic notification
+yyds-notify "Notification" "Your build is ready!"
+
+# Specify custom sender name
+yyds-notify "Alert" "High memory usage detected!" -a "SystemMonitor"
+
+# Dynamic notification updates using replace-id
+yyds-notify "Build Status" "Compiling Module A..." -r "build_job_12"
+yyds-notify "Build Status" "Compiling Module B..." -r "build_job_12"
+
+# Complex call with sound and critical urgency
+yyds-notify "Error" "Deployment failed!" -s "CI Pipeline" -u critical --sound
+
+# View full help menu
+yyds-notify --help
+```
+
+---
+
+## 🛡️ Technical Implementation Details
+
+1. **Windows**:
+   - Uses PowerShell to interface with the Windows Runtime (WinRT) `ToastGeneric` visual template.
+   - All string arguments (title, message, icon path) are passed via **process environment variables** to completely avoid shell injection and encoding/truncation issues (e.g. UTF-8/GBK encoding clashes).
+   - Maps `replace_id` to the `ToastNotification.Tag` property for in-place card updates.
+   - Gracefully attempts to initialize the ToastNotifier with your custom `app_name`. If it fails (due to unregistered AppUserModelId on older Windows releases), it falls back to a guaranteed registered PowerShell AppID.
+   - If WinRT initialization fails, it falls back to the classic balloon tip (`System.Windows.Forms.NotifyIcon`).
+
+2. **macOS**:
+   - Executes AppleScript (`osascript`) with display notification instructions.
+   - Implements robust escaping for double quotes and backslashes to eliminate script execution failures.
+
+3. **Linux**:
+   - Detects `DISPLAY` and `WAYLAND_DISPLAY` environments.
+   - If GUI is present, uses `notify-send` with a progressive fallback array (peels off unsupported options like `-r` or `-a` step-by-step if the local `notify-send` version is outdated). Falls back to `zenity --notification` if `notify-send` is completely absent.
+   - If headless (no GUI), automatically prints notification details to standard error (`sys.stderr`) to prevent crashes.

yyds_notify_os-0.2.0/yyds_notify_os.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+setup.py
+tests/test_notify.py
+yyds_notify_os/__init__.py
+yyds_notify_os/__version__.py
+yyds_notify_os/cli.py
+yyds_notify_os/core.py
+yyds_notify_os.egg-info/PKG-INFO
+yyds_notify_os.egg-info/SOURCES.txt
+yyds_notify_os.egg-info/dependency_links.txt
+yyds_notify_os.egg-info/entry_points.txt
+yyds_notify_os.egg-info/top_level.txt

yyds_notify_os-0.2.0/yyds_notify_os.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

yyds_notify_os-0.2.0/yyds_notify_os.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+yyds-notify = yyds_notify_os.cli:main
+yyds-notify-os = yyds_notify_os.cli:main

yyds_notify_os-0.2.0/yyds_notify_os.egg-info/top_level.txt

@@ -0,0 +1 @@
+yyds_notify_os