tessl/pypi-gntp

Growl Notification Transport Protocol for Python

1.25x

Overview

Eval results

Files

Command Line Interface

Name: tessl/pypi-gntp
Rating: 0.8 (1 reviews)
Author: tessl

The gntp.cli module provides a full-featured command-line interface for sending GNTP notifications from shell scripts, system automation, and interactive use. It supports all notification parameters and integrates with the configuration file system.

Capabilities

Command Line Parser

Comprehensive argument parser supporting all GNTP notification options with sensible defaults and configuration file integration.

class ClientParser(OptionParser):
    """
    Command line argument parser for GNTP notifications.
    
    Extends Python's OptionParser with GNTP-specific options organized
    into logical groups: Network Options and Notification Options.
    """
    
    def __init__(self):
        """
        Initialize parser with all GNTP command line options.
        
        Creates option groups for network settings (host, port, password)
        and notification settings (title, message, priority, etc.).
        Reads default values from ~/.gntp configuration file.
        """
    
    def parse_args(self, args=None, values=None):
        """
        Parse command line arguments with GNTP-specific processing.
        
        Handles stdin input for messages, automatic title generation,
        and logging level configuration.
        
        Parameters:
        - args (list): Command line arguments (None for sys.argv)
        - values: Initial option values
        
        Returns:
        tuple: (parsed_options, message_text)
        """

Main Entry Point

Primary function that orchestrates the complete notification workflow from command line arguments to GNTP transmission.

def main():
    """
    Main entry point for GNTP command line interface.
    
    Parses command line arguments, creates GrowlNotifier instance,
    registers with Growl server, handles icon loading, and sends
    the notification. Exits with appropriate status codes on failure.
    
    Command Line Usage:
    gntp [options] [title words...]
    
    Exit Codes:
    - 0: Success
    - Non-zero: Error tuple from failed operation
    """

Command Line Options

Network Options

Control connection to Growl server:

-H, --host HOST: Growl server hostname (default: localhost, or from ~/.gntp)
--port PORT: Growl server port (default: 23053, or from ~/.gntp)
-P, --password PASSWORD: Network authentication password (default: None, or from ~/.gntp)

Notification Options

Control notification appearance and behavior:

-n, --name APP_NAME: Application name (default: 'Python GNTP Test Client')
-N, --notification TYPE: Notification type name (default: 'Notification')
-t, --title TITLE: Notification title (default: command line args or message preview)
-m, --message MESSAGE: Notification message (default: read from stdin)
-p, --priority PRIORITY: Priority level from -2 to 2 (default: 0)
-s, --sticky: Make notification sticky (default: False)
--image PATH_OR_URL: Icon for notification (file path or URL)
--callback URL: Callback URL for notification clicks
-d, --identifier ID: Coalescing identifier for grouping notifications

General Options

-v, --verbose: Increase verbosity (repeat for more verbose output)
--version: Show version information

Usage Examples

Basic Notification

# Simple notification with stdin message
echo "Build completed successfully" | gntp -t "Build Status"

# Direct message without stdin
gntp -m "Server is back online" -t "System Alert"

# Using command line arguments as title
gntp "Deployment Finished" -m "Version 1.2.3 deployed to production"

Network Configuration

# Send to remote Growl server
gntp -H growl.company.com -P mypassword -m "Remote notification"

# Use different port
gntp --host 192.168.1.100 --port 23054 -m "Custom port notification"

Notification Customization

# High priority sticky notification
gntp -p 2 -s -m "Critical system error detected" -t "CRITICAL ALERT"

# Low priority info notification
gntp -p -1 -m "Background task completed" -t "Info"

# Custom application and notification names
gntp -n "Backup System" -N "Backup Complete" -m "Daily backup finished"

Icons and Resources

# URL-based icon
gntp --image "http://example.com/success.png" -m "Operation successful"

# Local file icon
gntp --image "/path/to/warning.png" -m "Warning condition detected"

# File icon with other options
gntp --image ~/icons/error.png -t "Error" -p 2 -s -m "Critical failure"

Callbacks and Coalescing

# Notification with callback URL
gntp --callback "http://example.com/details" -m "Click for details"

# Coalescing notifications (replace previous with same ID)
gntp -d "build-status" -m "Build started..."
gntp -d "build-status" -m "Build 50% complete..."  # Replaces previous
gntp -d "build-status" -m "Build finished!"        # Replaces previous

Interactive Use

# Interactive message input
gntp -t "Manual Message"
# (Enter message, press Ctrl-D to send)

# Combine with other commands
date | gntp -t "Current Time"
uptime | gntp -t "System Status"

Shell Scripting Examples

#!/bin/bash
# Backup notification script

gntp -n "Backup Script" -N "Backup Started" -m "Starting daily backup..."

if backup_command; then
    gntp -n "Backup Script" -N "Backup Success" -p 1 \
         --image ~/icons/success.png \
         -m "Backup completed successfully at $(date)"
else
    gntp -n "Backup Script" -N "Backup Failed" -p 2 -s \
         --image ~/icons/error.png \
         --callback "http://backup.company.com/logs" \
         -m "Backup failed! Check logs for details."
fi

Configuration File Integration

Create ~/.gntp configuration file:

[gntp]
hostname = notifications.company.com
password = enterprise-password
port = 23053

Then use CLI with automatic configuration:

# Automatically uses settings from ~/.gntp
gntp -m "Using enterprise notification server"

# Override specific settings while keeping others from config
gntp -H localhost -m "Use localhost instead of config server"

Build System Integration

# Makefile integration
build-success:
	gntp -n "Build System" -N "Build Success" -p 1 \
	     -m "Project built successfully in $(shell date)"

build-failed:
	gntp -n "Build System" -N "Build Failed" -p 2 -s \
	     --callback "http://buildserver/logs" \
	     -m "Build failed. Click for logs."

# CI/CD pipeline integration
deploy-notify:
	gntp -n "CI/CD Pipeline" -N "Deploy Complete" \
	     --image "http://company.com/deploy-icon.png" \
	     -m "Version ${VERSION} deployed to ${ENVIRONMENT}"

System Monitoring Scripts

#!/bin/bash
# Disk space monitor

USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')

if [ $USAGE -gt 90 ]; then
    gntp -n "System Monitor" -N "Disk Alert" -p 2 -s \
         -t "Disk Space Critical" \
         -m "Root filesystem is ${USAGE}% full"
elif [ $USAGE -gt 80 ]; then
    gntp -n "System Monitor" -N "Disk Warning" -p 1 \
         -t "Disk Space Warning" \
         -m "Root filesystem is ${USAGE}% full"
fi

Error Handling

The CLI handles errors gracefully:

Network failures: Exit with error tuple from underlying GNTP operations
Authentication failures: Exit with authentication error details
Missing configuration: Continues with built-in defaults, logs info message
Invalid arguments: Shows usage help and exits
File not found (for icons): Logs error and continues without icon
Keyboard interrupt: Exits cleanly during stdin input

Installation and Deployment

When installed via pip, the CLI is available as the gntp command:

pip install gntp
gntp --help

For development or custom installations, the CLI can be run as a module:

python -m gntp.cli --help

Integration with Configuration API

The CLI automatically integrates with the gntp.config module:

Reads default values from ~/.gntp configuration file
Command line arguments override configuration file values
Missing configuration file is handled gracefully
Supports all configuration options (hostname, password, port)

This enables enterprise deployments where all CLI usage automatically connects to the correct notification server without requiring command line arguments.

Install with Tessl CLI

npx tessl i tessl/pypi-gntp