0
# Django Notifications HQ
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: django-notifications-hq
7
- **Language**: Python
8
- **Framework**: Django (≥3.2)
9
- **Installation**: `pip install django-notifications-hq`
10

11
## Core Imports
12

13
```python
14
from notifications.models import Notification
15
from notifications.signals import notify
16
```
17

18
Alternative import after Django app is ready:
19

20
```python
21
import notifications
22
# Use notifications.notify after app initialization
23
```
24

25
For template tags:
26

27
```python
28
{% load notifications_tags %}
29
```
30

31
## Basic Usage
32

33
```python
34
from django.contrib.auth.models import User
35
from notifications.signals import notify
36

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

41
# Send a simple notification
42
notify.send(
43
    sender=actor,
44
    recipient=recipient,
45
    verb='followed',
46
    description='John started following you'
47
)
48

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

53
notify.send(
54
    sender=actor,
55
    recipient=recipient,
56
    verb='liked',
57
    target=post,
58
    description='John liked your post'
59
)
60

61
# Access user notifications
62
unread_notifications = recipient.notifications.unread()
63
all_notifications = recipient.notifications.all()
64

65
# Mark notifications as read
66
recipient.notifications.mark_all_as_read()
67
```
68

69
In templates:
70

71
```html
72
<!-- Load template tags -->
73
{% load notifications_tags %}
74

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

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

83
<!-- Live notification badge -->
84
{% live_notify_badge %}
85

86
<!-- Live notification list -->
87
{% live_notify_list %}
88

89
<!-- Register JavaScript callbacks -->
90
{% register_notify_callbacks %}
91
```
92

93
## Architecture
94

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

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

102
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.
103

104
## Capabilities
105

106
### Core Notification System
107

108
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.
109

110
```python { .api }
111
class Notification(AbstractNotification):
112
    def naturalday(self): ...
113
    def naturaltime(self): ...
114

115
class AbstractNotification(models.Model):
116
    level: str
117
    recipient: User
118
    unread: bool
119
    verb: str
120
    description: str
121
    timestamp: datetime
122
    public: bool
123
    deleted: bool
124
    emailed: bool
125
    data: dict
126
    
127
    def mark_as_read(self): ...
128
    def mark_as_unread(self): ...
129
    def timesince(self, now=None): ...
130
    def actor_object_url(self): ...
131
    def action_object_url(self): ...
132
    def target_object_url(self): ...
133

134
class NotificationQuerySet(models.query.QuerySet):
135
    def unread(self, include_deleted=False): ...
136
    def read(self, include_deleted=False): ...
137
    def mark_all_as_read(self, recipient=None): ...
138
    def mark_all_as_unread(self, recipient=None): ...
139
    def deleted(self): ...
140
    def active(self): ...
141
```
142

143
[Core System](./core-system.md)
144

145
### Signal-Based Notification Creation
146

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

149
```python { .api }
150
notify = Signal()
151

152
def notify_handler(verb, **kwargs): ...
153
```
154

155
[Signal System](./signals.md)
156

157
### Web Views and URL Patterns
158

159
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.
160

161
```python { .api }
162
class AllNotificationsList(NotificationViewList): ...
163
class UnreadNotificationsList(NotificationViewList): ...
164

165
def mark_all_as_read(request): ...
166
def mark_as_read(request, slug=None): ...
167
def mark_as_unread(request, slug=None): ...
168
def delete(request, slug=None): ...
169
```
170

171
[Web Interface](./web-interface.md)
172

173
### REST API Endpoints
174

175
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.
176

177
```python { .api }
178
def live_unread_notification_count(request): ...
179
def live_unread_notification_list(request): ...
180
def live_all_notification_count(request): ...
181
def live_all_notification_list(request): ...
182
```
183

184
[API Endpoints](./api-endpoints.md)
185

186
### Template Tags and Frontend Integration
187

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

190
```python { .api }
191
@register.simple_tag
192
def notifications_unread(context): ...
193

194
@register.filter
195
def has_notification(user): ...
196

197
@register.simple_tag
198
def register_notify_callbacks(**kwargs): ...
199

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

203
@register.simple_tag
204
def live_notify_list(list_class='live_notify_list'): ...
205
```
206

207
[Template Integration](./template-integration.md)
208

209
### Utility Functions and Helpers
210

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

213
```python { .api }
214
def get_notification_list(request, method_name='all'): ...
215
def get_num_to_fetch(request): ...
216
def slug2id(slug): ...
217
def id2slug(notification_id): ...
218
```
219

220
[Utilities](./utilities.md)
221

222
### Configuration and Settings
223

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

226
```python { .api }
227
def get_config(): ...
228

229
CONFIG_DEFAULTS = {
230
    'PAGINATE_BY': 20,
231
    'USE_JSONFIELD': False,
232
    'SOFT_DELETE': False,
233
    'NUM_TO_FETCH': 10,
234
    'CACHE_TIMEOUT': 2,
235
}
236
```
237

238
[Configuration](./configuration.md)
239

240
### Django Admin Integration
241

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

244
```python { .api }
245
class NotificationAdmin(AbstractNotificationAdmin):
246
    raw_id_fields: tuple
247
    readonly_fields: tuple
248
    list_display: tuple
249
    list_filter: tuple
250
    actions: list
251

252
def mark_unread(modeladmin, request, queryset): ...
253
```
254

255
[Admin Interface](./admin-integration.md)
256

257
## Types
258

259
```python { .api }
260
from typing import Union, Optional, List, Dict, Any, Literal
261
from django.contrib.auth.models import User, Group
262
from django.db.models import QuerySet
263
from django.contrib.contenttypes.models import ContentType
264

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

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

271
# Generic object reference
272
GenericObject = Any  # Any Django model instance
273
```