# -*- coding: utf-8 -*-
from distutils.core import setup

packages = \
['sitech_notifier',
 'sitech_notifier.delivery',
 'sitech_notifier.migrations',
 'sitech_notifier.templatetags']

package_data = \
{'': ['*'], 'sitech_notifier': ['templates/sitech_notifier/*']}

install_requires = \
['celery>=4.3,<5.0', 'django-render-block>=0.6.0,<0.7.0', 'django>=2.0,<4.0']

extras_require = \
{'realtime': ['pusher>=2.0,<3.0']}

setup_kwargs = {
    'name': 'sitech-notifier',
    'version': '2.0.4',
    'description': 'Notification library for real-time, sms and email notifications',
    'long_description': '# sitech-notifier\n[![CircleCI](https://circleci.com/gh/sitmena/sitech-notifier.svg?style=svg&circle-token=0c83c133f3336982a42c563eb9a29ef21608bdb1)](https://circleci.com/gh/sitmena/sitech-notifier)\n\nOfficial supported notification library for real-time, sms and email with notifications center.\n\n---\n### Requirements\n* Python (3.6, 3.7, 3.8)\n* Django (2.0, 2.1, 2.2, 3.0)\n* Celery\n\n### Installation\n\n1. Install with `pip`:\n   ```\n   pip install sitech-notifier\n   ```\n   If you want to enable real time notifications:\n   ```\n   pip install sitech-notifier[realtime]\n   ```\n2. Modify your `settings.py`:\n   ```python\n   INSTALLED_APPS = [\n       ...,\n       \'sitech_notifier\',\n   ]\n   ```\n3. Run `python manage.py migrate`\n\n---\n## Basic Usage\n\n### Setup\n\nFirst, you have to set up delivery backends in your `settings.py`, for example:\n```python\nSITECH_NOTIFIER_DELIVERY_BACKENDS = [\n    \'sitech_notifier.delivery.backends.EmailDeliveryBackends\',  # default\n    \'sitech_notifier.delivery.backends.PusherBackend\',\n    \'your_app.backends.CustomDeliveryBackend\'\n]\n```\nFor list of built-in delivery backends, go to [Delivery backends](#delivery-backends)\n\n#### Custom delivery backend\nOften you\'ll need custom delivery backend, for example for SMS notifications, or if you\nwant allow users to disable some delivery backends.\n\nTo create custom delivery backend, you can subclass `NotificationDeliveryBackend`.\nOverriding `perform_send` is required, `notification_enabled` is optional.\n\nExample:\n```python\nclass ConcreteSMSBackend(BaseSMSDeliveryBackend):\n    def notification_enabled(self, notification):\n        return notification.user.profile.sms_notifications_enabled\n\n    def perform_send(self, notification):\n        mobile_number = notification.user.profile.mobile_number\n        requests.post(SMS_GATEWAY_URL, {\n            \'api_key\': SMS_GATEWAY_API_KEY,\n            \'mobile_number\': mobile_number,\n            \'message\': notification.full_body_text\n        })\n```\n\n### Defining notifications\nSuppose you want to create a notification  on a new comment on your blog post. First,\nyou have to define a subclass of `BaseNotification`:\n```python\nfrom sitech_notifier.core import BaseNotification\n\nclass BlogPostCommentNotification(BaseNotification):\n    template_name = \'notifications/blog_post_comment.html\'\n    description = \'New comment on a blog post\'\n    notification_type = \'blog_post_comment\'\n```\n\nCheck all notification customization options in [notification factories](#notification-factories)\n\nThen, create file `your_app/templates/notifications/blog_post_comment.html` with\nsuch content:\n```html\n{% block subject %}New comment on a post blog{% endblock subject %}\n{% block short_body %}\n    There is a new comment on your blog post "{{ post.title }}".\n{% endblock short_body %}\n{% block text_body %}\n    Hello, there is a new comment on your blog post "{{ post.title }}".\n{% endblock text_body %}\n{% block html_body %}\n<h4>Hello,</h4>\n<p>\nThere is a new comment on your blog post "{{ post.title }}".\n</p>\n{% endblock html_body %}\n```\n\nThen you have to define an event which will fire the notification, see [events](#events-app) \nfor the details.\n\n### Enabling Pusher notifications\nYou can also want to enable real-time notifications which would appear in application.\n\nAt first, you have to set up Pusher application (visit https://pusher.com)\n\nThen you have to add `PusherDeliveryBackend` to `SITECH_NOTIFIER_DELIVERY_BACKENDS`\nand configure your app settings\n```python\nSITECH_NOTIFIER_DELIVERY_BACKENDS = [\n    ...,\n    \'sitech_notifier.delivery.backends.PusherDeliveryBackends\',\n]\n\nPUSHER_APP_ID = \'app_id\'\nPUSHER_KEY = \'pusher_key\'\nPUSHER_SECRET = \'secret\'\nPUSHER_CLUSTER = \'if-other-than-default-us-east-1\'\n```\n\nThen you have to edit your base template, for example `index.html`:\n```html\n{% load sitech_notifier %}\n...\n<script>\n    const NOTIFICATION_CALLBACK = data => {\n        alert(data.message)\n    };\n</script>\n{% enable_pusher_notifications %}\n```\n\n`NOTIFICATION_CALLBACK` is JS function which is being called when notification\ncomes to the user\'s private channel. Here we used standard JS `alert`, but in practice\nyou will want to use more advanced JS notification like [toastr](https://github.com/CodeSeven/toastr):\n```javascript\ntoastr.info(data.message, "", {\n    onclick: function() {\n      window.location = data.link;\n    }\n});\n```\n\n## Documentation\n\n### Models\n\n #### AbstractNotification\n Source: `sitech_notifier.models.AbstractNotification`\n   \n Base model for notifications, subclass\n this if you need any custom fields and extra data.\n \n **Fields**:\n * `user` - `settings.AUTH_USER_MODEL` foreign key, recipient of the notification\n * `subject` - notification subject, used for email notifications\n * `short_body` - short message of the notification, can be used for real-time in-app\n notifications or inbox page\n * `full_body_txt` - *(optional)* long notification body in plain text. Mainly used for email \n notifications\n * `full_body_html` - *(optional)* long notification body in HTML. Mainly used for email\n notifications\n * `link` - *(optional)* URL to the resource related to the notification.  \n Example use: Notification on new blog post, include blog post URL in the notification\n * `is_new` - Boolean indicating if notification is new. `True` by default.\n \n #### Notification\n Source: `sitech_notifier.models.Notification`\n \n Subclass of `AbstractNotification` with `created_at`, `modified_at` fields and default\n ordering `(-created_at,)`. Use this model if you don\'t need any custom data.\n \n #### Custom notifications\n If you want to create custom notification model, subclass `AbstractNotification` \n and add to `settings.py`:\n ```python\nSITECH_NOTIFIER_NOTIFICATION_MODEL = \'your_app.CustomNotification\'\n```\n \n### Notification factories\nNotification factories are subclasses of `sitech_notifier.notifications.BaseNotification`\nclass. They are used to define specific notification in the application. Calling such\nsubclass creates a notification with all needed data and sends it with Celery\nvia configured delivery backends.\n\nNotification signature: `SpecificNotification(user, event)`  \n`user` and `event` are saved as attributes and accessible through `self`.\n`Event` is an instance of `Event` model.\n\nNotifications should not be called manually, process of sending the notifications\nis handled by events. \nNotifications are sent by emitting an event which registered the notification as callback. See\n[Events](#events-app) for the details.\n\nNotification has to override following attributes:\n* `template_name` - path to the template, see [notification templates](#notification-template)\n* `description` - description what causes the notification, for example:\n"New comment on a blog post"\n* `get_context_from_event(event)` (static method) - get context from `Event` object.\n\nIf notification does not override these attributes and methods, it will be treated as abstract,\nand therefore not be registered in `notification_types`\n\nOptional attributes:\n* `notification_type` - notification type code, for example: `new_blog_post`. Notification\ntype has to be unique, if not defined, it will evaluate to lowercased class name. If\nnotification of such type already exists, `DuplicateNotificationType` will be raised.\n\nMethods (all optional):\n* `get_notification_link(self)` -  get URL linked to the notification, for example:\n`return kwargs[\'blog_post\'].get_absolute_url()`\n\n\n* `get_notification_language(self)` - get language in which notification should be\nrendered, for example: `return self.user.profile.language`. Defaults to \n`settings.LANGUAGE_CODE`\n\n* `transform_html_body(self, html_body)` - transform HTML body before sending,\noverride this if you want for example add CSS to your emails with library such as `premailer`\n\nHelper functions:\n* `sitech_notifier.notifications.get_notification_types()` - get all registered\nnotifications\n\n* `sitech_notifier.notifications.get_notification_description(notification_type)` - get\ndescription of a notification with given type\n\n#### Notification template\nNotification template has to look like this, blocks `subject` and `short_body`\nare required.\n```html\n{% block subject %}{% endblock %}\n{% block short_body %}{% endblock %}\n{% block text_body %}{% endblock %}\n{% block html_body %}{% endblock %}\n```\n\n### Delivery backends\nDelivery backends are subclasses of `NotificationDeliveryBackend` abstract class with\noverridden method `perform_send`.\n\n#### Email backend\nSource: `sitech_notifier.delivery.backends.EmailDeliveryBackend`\n\nSends notification to the user via email, `DEFAULT_FROM_EMAIL` setting is required.\n\n#### SMS backend\nSource: `sitech_notifier.delivery.backends.BaseSMSDeliveryBackend`\n\nThis backend does NOT work out of the box. It needs to be subclassed and `perform_send`\nmethod must be provided.\n\n[Example](#custom-delivery-backend)\n\n#### Pusher delivery backend\nSource: `sitech_notifier.delivery.backends.PusherDeliveryBackend`\n\nSends notification to the user\'s Pusher private channel, making it possible to enable\nreal time in-app notifications.\n\nLibrary also supplies `enable_pusher_notifications` templatetag which should be included\nin the base template. Before using the templatetag, JS function `NOTIFICATION_CALLBACK`\nhas to be defined.\n\nRequired settings:\n * `PUSHER_APP_ID`\n * `PUSHER_KEY`\n * `PUSHER_SECRET`\n\nOptional settings:\n * `PUSHER_CLUSTER` - if other than default `us-east-1`\n * `PUSHER_OPTIONS` - other `kwargs` for `Pusher` instance\n \n Pusher docs: <https://pusher.com/docs/channels>\n \n ## Events\n \n `sitech-notifier` package also ships with events library, which can be used to simplify \n the process of sending notifications. \n \n ### Basic Usage\n \n #### Events\n \n Create `events.py` file in your app and define events:\n \nTo connect notification to the events, use `register_notification` decorator. Decorated function\nshould return a `User` or iterable of users.\n ```python\nfrom sitech_notifier.core import BaseEvent\n\nclass NewBlogPost(BaseEvent):\n    name = \'new-blog-post\'\n\n    @register_notification(NewBlogPostNotification)\n    def notify_new_blog_post(self):\n        post = self.target\n        return post.blog.followers\n\n    @register_notification(PostSubmittedNoification)\n    def notify_post_submitted(self):\n        post = self.target\n        return post.author\n```\nNote that your notification has to override `get_context_from_event` static method.  \nExample:\n```python\nclass NewBlogPostNotification(BaseNotification):\n    ...\n    @staticmethod\n    def get_context_from_event(event):\n        return {\n            \'post\': event.target\n        }\n```\n\nNow, every time `NewBlogPost` is emitted, a notification is sent to all blog `followers`,\nwith `post=post` as a keyword argument.\n\n#### Emitting events\n\nEvents can be emitted with two arguments:\n  * `target` (required) - django `Model` instance which is the target of the self, for example\n  when there is a new post on a blog, blog is the target\n  * `actor` (optional) - django `User` (built-in or custom) instance who fired the \n  notification. Following the example, post author could be the actor, but it\'s\n  possible to retrieve him directly from the target, so it can be skipped.\n  \nEvents are emitted with following call:\n```python\nEvent(target, actor=None).emit()\n```\n\n#### Side effects\n\nEvents can also handle actions which are not related to the notifications. For this purpose,\noverride `side_effects` static method of Event\'s class\n\n```python\nclass CustomEvent(BaseEvent):\n    @staticmethod\n    def side_effects(self):\n        some_side_effect(self)\n```\n',
    'author': 'Norbert Cyran',
    'author_email': 'norbert@ulam.io',
    'url': None,
    'packages': packages,
    'package_data': package_data,
    'install_requires': install_requires,
    'extras_require': extras_require,
    'python_requires': '>=3.6,<4.0',
}


setup(**setup_kwargs)
