Django Growl Notifier

Send Django development server notifications to Growl (or compatible notification systems like Growl for Windows, Snarl, or prowlnotify).

✨ Features

• 🚀 Automatic notifications when Django server starts
• 🔥 Error notifications with detailed stacktrace
• 🌐 Multiple Growl hosts support - broadcast to multiple machines
• 🎨 Custom icons support for notifications
• ⚙️ Easy configuration - minimal setup required
• 🎯 Manual notifications - trigger notifications anywhere in your code
• 🔇 Silent mode - disable notifications when needed
• 📝 Detailed logging - track notification delivery

📦 Installation

Via pip

pip install django-growl-notifier

From source

git clone https://github.com/cumulus13/django-growl-notifier.git
cd django-growl-notifier
pip install -e .

🚀 Quick Setup

1. Add to INSTALLED_APPS

Add django_growl to your INSTALLED_APPS in settings.py:

INSTALLED_APPS = [
    # ... your other apps
    'django_growl',
]

2. Configure Growl Hosts

Add Growl configuration to your settings.py:

# Required: List of Growl hosts (IP:PORT or just IP)
GROWL_HOSTS = [
    '127.0.0.1:23053',        # Local machine
    '192.168.1.100:23053',    # Remote machine on network
]

# Optional settings
GROWL_APP_NAME = 'My Django App'  # Default: 'Django Server'
GROWL_ENABLED = True              # Default: True

3. Run Your Server

# Option 1: Use regular runserver (with auto-notify)
python manage.py runserver

# Option 2: Use custom command with explicit notification
python manage.py runserver_growl

# Option 3: Specify address and port
python manage.py runserver 0.0.0.0:8000

You'll see a Growl notification when the server starts! 🎉

⚙️ Configuration

All Available Settings

# settings.py

# ============================================
# REQUIRED SETTINGS
# ============================================

# List of Growl notification hosts
# Format: 'IP:PORT' or 'IP' (defaults to port 23053)
GROWL_HOSTS = [
    '127.0.0.1:23053',
    '192.168.1.50',  # Will use port 23053
]

# ============================================
# OPTIONAL SETTINGS
# ============================================

# Application name displayed in Growl
GROWL_APP_NAME = 'Django Server'  # Default

# Enable or disable all notifications
GROWL_ENABLED = True  # Default

# Custom icon for notifications
# Supports: file path, file:// URI, or http(s):// URL
GROWL_ICON = '/path/to/your/icon.png'

# Enable error notifications via middleware
GROWL_NOTIFY_ERRORS = True  # Default

# Make error notifications sticky (stay visible)
GROWL_STICKY_ERRORS = True  # Default

# Make server start notifications sticky
GROWL_STICKY_SERVER = False  # Default

Icon Configuration

Django Growl Notifier supports custom icons for notifications:

# Use a local file
GROWL_ICON = '/path/to/django-logo.png'

# Use file URI
GROWL_ICON = 'file:///path/to/icon.png'

# Use HTTP URL (if Growl supports it)
GROWL_ICON = 'https://example.com/icon.png'

Icon Priority:

1. Parameter passed to send_notification(icon=...)
2. GROWL_ICON environment variable
3. GROWL_ICON in settings.py
4. Default icon.png in package directory

📖 Usage

Automatic Server Start Notifications

Notifications are sent automatically when you start the Django development server:

$ python manage.py runserver
System check identified no issues (0 silenced).
December 03, 2025 - 11:35:30
Django version 5.2.8, using settings 'myproject.settings'
Starting development server at http://127.0.0.1:8000/
✓ Growl notification sent to 2 host(s)
Quit the server with CONTROL-C.

Error Notifications with Middleware

Get notified automatically when errors occur in your Django application.

Setup:

Add the middleware to your settings.py:

MIDDLEWARE = [
    # ... your other middleware
    'django_growl.middleware.GrowlErrorMiddleware',
]

# Optional: Configure error notification behavior
GROWL_NOTIFY_ERRORS = True      # Enable error notifications
GROWL_STICKY_ERRORS = True      # Make error notifications sticky

What you get:

