skip to navigation
skip to content

Not Logged In

django-notifications-hq 0.6.0

GitHub notifications alike app for Django.

Django Notifications Documentation

`django-notifications <>`_ is a GitHub notification alike app for Django, it was derived from `django-activity-stream <>`_

Notifications are actually actions events, which are categorized by four main components.

 * ``Actor``. The object that performed the activity.
 * ``Verb``. The verb phrase that identifies the action of the activity.
 * ``Action Object``. *(Optional)* The object linked to the action itself.
 * ``Target``. *(Optional)* The object to which the activity was performed.

``Actor``, ``Action Object`` and ``Target`` are ``GenericForeignKeys`` to any arbitrary Django object.
An action is a description of an action that was performed (``Verb``) at some instant in time by some ``Actor`` on some optional ``Target`` that results in an ``Action Object`` getting created/updated/deleted.

For example: `justquick <>`_ ``(actor)`` *closed* ``(verb)`` `issue 2 <>`_ ``(object)`` on `activity-stream <>`_ ``(target)`` 12 hours ago

Nomenclature of this specification is based on the Activity Streams Spec: `<>`_


Installation is easy using ``pip`` and will install all required libraries.


    $ pip install django-notifications-hq

or get it from source


    $ git clone
    $ cd django-notifications
    $ python install

Note that `django-model-utils <>`_ will be installed: this is required for the pass-through QuerySet manager.

Then to add the Django Notifications to your project add the app ``notifications`` to your ``INSTALLED_APPS`` and urlconf.

The app should go somewhere after all the apps that are going to be generating notifications like ``django.contrib.auth``::


Add the notifications urls to your urlconf::

    import notifications

    urlpatterns = patterns('',
        ('^inbox/notifications/', include(notifications.urls)),

The method of installing these urls, importing rather than using ``'notifications.urls'``, is required to ensure that the urls are installed in the ``notifications`` namespace.

How to migrate schema to 0.5.5

#. Install latest version `django-south <>`_
#. Execute `` migrate notifications --fake 0001`` command to initiate django-notifications migrate history
#. Execute `` migrate notifications`` to migrate django-notifications schema

Generating Notifications

Generating notifications is probably best done in a separate signal.


    from django.db.models.signals import post_save
    from notifications import notify
    from myapp.models import MyModel

    def my_handler(sender, instance, created, **kwargs):
        notify.send(instance, verb='was saved')

    post_save.connect(my_handler, sender=MyModel)

To generate an notification anywhere in your code, simply import the notify signal and send it with your actor, recipient, verb, and target.


    from notifications import notify

    notify.send(recipient=user, recipient=user, verb='you reached level 10')

    notify.send(comment.user, recipient=user, verb=u'replied', action_object=comment,
                description=comment.comment, target=comment.content_object)

    notify.send(follow_instance.user, recipient=follow_instance.follow_object, verb=u'has followed you',
                action_object=instance, description=u'', target=follow_instance.follow_object)

Extra data

You can attach arbitrary data to your notifications by doing the following:

  * Install a compatible JSONField application.
  * Add to your ``NOTIFY_USE_JSONFIELD=True``

Then, any extra arguments you pass to ``notify.send(...)`` will be attached to the ``.data`` attribute of the notification object. These will be serialised using the JSONField's serialiser, so you may need to take that into account: using only objects that will be serialised is a good idea.


QuerySet methods

Using ``django-model-utils``, we get the ability to add queryset methods to not only the manager, but to all querysets that will be used, including related objects. This enables us to do things like::


which returns all unread notifications. To do this for a single user, we can do::

  user = User.objects.get(pk=pk)

There are some other QuerySet methods, too.


Return all of the unread notifications, filtering the current queryset.


Return all of the read notifications, filtering the current queryset.

``qs.mark_all_as_read()`` | ``qs.mark_all_as_read(recipient)``

Mark all of the unread notifications in the queryset (optionally also filtered by ``recipient``) as read.

``qs.mark_all_as_unread()`` | ``qs.mark_all_as_unread(recipient)``

Mark all of the read notifications in the queryset (optionally also filtered by ``recipient``) as unread.

Model methods


A wrapper for Django's ``timesince`` function.


Mark the current object as read.

Template tags

Put `{% load notifications_tags %}` in the template before you actually use notification tags.



    {% notifications_unread %}

Give the number of unread notifications for a user, or nothing (an empty string) for an anonymous user.

Storing the count in a variable for further processing is advised, such as::

    {% notifications_unread as unread_count %}
    {% if unread_count %}
        You have <strong>{{ unread_count }}</strong> unread notifications.
    {% endif %}
File Type Py Version Uploaded on Size
django-notifications-hq-0.6.0.tar.gz (md5) Source 2013-03-06 10KB
  • Downloads (All Versions):
  • 54 downloads in the last day
  • 146 downloads in the last week
  • 515 downloads in the last month