| Name | wc-django-notifications JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | |
| Summary | Modular notifications system for your django applications. |
| upload_time | 2023-06-21 15:27:31 |
| maintainer | |
| docs_url | None |
| author | WebCase |
| requires_python | >=3.6 |
| license | MIT License |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Django notifications
Modular notifications system for your django applications.
## Installation
```sh
pip install wc-django-notifications
```
In `settings.py`:
```python
INSTALLED_APPS += [
# ...
'wcd_notifications',
]
WCD_NOTIFICATIONS = {
# Resolving function to get recipients from request.
# Using mostly by API.
'RECIPIENTS_RESOLVER': 'wcd_notifications.utils.default_resolve_recipients',
# Pipeline functions for additional notifications instances preparation.
'PREPARATION_PIPELINE': [],
# Pipeline functions that handle notification flag changes.
'CHANGE_FLAG_PIPELINE': [
# Resolves readability flags intersection.
'wcd_notifications.services.manager.set_readability_flags_operation',
],
}
```
## Usage
### Sending notifications
```python
from wcd_notifications.services import notifier
notifications = notifier.send(
# Simple formattable string.
# `.format` method will be applied during `send` event.
# For example:
'{actor} created new {action} after leaving {target}.',
# Recipient objects list.
[user1, user2],
# Optional. Object that performed activity.
actor=None,
# Optional. Action object, that was performed.
action=None,
# Optional. Target object to which the activity was performed.
target=None,
# Parent notification. If exists.
parent=None,
# Initial flags that a message will have.
flags=[],
# Some extra data that will be stored in json field.
extra={},
# Recipients can receive this message after some time.
send_at=None,
# Can send with different current time.
now=None,
batch_size=None,
)
```
Notifications send method has several breakpoints on which you may add additional handlers for a common situations:
1. Each notification separately will run preparation pipeline from `Notification.preparator`. It's an instances of `px_pipline.Filter` so you may add or remove them.
2. Then preparation pipeline from `settings.PREPARATION_PIPELINE` will be run on all new notification instances.
3. Notifications will be created.
4. For each notification `wcd_notifications.signals.notification_sent` will be sent.
4. For all new notifications `wcd_notifications.signals.notifications_sent` will be sent.
5. There is already one `wcd_notifications.signals.notifications_sent` signal reciever. It will recollect stats for all the recipients that new notifications has.
### Notification state management
You may change flags in three different ways:
- `add` - List of flags to add.
- `remove` - List of flags to remove.
- `specify` - List of flags to set hard. `add` and `remove` parameters i this case will be ignored.
```python
from wcd_notifications.services import manager
# For example we need to mark some notifications as `read`:
manager.change_flags(
Notification.objects.all(),
add=[Notification.Readability.READ],
# Empty specify list will be ignored.
specify=[],
)
```
Only read/unread flags are not enough. And you may use any numbers you wish as flags. It would be better to use `django.db.models.IntegerChoices` or at least `enum.Enum` to define different state groups.
And it will be better if library could know about your flags.
For this case there is a simple flags registry:
```python
from enum import Enum
from wcd_notifications.models import Notification
class OtherOptions(int, Enum):
ONE = 1
TWO = 2
# By running this command you register your flags:
Notification.flags_registry.add(OtherOptions)
```
Flags change method also has it's own breakpoints to extend:
1. After all flag changes applied, but not saved pipeline from `settings.CHANGE_FLAG_PIPELINE` runs.
2. All notification flags changes are saved to database.
3. Signal `wcd_notifications.signals.notifications_flags_changed` sent.
3. Signal `wcd_notifications.signals.notifications_updated` sent.
### Querying
Notifications queryset has additional methods, for easier querying:
```python
from wcd_notifications.models import Notification
qs = (
Notification.objects
# To find only read notifications.
.read()
# To find only new notifications.
.unread()
# To filter by recipients:
.recipients([])
# Actors:
.actors([])
# Actions:
.actions([])
# Targets:
.targets([])
# To display only already sent messages.
.sent(now=None)
)
```
### Stats
Reading information about notifications state is far more frequent action, that notifications change/sending. So library "caches" state data into database and updates it after any change occured.
There is only one simple SELECT operation to get state for any recipients:
```python
from wcd_notifications.models import Stats
# For one recipient there is at most one stats object exists.
user_stats = Stats.objects.recipients([user]).first()
```
Collecting stats are automatically happens in management methods. But there could be cases when notifications are updated by hand. In that case you should collect stats manually:
```python
from wcd_notifications.services import manager
# You may pass a recipients list here or manual `None` if stats for all
# recipients must be updated.
manager.collect_stats([user1])
```
## Contrib
### DRF
There are ready for use frontend for django rest framework.
```python
INSTALLED_APPS += [
# ...
'wcd_notifications.contrib.drf',
# Django filters required for api to work.
'django_filters',
'rest_framework',
]
In `urls.py`:
```python
from wcd_notifications.contrib.drf.views import make_urlpatterns
urlpatters = [
...
path('api/v1/notifications/', include(make_urlpatterns(
# Here you can replace any view by your own customized one.
))),
]
```
It will add 5 views there:
#### `GET[/api/v1/notifications/flags/list/]`
Returns list of all available flags.
#### `GET[/api/v1/notifications/notifications/list/]`
Paginatable list of notifications.
To be able to display related objects in more detailed manner you may also register serializers that will be used for each object of a particular model:
```python
from wcd_notifications.contrib.drf.serializers import FIELD_SERIALIZERS
from .models import SomeModel
from .serializers import SomeModelSerializer
# So for any object of `SomeModel` `SomeModelSerializer` will be used to
# display `props` in notifications list view.
FIELD_SERIALIZERS.add(SomeModel, SomeModelSerializer)
```
Also notifications messages can have shortcodes from `wc-shortcodes` and will be transformed during render. You only need to register your custom shortodes:
```python
from wcd_notifications.contrib.drf.serializers import SHORTCODES_REGISTRY
@SHORTCODES_REGISTRY.register()
def shortcode(entity, context={}):
return entity.content
```
Filters that can be applied:
- **ids**: List of identifiers to filter over:
`&ids=1,2,3&ids=4,6` - There can be mutiple same named fields. Comma ',' could be also a separator for multiple values. Or operator used for all identifiers.
- **actors**: List of actors to filter on:
`&actors=auth.user~1,auth.user~2&actors=auth.user~4` - There can be mutiple same named fields. Comma ',' could be also a separator for multiple values. Or operator used for all identifiers.
One value to filter on is: `{object_type}~{object_id}`.
- **actions**: Same as **actors**.
- **targets**: Same as **actors**.
- **actor_types**: List of types for filter on:
`&actor_types=auth.user,muapp.mymodel&actor_types=otherapp.othermodel` - There can be mutiple same named fields. Comma ',' could be also a separator for multiple values. Or operator used for all identifiers.
- **action_types**: Same as **actor_types**.
- **target_types**: Same as **actor_types**.
- **sent_at_before**: Filter by the time >= notification was sent. ISO datetime.
- **sent_at_after**: Filter by the time <= notification was sent. ISO datetime.
- **is_sent**: Get only already sent notifications.
- **is_root**: Since notifications are hierarchical you may only need a root notifications.
- **parents**: List of parent identifiers to filter over:
`&parents=1,2,3&parents=4,6` - There can be mutiple same named fields. Comma ',' could be also a separator for multiple values. Or operator used for all identifiers.
- **flags**: Filtering over flags is not that simple OR statement.
`&flags=1,2,3&flags=4,6` - Each comma ',' separated list considered as AND comparison. Or operator used between multiple `flags` fields.
So this example will lead to `(1 or 2 or 3) and (4 or 6)` comparison statement.
#### `POST[/api/v1/notifications/notifications/set-flags/]`
To add specific flags to notifications(like `read` for example) you can use this method.
Notifications can be filtered the same way as in `/notifications/list/` view.
Under the hood it uses `manager.change_flags` method, so data it requires works the same:
```json
{
"add": [1,2,4],
"remove": [6],
"specify": []
}
```
#### `POST[/api/v1/notifications/notifications/clear/]`
This view deletes notifications by your will. What notifications should be deleted can be filtered the same way as in `/notifications/list/` view.
#### `GET[/api/v1/notifications/notifications/stats/]`
Here user can get a notifications statistics. There will be a list for each recipient that current authorization resolves in.
Each recipient stats contains total count of notifications and notification counts for every flag exists in their notifications.
So this way you will find all read/unread messages for example.
Filters that can be applied:
- **actor_types**: List of types for filter on:
`&actor_types=auth.user,muapp.mymodel&actor_types=otherapp.othermodel` - There can be mutiple same named fields. Comma ',' could be also a separator for multiple values. Or operator used for all identifiers.
- **action_types**: Same as **actor_types**.
- **target_types**: Same as **actor_types**.
By applying filters you receive statistics data only for affected notifications.
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [0.3.1]
### Fixed
- Attempts to collect stats for `None` recipients.
### Added
- Management command to clear notifications and stats.
## [0.3.0]
### Changed
- Internal stats collect implementation.
### Added
- Management command to recollect stats.
- Notification stats filtering.
## [0.2.0]
### Changed
- Past form of verb "send" changed everywhere from "sended" to "sent".
### Removed
- Removed explicit `pagination_class` from notifications list view.
### Fixed
- Small fixes.
## [0.1.3]
### Fixed
- Django 2.2 compatibility.
## [0.1.1]
Initial version.
Raw data
{
"_id": null,
"home_page": "",
"name": "wc-django-notifications",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "WebCase",
"author_email": "info@webcase.studio",
"download_url": "https://files.pythonhosted.org/packages/17/72/63cf43032f0df309893c09f8a98c5286b85fbe5406b3290a9fabec16ed94/wc-django-notifications-0.3.1.tar.gz",
"platform": null,
"description": "# Django notifications\n\nModular notifications system for your django applications.\n\n## Installation\n\n```sh\npip install wc-django-notifications\n```\n\nIn `settings.py`:\n\n```python\nINSTALLED_APPS += [\n # ...\n 'wcd_notifications',\n]\n\nWCD_NOTIFICATIONS = {\n # Resolving function to get recipients from request.\n # Using mostly by API.\n 'RECIPIENTS_RESOLVER': 'wcd_notifications.utils.default_resolve_recipients',\n # Pipeline functions for additional notifications instances preparation.\n 'PREPARATION_PIPELINE': [],\n # Pipeline functions that handle notification flag changes.\n 'CHANGE_FLAG_PIPELINE': [\n # Resolves readability flags intersection.\n 'wcd_notifications.services.manager.set_readability_flags_operation',\n ],\n}\n```\n\n## Usage\n\n### Sending notifications\n\n```python\nfrom wcd_notifications.services import notifier\n\n\nnotifications = notifier.send(\n # Simple formattable string.\n # `.format` method will be applied during `send` event.\n # For example:\n '{actor} created new {action} after leaving {target}.',\n # Recipient objects list.\n [user1, user2],\n # Optional. Object that performed activity.\n actor=None,\n # Optional. Action object, that was performed.\n action=None,\n # Optional. Target object to which the activity was performed.\n target=None,\n # Parent notification. If exists.\n parent=None,\n # Initial flags that a message will have.\n flags=[],\n # Some extra data that will be stored in json field.\n extra={},\n # Recipients can receive this message after some time.\n send_at=None,\n # Can send with different current time.\n now=None,\n batch_size=None,\n)\n```\n\nNotifications send method has several breakpoints on which you may add additional handlers for a common situations:\n\n1. Each notification separately will run preparation pipeline from `Notification.preparator`. It's an instances of `px_pipline.Filter` so you may add or remove them.\n2. Then preparation pipeline from `settings.PREPARATION_PIPELINE` will be run on all new notification instances.\n3. Notifications will be created.\n4. For each notification `wcd_notifications.signals.notification_sent` will be sent.\n4. For all new notifications `wcd_notifications.signals.notifications_sent` will be sent.\n5. There is already one `wcd_notifications.signals.notifications_sent` signal reciever. It will recollect stats for all the recipients that new notifications has.\n\n### Notification state management\n\nYou may change flags in three different ways:\n\n- `add` - List of flags to add.\n- `remove` - List of flags to remove.\n- `specify` - List of flags to set hard. `add` and `remove` parameters i this case will be ignored.\n\n```python\nfrom wcd_notifications.services import manager\n\n\n# For example we need to mark some notifications as `read`:\nmanager.change_flags(\n Notification.objects.all(),\n add=[Notification.Readability.READ],\n # Empty specify list will be ignored.\n specify=[],\n)\n```\n\nOnly read/unread flags are not enough. And you may use any numbers you wish as flags. It would be better to use `django.db.models.IntegerChoices` or at least `enum.Enum` to define different state groups.\n\nAnd it will be better if library could know about your flags.\n\nFor this case there is a simple flags registry:\n\n```python\nfrom enum import Enum\n\nfrom wcd_notifications.models import Notification\n\n\nclass OtherOptions(int, Enum):\n ONE = 1\n TWO = 2\n\n\n# By running this command you register your flags:\nNotification.flags_registry.add(OtherOptions)\n```\n\nFlags change method also has it's own breakpoints to extend:\n\n1. After all flag changes applied, but not saved pipeline from `settings.CHANGE_FLAG_PIPELINE` runs.\n2. All notification flags changes are saved to database.\n3. Signal `wcd_notifications.signals.notifications_flags_changed` sent.\n3. Signal `wcd_notifications.signals.notifications_updated` sent.\n\n### Querying\n\nNotifications queryset has additional methods, for easier querying:\n\n```python\nfrom wcd_notifications.models import Notification\n\n\nqs = (\n Notification.objects\n # To find only read notifications.\n .read()\n # To find only new notifications.\n .unread()\n # To filter by recipients:\n .recipients([])\n # Actors:\n .actors([])\n # Actions:\n .actions([])\n # Targets:\n .targets([])\n # To display only already sent messages.\n .sent(now=None)\n)\n```\n\n### Stats\n\nReading information about notifications state is far more frequent action, that notifications change/sending. So library \"caches\" state data into database and updates it after any change occured.\n\nThere is only one simple SELECT operation to get state for any recipients:\n\n```python\nfrom wcd_notifications.models import Stats\n\n\n# For one recipient there is at most one stats object exists.\nuser_stats = Stats.objects.recipients([user]).first()\n```\n\nCollecting stats are automatically happens in management methods. But there could be cases when notifications are updated by hand. In that case you should collect stats manually:\n\n```python\nfrom wcd_notifications.services import manager\n\n\n# You may pass a recipients list here or manual `None` if stats for all\n# recipients must be updated.\nmanager.collect_stats([user1])\n```\n\n## Contrib\n\n### DRF\n\nThere are ready for use frontend for django rest framework.\n\n```python\nINSTALLED_APPS += [\n # ...\n 'wcd_notifications.contrib.drf',\n\n # Django filters required for api to work.\n 'django_filters',\n 'rest_framework',\n]\n\nIn `urls.py`:\n\n```python\nfrom wcd_notifications.contrib.drf.views import make_urlpatterns\n\nurlpatters = [\n ...\n path('api/v1/notifications/', include(make_urlpatterns(\n # Here you can replace any view by your own customized one.\n ))),\n]\n```\n\nIt will add 5 views there:\n\n#### `GET[/api/v1/notifications/flags/list/]`\n\nReturns list of all available flags.\n\n#### `GET[/api/v1/notifications/notifications/list/]`\n\nPaginatable list of notifications.\n\nTo be able to display related objects in more detailed manner you may also register serializers that will be used for each object of a particular model:\n\n```python\nfrom wcd_notifications.contrib.drf.serializers import FIELD_SERIALIZERS\n\nfrom .models import SomeModel\nfrom .serializers import SomeModelSerializer\n\n\n# So for any object of `SomeModel` `SomeModelSerializer` will be used to\n# display `props` in notifications list view.\nFIELD_SERIALIZERS.add(SomeModel, SomeModelSerializer)\n```\n\nAlso notifications messages can have shortcodes from `wc-shortcodes` and will be transformed during render. You only need to register your custom shortodes:\n\n```python\nfrom wcd_notifications.contrib.drf.serializers import SHORTCODES_REGISTRY\n\n\n@SHORTCODES_REGISTRY.register()\ndef shortcode(entity, context={}):\n return entity.content\n```\n\nFilters that can be applied:\n\n- **ids**: List of identifiers to filter over:\n\n `&ids=1,2,3&ids=4,6` - There can be mutiple same named fields. Comma ',' could be also a separator for multiple values. Or operator used for all identifiers.\n\n- **actors**: List of actors to filter on:\n\n `&actors=auth.user~1,auth.user~2&actors=auth.user~4` - There can be mutiple same named fields. Comma ',' could be also a separator for multiple values. Or operator used for all identifiers.\n\n One value to filter on is: `{object_type}~{object_id}`.\n\n- **actions**: Same as **actors**.\n- **targets**: Same as **actors**.\n- **actor_types**: List of types for filter on:\n\n `&actor_types=auth.user,muapp.mymodel&actor_types=otherapp.othermodel` - There can be mutiple same named fields. Comma ',' could be also a separator for multiple values. Or operator used for all identifiers.\n\n- **action_types**: Same as **actor_types**.\n- **target_types**: Same as **actor_types**.\n- **sent_at_before**: Filter by the time >= notification was sent. ISO datetime.\n- **sent_at_after**: Filter by the time <= notification was sent. ISO datetime.\n- **is_sent**: Get only already sent notifications.\n- **is_root**: Since notifications are hierarchical you may only need a root notifications.\n- **parents**: List of parent identifiers to filter over:\n\n `&parents=1,2,3&parents=4,6` - There can be mutiple same named fields. Comma ',' could be also a separator for multiple values. Or operator used for all identifiers.\n- **flags**: Filtering over flags is not that simple OR statement.\n\n `&flags=1,2,3&flags=4,6` - Each comma ',' separated list considered as AND comparison. Or operator used between multiple `flags` fields.\n\n So this example will lead to `(1 or 2 or 3) and (4 or 6)` comparison statement.\n\n#### `POST[/api/v1/notifications/notifications/set-flags/]`\n\nTo add specific flags to notifications(like `read` for example) you can use this method.\n\nNotifications can be filtered the same way as in `/notifications/list/` view.\n\nUnder the hood it uses `manager.change_flags` method, so data it requires works the same:\n\n```json\n{\n \"add\": [1,2,4],\n \"remove\": [6],\n \"specify\": []\n}\n```\n\n#### `POST[/api/v1/notifications/notifications/clear/]`\n\nThis view deletes notifications by your will. What notifications should be deleted can be filtered the same way as in `/notifications/list/` view.\n\n#### `GET[/api/v1/notifications/notifications/stats/]`\n\nHere user can get a notifications statistics. There will be a list for each recipient that current authorization resolves in.\n\nEach recipient stats contains total count of notifications and notification counts for every flag exists in their notifications.\n\nSo this way you will find all read/unread messages for example.\n\nFilters that can be applied:\n\n- **actor_types**: List of types for filter on:\n\n `&actor_types=auth.user,muapp.mymodel&actor_types=otherapp.othermodel` - There can be mutiple same named fields. Comma ',' could be also a separator for multiple values. Or operator used for all identifiers.\n\n- **action_types**: Same as **actor_types**.\n- **target_types**: Same as **actor_types**.\n\nBy applying filters you receive statistics data only for affected notifications.\n# Changelog\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n## [0.3.1]\n### Fixed\n- Attempts to collect stats for `None` recipients.\n### Added\n- Management command to clear notifications and stats.\n\n## [0.3.0]\n### Changed\n- Internal stats collect implementation.\n### Added\n- Management command to recollect stats.\n- Notification stats filtering.\n\n## [0.2.0]\n### Changed\n- Past form of verb \"send\" changed everywhere from \"sended\" to \"sent\".\n### Removed\n- Removed explicit `pagination_class` from notifications list view.\n### Fixed\n- Small fixes.\n\n## [0.1.3]\n### Fixed\n- Django 2.2 compatibility.\n\n## [0.1.1]\nInitial version.\n\n\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Modular notifications system for your django applications.",
"version": "0.3.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "177263cf43032f0df309893c09f8a98c5286b85fbe5406b3290a9fabec16ed94",
"md5": "bab372d5fe99b77488ec8f4dcca85879",
"sha256": "549660ea9f8f4a9226a44673b133a7cc15df9a4616b26870f4a61b247c62d72b"
},
"downloads": -1,
"filename": "wc-django-notifications-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "bab372d5fe99b77488ec8f4dcca85879",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 43211,
"upload_time": "2023-06-21T15:27:31",
"upload_time_iso_8601": "2023-06-21T15:27:31.822857Z",
"url": "https://files.pythonhosted.org/packages/17/72/63cf43032f0df309893c09f8a98c5286b85fbe5406b3290a9fabec16ed94/wc-django-notifications-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-21 15:27:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "wc-django-notifications"
}
