High-Level Notification API

def mini(description, applicationName='PythonMini', noteType="Message", 
         title="Mini Message", applicationIcon=None, hostname='localhost', 
         password=None, port=23053, sticky=False, priority=None, 
         callback=None, notificationIcon=None, identifier=None, 
         notifierFactory=GrowlNotifier):
    """
    Single notification function for fire-and-forget notifications.
    
    Parameters:
    - description (str): Notification message (required)
    - applicationName (str): Name of sending application
    - noteType (str): Type of notification
    - title (str): Notification title
    - applicationIcon (str or bytes): Application icon URL or binary data
    - hostname (str): Growl server hostname
    - password (str): Network password for authentication
    - port (int): Growl server port
    - sticky (bool): Make notification sticky
    - priority (int): Priority level (-2 to 2)
    - callback (str): URL callback for notification clicks
    - notificationIcon (str or bytes): Notification-specific icon
    - identifier (str): Coalescing identifier for grouping notifications
    - notifierFactory (class): Factory class for creating notifier instances
    
    Returns:
    bool or tuple: True on success, error tuple on failure
    """

class GrowlNotifier(object):
    """
    Helper class to simplify sending Growl messages.
    
    Attributes:
    - passwordHash (str): Password hash algorithm ('MD5', 'SHA1', 'SHA256', 'SHA512')
    - socketTimeout (int): Socket timeout in seconds (default: 3)
    """
    
    def __init__(self, applicationName='Python GNTP', notifications=[], 
                 defaultNotifications=None, applicationIcon=None, 
                 hostname='localhost', password=None, port=23053):
        """
        Initialize GrowlNotifier instance.
        
        Parameters:
        - applicationName (str): Sending application name
        - notifications (list): List of valid notification types
        - defaultNotifications (list): Notifications enabled by default
        - applicationIcon (str or bytes): Application icon URL or binary data
        - hostname (str): Remote Growl server hostname
        - password (str): Network password for authentication
        - port (int): Remote Growl server port
        """
    
    def register(self):
        """
        Send GNTP Registration to Growl server.
        
        Must be called before sending notifications. Registers the application
        and its supported notification types with the Growl server.
        
        Returns:
        bool or tuple: True on success, error tuple on failure
        
        Raises:
        NetworkError: When connection to Growl server fails
        AuthError: When authentication fails
        ParseError: When server response is invalid
        """
    
    def notify(self, noteType, title, description, icon=None, sticky=False, 
               priority=None, callback=None, identifier=None, custom={}):
        """
        Send a GNTP notification.
        
        Must have registered with Growl beforehand or message will be ignored.
        
        Parameters:
        - noteType (str): Notification type (must be in registered notifications)
        - title (str): Notification title
        - description (str): Main notification content
        - icon (str or bytes): Icon URL or binary data
        - sticky (bool): Make notification sticky
        - priority (int): Message priority (-2 to 2)
        - callback (str): URL callback for notification clicks
        - identifier (str): Coalescing ID for grouping related notifications
        - custom (dict): Custom attributes (keys should have X- prefix)
        
        Returns:
        bool or tuple: True on success, error tuple on failure
        
        Raises:
        AssertionError: When noteType not in registered notifications
        NetworkError: When connection to Growl server fails
        AuthError: When authentication fails
        """
    
    def subscribe(self, id, name, port):
        """
        Send a Subscribe request to remote machine.
        
        Parameters:
        - id (str): Subscriber ID
        - name (str): Subscriber name
        - port (int): Subscriber port
        
        Returns:
        bool or tuple: True on success, error tuple on failure
        """
    
    def add_origin_info(self, packet):
        """
        Add optional Origin headers to GNTP packet.
        
        Headers include machine name, software name/version, and platform info.
        
        Parameters:
        - packet: GNTP packet object to modify
        """
    
    def register_hook(self, packet):
        """
        Hook for modifying registration packets before sending.
        
        Override in subclasses to customize registration behavior.
        
        Parameters:
        - packet: GNTPRegister packet to modify
        """
    
    def notify_hook(self, packet):
        """
        Hook for modifying notification packets before sending.
        
        Override in subclasses to customize notification behavior.
        
        Parameters:
        - packet: GNTPNotice packet to modify
        """
    
    def subscribe_hook(self, packet):
        """
        Hook for modifying subscription packets before sending.
        
        Override in subclasses to customize subscription behavior.
        
        Parameters:
        - packet: GNTPSubscribe packet to modify
        """

import gntp.notifier

# Simple notification with default settings
gntp.notifier.mini("Task completed successfully!")

# Notification with custom title and priority
gntp.notifier.mini(
    "Build finished with 3 warnings",
    title="Build Status",
    priority=1,
    applicationName="Build System"
)

import gntp.notifier

# Create notifier with multiple notification types
app = gntp.notifier.GrowlNotifier(
    applicationName="Task Manager",
    notifications=["Task Started", "Task Completed", "Task Failed"],
    defaultNotifications=["Task Completed", "Task Failed"],
    hostname="localhost",
    password="mypassword"
)

# Register with Growl (required)
result = app.register()
if result is not True:
    print(f"Registration failed: {result}")
    exit(1)

# Send different types of notifications
app.notify("Task Started", "Building project", "Starting compilation...")

app.notify(
    "Task Completed", 
    "Build successful", 
    "Project built in 2.3 seconds",
    priority=1,
    icon="http://example.com/success.png"
)

app.notify(
    "Task Failed",
    "Build failed", 
    "Compilation error in main.py line 42",
    priority=2,
    sticky=True,
    callback="http://example.com/build-log"
)

import gntp.notifier

# URL-based icon
gntp.notifier.mini(
    "New email received",
    title="Email",
    notificationIcon="http://example.com/email-icon.png"
)

# Binary icon data (useful for offline/embedded icons)
with open('/path/to/icon.png', 'rb') as f:
    icon_data = f.read()

gntp.notifier.mini(
    "File saved",
    title="Editor",
    notificationIcon=icon_data
)

import gntp.notifier

app = gntp.notifier.GrowlNotifier(
    applicationName="Download Manager",
    notifications=["Download Progress"]
)
app.register()

# Send progress notifications that replace each other
for progress in [25, 50, 75, 100]:
    app.notify(
        "Download Progress",
        f"Download {progress}% complete",
        f"Downloaded {progress}MB of 100MB",
        identifier="download-123",  # Same ID causes replacement
        custom={
            "X-Progress": str(progress),
            "X-Download-ID": "123"
        }
    )

import gntp.notifier
import gntp.errors

try:
    app = gntp.notifier.GrowlNotifier(hostname="unreachable-host")
    app.register()
except gntp.errors.NetworkError as e:
    print(f"Network error: {e}")
except gntp.errors.AuthError as e:
    print(f"Authentication failed: {e}")
except gntp.errors.ParseError as e:
    print(f"Invalid response from server: {e}")