Metadata-Version: 2.1
Name: django-snitch
Version: 1.0
Summary: Django app made to integrate generic events that create notifications that
Home-page: https://github.com/marcosgabarda/django-snitch
License: UNKNOWN
Author: Marcos Gabarda
Author-email: hey@marcosgabarda.com
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: License :: OSI Approved :: MIT License
Requires-Dist: django
Requires-Dist: django-model-utils
Requires-Dist: django-push-notifications
Requires-Dist: bleach
Requires-Dist: celery
Requires-Dist: sphinx; extra == "doc"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-django; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: factory_boy; extra == "test"
Provides-Extra: doc
Provides-Extra: test

=============
Django Snitch
=============

.. image:: https://travis-ci.org/marcosgabarda/django-snitch.svg?branch=master
    :target: https://travis-ci.org/marcosgabarda/django-snitch

.. image:: https://coveralls.io/repos/github/marcosgabarda/django-snitch/badge.svg?branch=master
    :target: https://coveralls.io/github/marcosgabarda/django-snitch?branch=master

Django app made to integrate generic events that create notifications that
can be sent to users using several backends.

By default, it integrates **push notifications** and **email** to send the
notifications.

Made with Python 3 and Django with :heart:.

Quick start
-----------

**1** Install using pip:

.. code-block:: bash

    pip install django-snitch

**2** Add "snitch" to your INSTALLED_APPS settings like this:

.. code-block:: python

    INSTALLED_APPS += ('snitch',)

**3** Create an ``events.py`` file in your app to register the events:

.. code-block:: python

    import snitch
    from snitch.backends import PushNotificationBackend, EmailNotificationBackend

    ACTIVATED_EVENT = "activated"
    CONFIRMED_EVENT = "confirmed"


    @snitch.register(ACTIVATED_EVENT)
    class ActivatedHandler(snitch.EventHandler):
        title = "Activated!"


    @snitch.register(CONFIRMED_EVENT)
    class ConfirmedHandler(snitch.EventHandler):
        title = "Confirmed!"
        notification_backends = [PushNotificationBackend, EmailNotificationBackend]

        # Custom configuration for email backend
        template_email_kwargs = {"template_name": "email.html"}
        template_email_async = False

        def audience(self):
            return get_user_model().objects.all()


**4** Use ``dispatch`` decorator to dispatch the event when a function is called:

.. code-block:: python

    from django.db import models
    from django.utils import timezone

    import snitch
    from snitch.models import AbstractNotification
    from tests.app.events import ACTIVATED_EVENT, CONFIRMED_EVENT


    class Stuff(models.Model):
        """Simple stuff model with status."""

        IDLE, ACTIVE, CONFIRMED = 0, 1, 2
        status = models.PositiveIntegerField(default=IDLE)
        activated_at = models.DateTimeField(null=True, blank=True)
        confirmed_at = models.DateTimeField(null=True, blank=True)

        @snitch.dispatch(ACTIVATED_EVENT)
        def activate(self):
            self.activated_at = timezone.now()

        @snitch.dispatch(CONFIRMED_EVENT)
        def confirm(self):
            self.confirmed_at = timezone.now()


Custom Notification model
-------------------------

You can, in the same way that ``django.contrib.auth.model.User`` works, swap the
Notification model, to customize it.

In order to do thar, you should create a model that inherits from
``AbstractNotification``:

.. code-block:: python

    from django.db import models

    from snitch.models import AbstractNotification


    class Notification(AbstractNotification):
        """Custom notification."""

        extra_field = models.BooleanField(default=False)


An after that, specify it in the settings:

.. code-block:: python

    SNITCH_NOTIFICATION_MODEL = "app.Notification"