• Automatic notifications on 500 errors
• Full exception details and stacktrace
• Request path and HTTP method
• Sticky notifications (so you don't miss them)

Manual Notifications

Send custom notifications from anywhere in your Django code:

from django_growl import send_notification

# Basic notification
send_notification(
    title="Task Complete",
    message="Database backup finished successfully"
)

# With all options
send_notification(
    title="User Registration",
    message="New user: [email protected]",
    note_type='Info',          # 'Info', 'Error', or 'Server Status'
    sticky=True,               # Keep notification visible
    icon='/path/to/icon.png'   # Custom icon for this notification
)

Use Cases:

• Celery task completion
• Scheduled job notifications
• Custom admin actions
• Database migrations
• Deployment scripts

Programmatic Control

from django_growl import get_growl_notifier

# Get the notifier instance
notifier = get_growl_notifier()

# Check if enabled
if notifier.enabled:
    notifier.notify(
        title="Custom Alert",
        message="Something important happened",
        note_type='Info',
        sticky=False
    )

🎨 Examples

Example 1: Task Completion in Views

from django.shortcuts import render
from django_growl import send_notification
from .models import Report

def generate_report(request):
    # Generate report
    report = Report.objects.create(...)
    
    # Notify via Growl
    send_notification(
        title="Report Generated",
        message=f"Report #{report.id} is ready for download",
        sticky=True
    )
    
    return render(request, 'report.html', {'report': report})

Example 2: Celery Task Notification

from celery import shared_task
from django_growl import send_notification

@shared_task
def process_large_dataset(dataset_id):
    # Process data...
    result = do_processing(dataset_id)
    
    # Notify when complete
    send_notification(
        title="Processing Complete",
        message=f"Dataset {dataset_id} processed: {result.count} records",
        note_type='Info'
    )
    
    return result

Example 3: Management Command

from django.core.management.base import BaseCommand
from django_growl import send_notification

class Command(BaseCommand):
    help = 'Cleanup old data'
    
    def handle(self, *args, **options):
        # Cleanup logic
        deleted_count = cleanup_old_data()
        
        # Notify
        send_notification(
            title="Cleanup Complete",
            message=f"Removed {deleted_count} old records"
        )
        
        self.stdout.write(self.style.SUCCESS('Done!'))

Example 4: Custom Admin Action

from django.contrib import admin
from django_growl import send_notification

@admin.register(MyModel)
class MyModelAdmin(admin.ModelAdmin):
    actions = ['export_selected']
    
    def export_selected(self, request, queryset):
        count = queryset.count()
        # Export logic...
        
        send_notification(
            title="Export Complete",
            message=f"Exported {count} items",
            sticky=True
        )
        
        self.message_user(request, f"Exported {count} items")
    
    export_selected.short_description = "Export selected items"

🔧 Troubleshooting

Notifications Not Appearing

1. Check if Growl is running:

   # Windows: Check Task Manager for Growl.exe
   # Mac: Check if Growl is running in menu bar

2. Verify network connectivity:

   # Test if port is open
   telnet 192.168.1.100 23053

3. Check Django logs:

   # settings.py - Enable debug logging
   LOGGING = {
       'version': 1,
       'handlers': {
           'console': {'class': 'logging.StreamHandler'},
       },
       'loggers': {
           'django_growl': {
               'handlers': ['console'],
               'level': 'DEBUG',
           },
       },
   }

4. Verify settings:

   # In Django shell
   from django.conf import settings
   print(settings.GROWL_HOSTS)
   print(settings.GROWL_ENABLED)

Common Issues

Issue: "Failed to register Growl notifier"

• Solution: Check if Growl is accepting network notifications. Enable "Listen for incoming notifications" in Growl settings.

Issue: Notifications work locally but not on remote hosts

• Solution: Check firewall settings. Port 23053 must be open on remote machines.

Issue: Icons not showing

• Solution: Verify icon path exists and is accessible. Use absolute paths or URIs.

Issue: Too many notifications during development

• Solution: Temporarily disable:

  GROWL_ENABLED = False

🔍 Advanced Usage

Environment Variable Override

You can override settings using environment variables:

# Disable notifications temporarily
export GROWL_ENABLED=false
python manage.py runserver

# Use custom icon
export GROWL_ICON=/path/to/custom-icon.png
python manage.py runserver

Multiple Notification Types

from django_growl import send_notification

# Info notification (default)
send_notification("Task Done", "Completed successfully", note_type='Info')

# Error notification
send_notification("Task Failed", "Error occurred", note_type='Error')

# Server status notification
send_notification("Server Event", "Config reloaded", note_type='Server Status')

Conditional Notifications

from django.conf import settings
from django_growl import send_notification

def my_view(request):
    # Only notify in development
    if settings.DEBUG:
        send_notification("Debug", "View accessed")
    
    # Only notify for specific users
    if request.user.is_staff:
        send_notification("Admin Action", f"{request.user} performed action")

🧪 Testing

# Install dev dependencies
pip install -e .[dev]

# Run tests
python -m pytest

# With coverage
python -m pytest --cov=django_growl

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📋 Requirements

• Python >= 3.8
• Django >= 3.2
• gntp >= 1.0.3
• version_get
• Growl for Windows, Growl (macOS), or compatible notification system use GNTP

📄 Documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Hadi Cahyadi

• Email: [email protected]
• GitHub: @cumulus13

💖 Support

If you find this project helpful, please consider supporting:

🙏 Acknowledgments

• Thanks to the Growl team for the notification system
• Thanks to the Django community for the excellent web framework
• Built with ❤️ by developers, for developers

📚 Related Projects

• gntp - Growl Notification Transport Protocol library
• django-notifications - Generic notification system for Django
• Growl for Windows - Windows implementation of Growl

---

Star ⭐ this repo if you find it useful!