Usage Guide

This guide covers different ways to use Django Growl Notifier.

Automatic Notifications

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.

You can also use the explicit command:

python manage.py runserver_growl

Error Notifications

Configure middleware in settings.py:

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

GROWL_NOTIFY_ERRORS = True
GROWL_STICKY_ERRORS = True

Now you’ll receive notifications for all 500 errors with:

  • Full exception details

  • Stack trace

  • Request path and method

  • Sticky notifications (won’t disappear)

Manual Notifications

Basic Notification

Send a simple notification:

from django_growl import send_notification

send_notification(
    title="Task Complete",
    message="Your data has been processed successfully"
)

With All Options

Use all available options:

from django_growl import send_notification

send_notification(
    title="User Registration",
    message="New user registered: john@example.com",
    note_type='Info',          # 'Info', 'Error', 'Server Status'
    sticky=True,               # Keep notification visible
    icon='/path/to/icon.png'   # Custom icon
)

Notification Types

Three types of notifications are available:

# Info notification (default)
send_notification(
    title="Information",
    message="Task completed",
    note_type='Info'
)

# Error notification
send_notification(
    title="Error Occurred",
    message="Failed to process data",
    note_type='Error'
)

# Server status notification
send_notification(
    title="Server Event",
    message="Configuration reloaded",
    note_type='Server Status'
)

Programmatic Control

Get Notifier Instance

Access the notifier directly:

from django_growl import get_growl_notifier

notifier = get_growl_notifier()

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

Check Configuration

from django_growl import get_growl_notifier

notifier = get_growl_notifier()

print(f"Enabled: {notifier.enabled}")
print(f"App Name: {notifier.app_name}")
print(f"Hosts: {notifier.growl_hosts}")
print(f"Registered: {len(notifier.notifiers)} host(s)")

Conditional Notifications

Based on Environment

from django.conf import settings
from django_growl import send_notification

def my_task():
    result = do_something()

    # Only notify in development
    if settings.DEBUG:
        send_notification(
            title="Task Result",
            message=f"Processed {result.count} items"
        )

Based on User

def admin_action(request):
    # Process something

    # Notify only for staff users
    if request.user.is_staff:
        send_notification(
            title="Admin Action",
            message=f"{request.user.username} performed action"
        )

Integration Examples

With Django Views

from django.shortcuts import render
from django_growl import send_notification

def generate_report(request):
    # Generate report
    report = Report.objects.create(
        title="Monthly Report",
        data=get_report_data()
    )

    # Notify
    send_notification(
        title="Report Generated",
        message=f"Report '{report.title}' is ready",
        sticky=True
    )

    return render(request, 'report.html', {
        'report': report
    })

With Celery Tasks

from celery import shared_task
from django_growl import send_notification

@shared_task
def process_large_dataset(dataset_id):
    try:
        # Process data
        result = do_heavy_processing(dataset_id)

        # Notify success
        send_notification(
            title="Processing Complete",
            message=f"Dataset {dataset_id}: {result.count} records",
            note_type='Info'
        )

    except Exception as e:
        # Notify error
        send_notification(
            title="Processing Failed",
            message=f"Dataset {dataset_id}: {str(e)}",
            note_type='Error',
            sticky=True
        )
        raise

With Management Commands

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):
        deleted_count = cleanup_old_data()

        send_notification(
            title="Cleanup Complete",
            message=f"Removed {deleted_count} old records"
        )

        self.stdout.write(
            self.style.SUCCESS(f'Cleaned up {deleted_count} records')
        )

With Django Signals

from django.db.models.signals import post_save
from django.dispatch import receiver
from django_growl import send_notification
from .models import Order

@receiver(post_save, sender=Order)
def order_created(sender, instance, created, **kwargs):
    if created and instance.total > 1000:
        send_notification(
            title="Large Order Created",
            message=f"Order #{instance.id}: ${instance.total}",
            sticky=True
        )

Best Practices

  1. Use appropriate notification types

    • 'Info' for general notifications

    • 'Error' for errors and failures

    • 'Server Status' for server events

  2. Use sticky notifications wisely

    • Sticky for important errors

    • Non-sticky for routine updates

  3. Don’t spam notifications

    • Aggregate similar notifications

    • Use conditions to filter unnecessary alerts

  4. Test in development first

    • Verify notifications work before production

    • Use environment-specific settings

  5. Handle exceptions

    • Notification failures shouldn’t break your app

    • The library handles this automatically

Next Steps