or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

admin-integration.mdapi-endpoints.mdconfiguration.mdcore-system.mdindex.mdsignals.mdtemplate-integration.mdutilities.mdweb-interface.md
tile.json

tessl/pypi-django-notifications-hq

GitHub notifications alike app for Django providing comprehensive activity tracking and notification features.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/django-notifications-hq@1.8.x

To install, run

npx @tessl/cli install tessl/pypi-django-notifications-hq@1.8.0

index.mddocs/

Django Notifications HQ

A comprehensive Django package that provides GitHub-style notification functionality for web applications. This library enables developers to implement activity tracking, user notifications, and social interaction features using Django's built-in systems and conventions.

Package Information

  • Package Name: django-notifications-hq
  • Language: Python
  • Framework: Django (≥3.2)
  • Installation: pip install django-notifications-hq

Core Imports

from notifications.models import Notification
from notifications.signals import notify

Alternative import after Django app is ready:

import notifications
# Use notifications.notify after app initialization

For template tags:

{% load notifications_tags %}

Basic Usage

from django.contrib.auth.models import User
from notifications.signals import notify

# Get users
actor = User.objects.get(username='john')
recipient = User.objects.get(username='jane')

# Send a simple notification
notify.send(
    sender=actor,
    recipient=recipient,
    verb='followed',
    description='John started following you'
)

# Send notification with target object
from myapp.models import Post
post = Post.objects.get(id=1)

notify.send(
    sender=actor,
    recipient=recipient,
    verb='liked',
    target=post,
    description='John liked your post'
)

# Access user notifications
unread_notifications = recipient.notifications.unread()
all_notifications = recipient.notifications.all()

# Mark notifications as read
recipient.notifications.mark_all_as_read()

In templates:

<!-- Load template tags -->
{% load notifications_tags %}

<!-- Display unread count -->
<span class="badge">{% notifications_unread %}</span>

<!-- Check if user has notifications -->
{% if user|has_notification %}
    <div class="notification-indicator">!</div>
{% endif %}

<!-- Live notification badge -->
{% live_notify_badge %}

<!-- Live notification list -->
{% live_notify_list %}

<!-- Register JavaScript callbacks -->
{% register_notify_callbacks %}

Architecture

Django Notifications HQ is built around four core components following the Activity Streams specification:

  • Actor: The user or object that performed the action
  • Verb: The action that was performed (e.g., "liked", "followed", "commented")
  • Action Object: Optional object linked to the action (e.g., a comment, post)
  • Target: Optional object the action was performed on (e.g., a post that was liked)

The system uses Django's GenericForeignKey to reference any model as actor, action object, or target, providing maximum flexibility. Notifications are stored in a single table with efficient indexing for recipient and read status queries.

Capabilities

Core Notification System

The foundational notification models, queryset methods, and signal handling that power the entire system. Includes the main Notification model with fields for actor, verb, target, timestamps, and read status.

class Notification(AbstractNotification):
    def naturalday(self): ...
    def naturaltime(self): ...

class AbstractNotification(models.Model):
    level: str
    recipient: User
    unread: bool
    verb: str
    description: str
    timestamp: datetime
    public: bool
    deleted: bool
    emailed: bool
    data: dict
    
    def mark_as_read(self): ...
    def mark_as_unread(self): ...
    def timesince(self, now=None): ...
    def actor_object_url(self): ...
    def action_object_url(self): ...
    def target_object_url(self): ...

class NotificationQuerySet(models.query.QuerySet):
    def unread(self, include_deleted=False): ...
    def read(self, include_deleted=False): ...
    def mark_all_as_read(self, recipient=None): ...
    def mark_all_as_unread(self, recipient=None): ...
    def deleted(self): ...
    def active(self): ...

Core System

Signal-Based Notification Creation

Django signal system for creating notifications with flexible actor-verb-object patterns. Supports individual users, groups, and querysets as recipients with automatic notification creation.

notify = Signal()

def notify_handler(verb, **kwargs): ...

Signal System

Web Views and URL Patterns

Pre-built Django views for displaying, managing, and interacting with notifications through web interfaces. Includes list views, mark-as-read functionality, and deletion with proper URL routing.

class AllNotificationsList(NotificationViewList): ...
class UnreadNotificationsList(NotificationViewList): ...

def mark_all_as_read(request): ...
def mark_as_read(request, slug=None): ...
def mark_as_unread(request, slug=None): ...
def delete(request, slug=None): ...

Web Interface

REST API Endpoints

JSON API endpoints for real-time notification features including unread counts, notification lists, and AJAX-powered live updates for single-page applications and mobile apps.

def live_unread_notification_count(request): ...
def live_unread_notification_list(request): ...
def live_all_notification_count(request): ...
def live_all_notification_list(request): ...

API Endpoints

Template Tags and Frontend Integration

Django template tags for displaying notification counts, status indicators, and live-updating notification interfaces with JavaScript integration for real-time updates.

@register.simple_tag
def notifications_unread(context): ...

@register.filter
def has_notification(user): ...

@register.simple_tag
def register_notify_callbacks(**kwargs): ...

@register.simple_tag
def live_notify_badge(context, badge_class='live_notify_badge'): ...

@register.simple_tag
def live_notify_list(list_class='live_notify_list'): ...

Template Integration

Utility Functions and Helpers

Helper functions for formatting notifications, converting IDs to URL-safe slugs, and retrieving notification data for API responses with configurable limits and pagination.

def get_notification_list(request, method_name='all'): ...
def get_num_to_fetch(request): ...
def slug2id(slug): ...
def id2slug(notification_id): ...

Utilities

Configuration and Settings

Configurable settings for pagination, soft deletion, JSON field usage, caching, and other behavioral options with sensible defaults and Django settings integration.

def get_config(): ...

CONFIG_DEFAULTS = {
    'PAGINATE_BY': 20,
    'USE_JSONFIELD': False,
    'SOFT_DELETE': False,
    'NUM_TO_FETCH': 10,
    'CACHE_TIMEOUT': 2,
}

Configuration

Django Admin Integration

Admin interface configuration for managing notifications with proper field displays, filtering options, and bulk actions for administrative oversight and debugging.

class NotificationAdmin(AbstractNotificationAdmin):
    raw_id_fields: tuple
    readonly_fields: tuple
    list_display: tuple
    list_filter: tuple
    actions: list

def mark_unread(modeladmin, request, queryset): ...

Admin Interface

Types

from typing import Union, Optional, List, Dict, Any, Literal
from django.contrib.auth.models import User, Group
from django.db.models import QuerySet
from django.contrib.contenttypes.models import ContentType

# Recipient types
Recipient = Union[User, Group, QuerySet, List[User]]

# Notification levels
NotificationLevel = Literal['success', 'info', 'warning', 'error']

# Generic object reference
GenericObject = Any  # Any Django model instance